repo-cartographer

repo-cartographer

あらゆるコードベースを60秒で把握できます。 任意のリポジトリをアーキテクチャ図に変換する MCP サーバーです。

LLM にフォルダーを指定すると、言語、フレームワーク、エントリーポイント、モジュール、インポートグラフをまとめたアーキテクチャマップが返されます。Mermaid 図として出力されるため、PR、ドキュメント、オンボーディングガイドに貼り付けられます。

モデルに依存しません。 stdio 経由で Model Context Protocol を使用するため、Claude Code、Claude Desktop、Cursor、Cline、Copilot、OpenAI Agents SDK で動作し、Claude 固有の依存関係はありません。

何が違うのか

サーバーは確かな事実を抽出し、モデルが推論します。

repo-cartographer はコードを意味的に「理解」しようとはしません。ファイルツリー、インポートのつながり、マニフェスト、フレームワークの検出結果、エントリーポイントといった決定論的な事実を解析し、構造化 JSON と下書きの図を LLM に渡します。モデルはそれらの事実をもとに、最終的な説明と洗練された図を作成します。

この分担により、サーバーは小さく、高速で、テストしやすく、移植しやすくなります。また、図は幻覚ではなく、リポジトリに実際に含まれている内容に基づきます。

出力例

このリポジトリに対して 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

共有可能な単体の HTML レンダリングを examples/ にコミットしています（高レベル表示とファイルレベルの 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

サーバーは stdio 経由で通信し、AI クライアントはその方法で起動します。ターミナルから直接使うこともできます。詳しくは以下をご覧ください。

コマンドライン（AI 不要）

同じバイナリがデュアルモードで動作します。引数なしの場合は MCP サーバー、サブコマンドを指定した場合は人や CI 向けの通常の CLI になります。

# 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/ ラッパーを含む）を指定すると、ラッパーを検出して実際のリポジトリルートをマップします。このことは出力に記載され、通知なしに処理されることはありません。

2 種類の出力形式で、戦略は 1 つです。Mermaid を使うのは、そこが人々の目に触れる場所だからです（GitHub は PR コメントや README でネイティブにレンダリングします）。DOT を使うのは、ツールがそれを読み込むからです（Graphviz、Backstage、その他のツールにパイプで渡せます：dot -Tsvg architecture.dot）。どちらも、共有可能な同じ HTML ページと役割別に色分けされたモジュールを出力します。リポジトリに .cartographer.yml がある場合、その diagram: セクションが --level、--format、-o のデフォルトを設定します。明示的に指定したフラグが常に優先されます。

check はルールファイルを読み込み、禁止された境界を越えるインポートと依存関係の循環を検出します。LLM を使わず決定論的に実行されるため、マージのゲートとして安全に利用できます。

# .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）、事実の要約、インラインのドラフトソースが 1 回の呼び出しで得られます。
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 だけです — 「パスを渡せば、図が出力される」という仕組みです。4 つの個別ツールは、自分で手順を組み立てたい場合にのみ使います（たとえば、generate_diagram と render_diagram の間でモデルに図のソースを調整させる場合など）。

大規模なリポジトリでも高速な理由

• 対応言語： JavaScript/TypeScript と Python（v1）。
• node_modules、.git、dist、build、venv、__pycache__、vendor などのビルド／依存関係／キャッシュ用ディレクトリ（およびすべての隠しディレクトリ）をスキップします。
• スキャンするファイル数とファイルごとの読み取りバイト数に上限を設け、大きさがしきい値を超えると import グラフをディレクトリ単位に折りたたみます。上限に達したものは出力で報告され、通知なしに除外されることはありません。
• スキャン時にネットワーク呼び出しはありません。（レンダリングされた 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

テストでは、決定論的なコア機能である import の解決（JS/TS + Python）、モジュールの折りたたみ、循環の検出、ルールの glob、ベースラインとの差分、Mermaid のレンダリング、check のエンドツーエンドパスを網羅しています。tsx を使って src/ を対象に実行するため、ビルド手順やテストフレームワークへの依存はありません。

制作者

Gopi K Aitham（builditwithgk）が作成しました — about://author をご覧いただくか、scaleup-solutions.in にアクセスしてください。AI、エージェント、MCP ツールのフリーランスおよび業務委託の仕事を承っています。

ライセンス

MIT