codecanvas

CodeCanvas MCP

ファイルを一つずつ読み込むのに何千ものトークンを費やす前に、なじみのない Python システムを理解しましょう。

CodeCanvas は、Python 向けのローカル静的解析 Model Context Protocol サーバーです。プロジェクト全体の呼び出し経路と制御フローを、分岐、呼び出し元、呼び出し先、副作用、変更の影響について、引用にそのまま使える簡潔な回答に変換します。

ベンチマークの対象は、固定リビジョンの Google ADK、LangGraph、FastAPI に拡大しました。Apple M4 Pro で測定したコールド解析時間は 4.38s から 61.62s、これらのリポジトリでの find_symbols のウォーム時の中央値レイテンシーは 48.264ms から 293.778ms でした。管理された54セッションのエージェントテストでは、どちらの条件でも同じ組み込みコード検索ツールを使用し、処置条件では logic_flow のみを追加しました。この追加だけで、3回のペア反復全体における総トークン数の中央値が 22.95%減少し、通常のコード探索に加えて大きな価値をもたらすことが実証されました。キャッシュされないトークンは0.78%増加しており、回答のブラインド評価はまだ実施されていません。方法論、完全な表、制限事項をご覧ください。

次のような質問への回答に利用できます。

• この関数を直接または間接的に呼び出すのはどれですか？
• この関数から到達できるものは何ですか？副作用はどこで発生しますか？
• どのガード条件で、この戻り値または例外が発生しますか？
• 指定したモードで、このソースから対象に本当に到達しますか？
• 差分によって影響を受ける API ルート、スクリプト、公開エクスポートはどれですか？

CodeCanvas は Python のみを対象としており、Python 3.10 以降が必要です。

違いを見る

次の質問をしてみましょう。

Use logic_flow on UserService.update_user. Show its branches, outcomes,
downstream effects, and evidence quality.

同梱の FastAPI サンプルでの実際の回答からの抜粋です。

{
  "function": "app.services.user_service.UserService.update_user",
  "source": "app/services/user_service.py:13",
  "flow": [
    "15  user = await self.user_repo.find_by_id(...)",
    "16  if user is None:",
    "17      → return None",
    "18  → return await self.user_repo.update(user_id, user)"
  ],
  "outcomes": [
    {"at": 17, "detail": "None", "guards": ["user is None"]},
    {"at": 18, "detail": "await self.user_repo.update(user_id, user)", "guards": []}
  ],
  "downstream": [
    {
      "function": "app.repositories.user_repo.UserRepository.find_by_id",
      "location": "app/repositories/user_repo.py:13",
      "effects": ["db"]
    },
    {
      "function": "app.repositories.user_repo.UserRepository.update",
      "location": "app/repositories/user_repo.py:18",
      "effects": ["db"]
    }
  ],
  "evidence_grade": "inferred",
  "safe_to_summarize": false,
  "response_guidance": "Do not turn inferred call edges into unconditional claims."
}

この回答だけで、早期リターン、成功経路、後続のデータベース処理、正確なソース位置、そしてエージェントが結果をどの程度慎重に要約できるかが明らかになります。

クイックスタート

uvx がすでに利用可能でない場合は、uv をインストールしてください。 リポジトリには、Claude Code と Codex の両方に対応するネイティブマニフェストを備えた、共通のプラグインパッケージが含まれています。CodeCanvas マーケットプレイスからインストールします。

# Claude Code
claude plugin marketplace add donggyun112/codecanvas
claude plugin install codecanvas@codecanvas

# Codex
codex plugin marketplace add donggyun112/codecanvas
codex plugin add codecanvas@codecanvas

どちらのプラグインも uvx codecanvas-mcp を起動し、すべてのツールカタログを公開します。ローカルチェックアウトでのテスト方法と検証コマンドについては、プラグインパッケージをご覧ください。

クライアントがプラグインに対応していない場合は、サーバーを直接登録してください。Claude Code の場合：

claude mcp add codecanvas -- uvx codecanvas-mcp

このコマンドはすべてのツールカタログを公開します。MCP クライアントがオンデマンドのツール検出またはツール検索に対応している場合は、カタログ全体を有効にしておいてください。必要なスキーマだけを必要なときにクライアントが読み込めるため、他の CodeCanvas ツールも、モデルへのリクエストごとにスキーマのコストを負担することなく利用できます。

[mcp_servers.codecanvas]
command = "uvx"
args = ["codecanvas-mcp"]

有効にしたすべてのツールスキーマを、クライアントがすべてのモデルリクエストに遅延なく注入する場合は、代わりにこちらの互換プロファイルを使用してください。

[mcp_servers.codecanvas]
command = "uvx"
args = ["codecanvas-mcp"]
enabled_tools = ["logic_flow", "who_calls", "call_tree"]

3つのツールに限定した許可リストは、スキーマを一括で読み込むクライアント向けの代替策であり、CodeCanvas の残りの機能を捨てることを推奨するものではありません。他の MCP クライアントでは、同等の stdio 設定を使用してください。

{
  "mcpServers": {
    "codecanvas": {
      "command": "uvx",
      "args": ["codecanvas-mcp"]
    }
  }
}

最初のツール呼び出しで、絶対パスの project_path を指定してください。CodeCanvas は、サーバーセッション中、最後に明示的に選択されたプロジェクトを記憶します。

カタログ全体を有効にしている場合、project_status は、ネストされた Python プロジェクトの解析候補ルートを報告します。コンパクトプロファイルを使用する場合は、対象のネストされたルートを明示的に指定してください。

エージェントに使用タイミングを教える

ツールを追加しても、エージェントが適切なタイミングでそれを選ぶとは限りません。AGENTS.md、CLAUDE.md、またはコーディングエージェントが使用する同等のファイルに、次のような短い指示を記載してください。

## Code analysis

Use CodeCanvas before text search when you need to know:

- how a Python function branches, returns, and produces side effects;
- who calls it directly or transitively;
- what it reaches downstream through project-internal calls.

Pass `project_path` once, then reuse the active project. Treat
`safe_to_summarize: false`, inferred edges, ambiguity, and truncation as
qualifications rather than unconditional facts.

Start with `logic_flow`. Use `who_calls` for upstream impact and `call_tree`
for a deeper downstream trace.

続いて、エージェントに自然な言葉で尋ねてください。

Use logic_flow first to understand checkout without repeated source searches.
What calls UserService.update_user, up to three hops?
What does checkout reach downstream, including HTTP or database effects?

カタログ全体を有効にすると、CodeCanvas は次の質問にも回答できます。

List the entrypoints in this project.
Under exactly what conditions can authenticate raise?
Verify that dry-run publish reaches _call_api.
Analyze the impact of the current diff.

grep や LSP では不十分なのはなぜですか？

CodeCanvas はどちらも補完します。繰り返し検索して手作業で再構成しなければならないような、動作に関する質問に対応します。

必要なこと	grep	LSP	CodeCanvas
正確なテキスト	最適	対象外	引き続き grep を使用
定義と直接参照	手作業	最適	構造化された結果内でシンボルを解決
推移的な呼び出し元と呼び出し先	手作業で何度もたどる	参照は呼び出しパスではない	範囲を限定した上流・下流グラフ
分岐ガードと結果	ソースを読んで再構成	通常はモデル化されていない	構造化されたフローと、ガード付きの return／raise
副作用と変更の影響	手作業で推測	通常はモデル化されていない	呼び出しパスとエントリーポイントを通じて影響を特定
不確実性	信頼度モデルなし	解決状況に依存	根拠のレベル、曖昧さ、打ち切り、ガイダンス

回答の信頼性を高める仕組み

静的解析は実行時の真実ではありません。そのため CodeCanvas は、不確実性を隠さずに明示します。

成功したすべての MCP レスポンスには、選択された analysis_root が示され、エージェントが結果をどの程度確かなものとして述べられるか判断するのに役立つメタデータが含まれます。

• evidence_grade は、解決された根拠の強さを示します。
• inferred_edge_count と ambiguous_calls は、不確かな呼び出しエッジを明らかにします。
• truncated は、範囲の制限によって結果が省略されたかどうかを示します。
• safe_to_summarize は、結果が無条件の主張を裏付けるかどうかを示します。
• response_guidance は、裏付けがない場合に結果をどのように限定して説明するかを示します。

verify_claim はさらに、候補となる呼び出しパスを分岐および return／raise のガードと組み合わせて検証します。結果は true、false、または uncertain で返され、裏付けのない修飾条件や推論のみのパスが、暗黙のうちに確定的な true になることはありません。

ツール

検出と理解

ツール	用途
project_status	アクティブなルート、Python ファイル数、キャッシュ、ワーカーのインタープリター、ネストされたプロジェクト候補を確認
list_entrypoints	FastAPI のルート、スクリプト、関数のエントリーポイント、分散ライブラリのエクスポートを検出
find_symbols	完全一致優先の名前検索、セマンティック検索、またはハイブリッド検索で関数、メソッド、クラスを特定
logic_flow	関数の分岐、結果、下流の呼び出し、副作用を、引用に適した簡潔な形式で表示
what_does	シグネチャ、docstring、呼び出し、副作用、例外、直接的なリスクから関数を調査
function_flow	条件、対象、スコープ、ネストを含む構造化された分岐ツリーを確認
reaching_conditions	各 return または raise を囲むガードに加え、複雑さと到達不能コードを取得

動作の追跡と変更の評価

ツール	用途
who_calls	直接または推移的な呼び出し元を上流方向にたどる
call_tree	プロジェクト内部の呼び出し先を下流方向にたどり、直接的・推移的な副作用を特定
verify_claim	パスとガードに照らして、条件付きの「source reaches target」という主張を保守的に検証
analyze_impact	インラインの差分または git ref を、変更された関数と影響を受けるエントリーポイント／公開 API に対応付ける

状態に依存するバグの再現

ツール	用途
validate_state_schema	関数による状態の読み取り、書き込み、マッピングの返却内容を、呼び出し元が指定したスキーマと比較
simulate_state_transition	不変条件と依存関係のオーバーライドを指定して、生成された状態ケースまたは明示的な状態ケースを重点的に実行

大きな結果セットには上限があります。結果を完全なものとして扱う前に、各ツールの filter、kind、path、depth、またはページネーション引数を使って範囲を絞り込んでください。

仕組み

1. プロジェクトを選択します。 CodeCanvas は明示的に指定された Python プロジェクトのルートを解決し、記憶します。入れ子になったルートが曖昧な場合は、推測せずに選択する必要があります。
2. 構造インデックスを構築します。 Python AST 解析により、プロジェクト全体の呼び出しグラフと、関数ごとの制御フローデータを構築します。エクストラクターは FastAPI のルートと Depends() チェーン、スクリプト、汎用関数エントリーポイント、パッケージのエクスポートを追加します。
3. 互換性のある解析結果を再利用します。 呼び出しグラフとエントリーポイントは <project>/.codecanvas/ にキャッシュされ、MCP セッション中はプロセス内のビルダーが再利用されます。
4. 簡潔な回答を生成します。 各 MCP ツールは共有解析結果を検索し、出所、根拠、曖昧さ、切り捨てに関するメタデータを含む、範囲を限定した結果を返します。

既定の解析上限は Python ファイル 5,000 件です。大規模プロジェクトでの動作は、次の設定で調整できます。

変数	既定値	説明
CODECANVAS_MAX_FILES	5000	解析する Python ファイルの最大数
CODECANVAS_BATCH_SIZE	50	処理を譲るまでに処理するファイル数
CODECANVAS_THROTTLE_MS	10	バッチ間の遅延（ミリ秒）

安全性と制限事項

• CodeCanvas は Python ソースを解析します。あらゆる動的インポート、モンキーパッチ、リフレクションの経路、実行時の値をモデル化するわけではありません。
• 推論されたエッジや曖昧なエッジは、確定的な根拠として扱わず、注記として報告されます。
• 静的解析ツールはプロジェクトファイルを読み取り、ローカルの .codecanvas/ キャッシュに書き込みます。リモートの CodeCanvas サービスは不要です。
• simulate_state_transition は異なります。このツールは別プロセス内で、信頼できるプロジェクトコードをインポートして実行します。これは対象を絞った再現のための分離であり、セキュリティサンドボックスではありません。プロジェクトコードは引き続きファイルシステム、ネットワーク、サブプロセスにアクセスでき、インポート時に副作用が発生する可能性もあります。
• シミュレーターは <project>/.venv または venv を優先し、次に親プロジェクト内の同じディレクトリを使用します。明示的に選択するには python_executable を使い、インポートに失敗した場合は返された worker メタデータを確認してください。

根拠

測定済みのローカルレイテンシースイートでは、Python ファイル数が 148～1,650 件、インデックス済み関数数が 4,468～16,960 件の、ピン留めされた 3 つのプロジェクトを対象としています。コールド解析、初回およびウォーム状態での検索レイテンシー、8 ワーカーのスループットを報告し、生データはベンチマーク成果物とともにコミットされています。

モデルを使用した評価では、Google ADK、LangGraph、FastAPI の固定タスクと非公開の評価基準を対象としています。組み込みのコード探索に logic_flow を加えた構成と、組み込みのコード探索のみの構成を比較しています。54 件の独立したセッションで、3 回のペア反復により、サーバーが報告した合計トークン数はスイート全体の中央値で 22.95% 減少しました。介入群の 27 セッションすべてで必須のツール呼び出しが完了しており、CodeCanvas のツールを 1 つ加えることで、エージェントの既存の検索ツールを置き換えることなく、意味のある価値が追加される直接的な根拠となっています。キャッシュされていない入力と出力の合計は中央値で 0.78% 増加しました。また、回答はまだブラインド評価されていないため、同等の品質における効率性や請求コストに関する主張ではありません。

完全な手法、結果表、再現コマンド、監査成果物を参照してください。

開発

git clone https://github.com/donggyun112/codecanvas.git
cd codecanvas/core
uv sync --extra dev
cd ..
core/.venv/bin/python -m pytest

パッケージのソースは core/ にあります。ルートのテスト設定では、tests/ の製品テストと core/tests/ のパッケージレベルのテストの両方が実行されます。

Issue の報告や、対象を絞った再現ケースの提供を歓迎します。 https://github.com/donggyun112/codecanvas/issues。

ライセンス

CodeCanvas MCP は、MIT License に基づいてライセンスされるオープンソースソフトウェアです。