Cartograph

Cartograph

Cartograph は、コーディングエージェント向けにタスクに沿ったリポジトリコンテキストを提供します。CLI、MCP サーバー、Claude Code と OpenClaw 向けのユーザースコープのインストールアダプター、ドキュメント中心のワークフロー向けにパッケージ化されたエージェントアセットを提供します。

• npm: @anthony-maio/cartograph
• MCP Registry: io.github.anthony-maio/cartograph
• クイックスタート: cartograph.making-minds.ai

リポジトリ全体をコンテキストに読み込む代わりに、Cartograph は重要なファイルをランク付けし、依存関係をマッピングし、構造化されたアーティファクトをキャッシュします。次のツールやエージェントは、そのアーティファクトを引き継いで作業できます。

基本的なワークフローは次のとおりです。

1. analyze でリポジトリをマッピングします
2. packet で作業の準備をします
3. context --static でモデルを呼び出さずに、タスクに合ったファイルを読み込みます

wiki、ホストへのインストール、ベンチマークは、この基本的な流れを中心に構成された補助的な機能です。

インストール

npm install
npm run build

npm からグローバルに使用する場合：

npm install -g @anthony-maio/cartograph

公式レジストリから MCP ホストに検出させる場合：

• io.github.anthony-maio/cartograph
• レジストリの掲載ページ

この公開リポジトリから Claude Code プラグインをインストールする場合：

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

ローカルのチェックアウトからグローバルに使用する場合：

npm install -g .

開発ワークフローについてはCONTRIBUTING.mdを、脆弱性の報告についてはSECURITY.mdを参照してください。

完全な例を実行する

npm パッケージには、小規模なリフレッシュトークンの例が含まれています。新しい作業ディレクトリから実行します。

npm init -y
npm install @anthony-maio/[email protected]
npx cartograph analyze ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --static
npx cartograph packet ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --type bug-fix --task "fix refresh token expiry"
npx cartograph context ./node_modules/@anthony-maio/cartograph/examples/auth-refresh --task "fix refresh token expiry" --static --json
node --test ./node_modules/@anthony-maio/cartograph/examples/auth-refresh/tests/auth-refresh.test.js

パケットには src/auth/refresh.js と tests/auth-refresh.test.js が含まれるはずです。コンテキストバンドルにはクロックヘルパーが含まれ、無関係な請求処理やカタログ関連のファイルは除外されます。3 つの動作チェックがすべて成功するはずです。調査手順で、期待される結果と同じプロセスをリポジトリに適用する方法を確認してください。

Claude Code プラグイン

このリポジトリは Claude Code プラグインマーケットプレイスとしても機能します。cartograph プラグインには、次のものが含まれています。

• プラグインスコープの Cartograph MCP サーバー
• スラッシュコマンド：/cartograph:analyze、/cartograph:context、/cartograph:wiki
• use-cartograph と repo-surveyor のスキル
• ドキュメントエージェントバンドル：repo-scout、dependency-tracer、context-picker、api-surface-writer、wiki-writer

次のコマンドでインストールします。

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

基本的なワークフロー

1 つだけ覚えておくなら、これを覚えてください。

cartograph analyze <repo> --static
cartograph packet <repo> --type <type> --task "<task>"
cartograph context <repo> --task "<task>" --static --json

• analyze はリポジトリをマッピングし、重要な要素を示します。
• packet は具体的な作業を、再利用可能な作業アーティファクトに変換します。
• context --static は、タスクに合ったファイルと、その近くにある依存関係やテストを内容とともに選択します。ローカルのヒューリスティクスを使用するため、API キーは不要です。

別途用意されているモデルを利用したコンテキストワークフローは、--static を省略すると実行されます。使用する前にプロバイダーを設定してください。どちらのモードも、選択されたファイルにバグが含まれていることを証明するものではありません。

コマンド一覧

cartograph analyze <repo> [options]
cartograph packet <repo> --type <type> --task "<task>" [--changed <paths...>]
cartograph context <repo> --task "<task>" [options]
cartograph wiki <repo> [options]
cartograph export <run-id> --to <path> [--artifact <name>]
cartograph install <claude|openclaw|mcp>
cartograph uninstall <claude|openclaw|mcp>
cartograph doctor [target] [--json]
cartograph mcp

従来との互換性も引き続き保たれています。

cartograph <repo> --static
cartograph <repo> -c "trace auth flow"

CLI の使用方法

# Map the repo
cartograph analyze ./my-project --static

# Prepare a concrete job
cartograph packet ./my-project --type bug-fix --task "fix auth refresh bug" --changed src/auth/service.ts tests/auth/service.test.ts

# Load the minimum file set for that job
cartograph context ./my-project --task "add user authentication" --static --json

# Force embedded snippets when you really want them
cartograph analyze ./my-project --static --json --include-contents

# Full wiki output
cartograph wiki ./my-project -p gemini -k $CARTOGRAPH_API_KEY -o wiki.md

# Export a cached artifact to an explicit path
cartograph export run-abc123 --to ./artifacts/wiki.md

# Run the MCP server directly
cartograph mcp

小規模なリポジトリでは、analyze --static --json のデフォルト出力が、上位ファイルの内容を埋め込む形式からコンパクトな形式に変わりました。これにより、小規模なリポジトリでも読みやすさが保たれ、ファイルを直接読み込むほうが巨大な JSON の塊を扱うよりも低コストになります。スニペットを埋め込む場合は、--include-contents を使用してください。

analyze --static のデフォルトの Markdown 出力は、人が読むことを優先しています。重要な点を強調し、依存関係のハブを示し、ファイルの生の内容をすぐに出力する代わりに、次に実行するコマンドを提案します。

プロバイダー

• gemini
• openai
• openrouter
• ollama

--key または CARTOGRAPH_API_KEY で API キーを設定します。Ollama ではキーは必要ありません。

キャッシュモデル

Cartograph は、デフォルトで成功した実行結果をユーザーキャッシュに書き込みます。

• Windows：%USERPROFILE%\\.cartograph\\cache
• POSIX：~/.cartograph/cache

実行ごとにマニフェストと名前付きのアーティファクトが作成されます。これにより、エージェント間の引き継ぎが軽量になり、cartograph export の結果が決定的になります。

ホストへのインストール

Cartograph は、明示的なハイブリッドインストールモデルを採用しています。パッケージをインストールしても、Claude Code、OpenClaw、MCP ホストの設定は自動的に変更されません。

代わりに、必要なインテグレーションだけをインストールしてください。

cartograph install claude
cartograph install openclaw
cartograph install mcp

各ターゲットでインストールされるもの：

• claude：ユーザースコープのスキルと、同梱のドキュメント作成エージェントを ~/.claude にインストールします
• openclaw：ユーザースコープのスキルパックを ~/.openclaw にインストールします
• mcp：Cartograph の MCP 設定スニペットを ~/.cartograph/mcp にインストールします

ステータスはいつでも確認できます。

cartograph doctor
cartograph doctor --json

利用方法を選ぶ

• CLI：決定論的なローカル分析と明示的な成果物が必要な場合に最適な標準の方法です。
• Claude Code プラグイン：プラグインのインストール、同梱スキル、スラッシュコマンド、プラグインスコープの MCP サーバーが必要な場合に最適です。
• OpenClaw スキル：スキルを中心とした OpenClaw 環境で同じ Cartograph ワークフローを使いたい場合に最適です。
• MCP Registry：ホストがシェルコマンドよりもツールの接続を優先する場合に最適です。

MCP サーバー

Cartograph の MCP サーバーは、シェルコマンドよりも MCP を優先するホストに、静的なリポジトリ分析機能を直接提供します。

ツール：

• analyze_repo：ローカルリポジトリまたは GitHub URL のファイルをスコアリングし、依存関係をマッピングして、簡潔な分析結果または上位ファイルの埋め込みコンテンツを返します
• get_file_contents：分析後、指定したファイルの完全な内容を取得します
• build_task_packet：主要ファイル、依存関係のハブ、検証対象、リスク、タスク固有の詳細を含む型付きタスクパケットを返します

バグ修正用のパケットは、--changed または changed_files を指定した場合に、対象を絞った状態を保つよう調整されています。明示的な変更範囲を維持し、正確な検証対象を優先し、周辺的なユーティリティスクリプトより共有依存関係を重視します。

Cartograph のパッケージ済み MCP スニペットを使うには、次を実行してください。

cartograph install mcp

再利用可能な設定ファイルが作成され、次を参照します。

{
  "mcpServers": {
    "cartograph": {
      "command": "cartograph",
      "args": ["mcp"]
    }
  }
}

MCP Registry

Cartograph は公式 MCP Registry に、サーバー名 io.github.anthony-maio/cartograph で公開されています。

• レジストリエントリーを表示

リポジトリ側のメタデータは次の場所にあります。

• package.json の mcpName フィールド
• レジストリメタデータ用の server.json

現在 npm に公開されているインストール成果物は次のとおりです。

• @anthony-maio/cartograph

レジストリへのリリースを再現可能にするため、このリポジトリには publish-mcp.yml に GitHub Actions ワークフローも含まれています。GitHub Actions での npm の信頼された公開を設定し、その後 GitHub OIDC で MCP Registry に認証して server.json を公開します。

パッケージに含まれるエージェント用アセット

現在、パッケージには次のものが含まれています。

• Claude スキル 2 つ：use-cartograph と repo-surveyor
• Claude ドキュメント作成エージェント 5 つ：repo-scout、dependency-tracer、context-picker、api-surface-writer、wiki-writer
• OpenClaw スキル 2 つ：use-cartograph と repo-surveyor
• リポジトリのドキュメント作成とタスクコンテキストのワークフロー向けの、両方の OpenClaw スキルに同梱された OpenProse テンプレート

スキルの役割：

• use-cartograph：CLI または MCP サーバーが利用可能な場合に使う、ツール優先の方法です
• repo-surveyor：Cartograph を利用できない場合や、検証が必要な場合に使う手動の代替方法です

どちらのスキルも、後続の処理で同じ契約を生成するよう設計されています。

• 主要ファイル
• 依存関係のハブ
• 最小限のタスクコンテキスト
• ドキュメント作成に適した要約

これらのアセットは、大量の文章をメインコンテキストにコピーする代わりに、ステップ間で実行 ID と成果物のパスを受け渡すことを目的としています。

このリポジトリの Claude プラグインマーケットプレイスには、同じスキルとエージェントに加え、プラグイン優先のスラッシュコマンドと Cartograph MCP サーバーが同梱されています。

タスクパケットのベンチマーク

このリポジトリには、benchmarks/task-packets にタスクパケットの公開ベンチマークパックが含まれています。

安定した一連のタスクプロンプトを使って、大規模で公開されているリポジトリ間のパケット品質を比較できます。

npm run benchmark:task-packets -- --list
npm run benchmark:task-packets -- --case llama-cpp-bug-fix --dry-run

ベンチマークランナーは、パケットの成果物を benchmarks/task-packets/output/ に書き込みます。このディレクトリは gitignore に登録されています。

厳選したスコアカードと公開成果物へのリンクも、サイトで公開されています。

• cartograph.making-minds.ai/examples/benchmarks.html

成果物の例

追跡対象のサンプルは docs/examples にあります。

• llama-cpp-task-packet.md
• llama-cpp-task-packet.json
• llama-cpp-deepwiki.md
• task-packet-benchmark-scorecards.md

大規模な公開コードベースで、バグ修正に特化したパケットと、厳選したリポジトリ概要がどのようなものかを示す際に役立ちます。

開発

npm install
npm test
npm run check
npm run build
npm run pack:smoke

ライセンス

MIT