repo-cartographer

repo-cartographer

60 秒了解任意代码库。 一个 MCP 服务，可将任意仓库转换为架构图。

让大模型读取一个文件夹，即可获得架构图谱：语言、框架、入口点、模块和导入关系图，并以 Mermaid 图表形式呈现，可直接放入 PR、文档或入门指南。

它与模型无关。它通过标准输入输出使用 Model Context Protocol，因此可与 Claude Code、Claude Desktop、Cursor、Cline、Copilot 或 OpenAI Agents SDK 配合使用，不依赖 Claude。

有何不同

服务提取确凿事实，模型负责推理。

repo-cartographer 从不试图从语义层面“理解”你的代码。它会解析确定性事实——文件树、导入关系、清单文件、框架检测结果和入口点——并将结构化 JSON 以及一张草稿图表交给大模型。模型会根据这些事实生成最终说明，并完善图表。

这种分工让服务保持精简、快速、可测试且易于移植，也确保图表基于仓库中的实际内容，而非凭空编造。

输出示例

针对此仓库运行 generate_diagram 后生成的结果（模型随后会完善这张草稿）：

flowchart TD
    n0["src · 2 files"]
    n1["src/lib · library code · 9 files"]
    n2["src/resources · resource handlers · 1 file"]
    n3["src/tools · tool implementations · 4 files"]
    n0 --> n1
    n0 --> n2
    n0 --> n3
    n1 --> n0
    n3 --> n0
    n3 --> n1

examples/ 下提交了一个独立且易于分享的 HTML 渲染页面（包含高层视图和文件级 detail 视图）。

安装与运行

需要 Node.js 18+。

# Run directly (no install)
npx -y repo-cartographer

# …or from source
git clone https://github.com/builditwithgk/repo-cartographer
cd repo-cartographer
npm install
npm run build
node dist/index.js

服务通过标准输入输出通信；AI 客户端会以这种方式启动它。你也可以直接在终端中使用它——请参阅下文。

命令行（无需 AI）

同一个二进制文件支持双模式：不带参数时作为 MCP 服务；带子命令时则作为供用户和 CI 使用的普通命令行工具。

# Draw a diagram — path in, architecture.html out
npx -y repo-cartographer map ./my-project
npx -y repo-cartographer map ./my-project --level detail -o docs/architecture
npx -y repo-cartographer map ./my-project --format dot   # Graphviz DOT instead of Mermaid

# Enforce architecture rules (exits 1 on an error-level violation — use it in CI)
npx -y repo-cartographer check ./my-project --config .cartographer.yml

兼容 ZIP：如果将其指向解压后的“Download ZIP”文件夹（包括 repo-main/ 外层目录），它会检测该外层目录并映射到真实仓库根目录——并在输出中注明，绝不会静默处理。

两种输出格式，同一套策略：使用 Mermaid，因为大家都在这里阅读（GitHub 会在 PR 评论和 README 中原生渲染它）；使用 DOT，因为工具都能读取它（可通过管道传给 Graphviz、Backstage 或其他工具：dot -Tsvg architecture.dot）。两种格式都附带同一张可分享的 HTML 页面和按角色着色的模块。如果仓库中有 .cartographer.yml，其 diagram: 部分会提供 --level、--format 和 -o 的默认值；显式传入的标志始终优先。

check 会读取规则文件，并标记禁止的跨边界导入和依赖循环——结果是确定性的，不涉及大模型，因此可安全地用于合并门禁：

# .cartographer.yml
rules:
  forbidden:
    - from: "src/ui/**"
      to:   "src/db/**"
      reason: "UI must go through the service layer, not the DB directly."
  cycles: error        # error | warn | off

要在现有代码库中采用？ 记录当前违规项作为已接受的基线，这样只有新增违规才会导致构建失败：

npx -y repo-cartographer check . --update-baseline   # writes .cartographer-baseline.json

提交该文件；之后运行时会自动检测它，除非 PR 引入了新的违规项，否则检查都会通过。

在 CI 中进行架构治理（GitHub Action）

一个复合操作（action.yml）会在每个 PR 上运行 check——遇到错误级别违规时构建失败，并发布一条置顶评论，其中包含图表和所有违规项：

# .github/workflows/architecture.yml
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: builditwithgk/repo-cartographer@v1
        with: { path: ., config: .cartographer.yml }

本仓库通过 .github/workflows/architecture.yml 实际使用此操作。 完整设计与阶段说明：docs/github-action.md。

与 Claude Code 配合使用

claude mcp add repo-cartographer -- npx -y repo-cartographer

然后提问：“使用 repo-cartographer 绘制 ./my-project 的地图，并为我画一张架构图。”

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "repo-cartographer": {
      "command": "npx",
      "args": ["-y", "repo-cartographer"]
    }
  }
}

将其与 OpenAI Agents SDK 配合使用

同一个服务，不同的模型——这正是 MCP 的意义所在：

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        params={"command": "npx", "args": ["-y", "repo-cartographer"]},
    ) as cartographer:
        agent = Agent(
            name="Cartographer",
            instructions=(
                "Use the repo tools to gather facts, then refine the draft "
                "Mermaid diagram into a clean architecture map."
            ),
            mcp_servers=[cartographer],
        )
        result = await Runner.run(agent, "Map ./my-project and explain its architecture.")
        print(result.final_output)

asyncio.run(main())

工具与资源

工具	返回内容
map_repo(path, level?, format?, outPath?)	一站式流程。 指定一个文件夹，即可在一次调用中获取可下载的架构图（architecture.html + .mermaid/.dot）、事实摘要以及内联的草稿源代码。
scan_repo(path)	语言、框架、入口点、顶层模块（含角色推测）以及清单摘要——以 JSON 事实形式返回。
build_import_graph(path)	JS/TS + Python 的仓库内部 import/require 边。节点为文件；对于大型仓库，会自动折叠到模块级别。
generate_diagram(path, level?, format?)	草稿图表。level = "high"（模块，默认值）或 "detail"（按模块分组的文件）；format = "mermaid"（默认值）或 "dot"（Graphviz）。
render_diagram(source, outPath, format?)	写入一个自包含、带样式的 .html（通过 CDN 渲染：Mermaid 或用于 DOT 的 Viz），以及原始的 .mermaid/.dot 文件。

资源
about://author	作者介绍及联系方式（Markdown）。

大多数情况下，你只需要 map_repo——“输入路径，输出图表”。只有当你想自行组合步骤时（例如，让模型在 generate_diagram 和 render_diagram 之间完善图表源代码），才使用这四个细分工具。

如何在大型仓库中保持快速

• 语言： JavaScript/TypeScript 和 Python（v1）。
• 跳过 node_modules、.git、dist、build、venv、__pycache__、vendor 以及其他构建/依赖/缓存目录（还有所有隐藏目录）。
• 限制扫描的文件数量和每个文件读取的字节数；超过阈值后，将导入图折叠到目录级别。任何受限项都会在输出中报告——绝不会静默丢弃。
• 扫描时不进行网络调用。（只有当你在浏览器中打开渲染后的 HTML 时，它才会从 CDN 加载 Mermaid。）
• **结果具有确定性：**输出经过排序且稳定，因此图表不会在不同运行之间反复变化。

开发

npm run dev        # run from source with tsx
npm run build      # type-check + emit to dist/
npm test           # unit tests (node:test, no build step needed)
npm run typecheck  # type-check src/ and test/ together, no emit

测试覆盖确定性核心功能——导入解析（JS/TS + Python）、模块折叠、循环检测、规则 glob、基线差异比较、Mermaid 渲染以及端到端 check 流程。测试通过 tsx 针对 src/ 运行，因此无需构建步骤，也不依赖测试框架。

作者

由 Gopi K Aitham (builditwithgk) 构建——请参阅 about://author，或访问 scaleup-solutions.in。承接 AI、Agent 和 MCP 工具方面的自由职业及合同项目。

许可证

MIT