TRACE-MCP

_{対応クライアント  ·  Claude Code  ·  Cursor  ·  Codex  ·  Windsurf  ·  Zed  ·  あらゆる MCP クライアント}

trace-mcp はエージェントが何度も読み直す情報をインデックス化し、その代わりに答えを提供します。
プルリクエストのレビューで入力トークンを72.7%削減 — 自社が所有していないオープンソースリポジトリでマージされたプルリクエスト60件の中央値です。

tweakcc 連携では、サードパーティのパッチャーを代わりに実行します。

npm install -g trace-mcp   # MCP server, no app
trace init                 # wire it into your agent, once per machine
trace add                  # index the repo you are in

プルリクエストのレビューに必要な入力トークンを72.7%削減 — 自社以外の6つのリポジトリでマージされた60件のPRの中央値で、プルリクエストあたり13,595から3,291に削減しました。測定方法と再現手順 →

_{2026年9月7日に trace-mcp 3.23.2（cb8ab30c）で測定 — この結果はそのビルドでのものであり、現行バージョンについて主張するものではありません。測定の目的、クリアすべき基準、判定結果：事前登録。}

安価であることと、優れていることは同じではありません。そこで、同じ60件のプルリクエストを2回レビューし、ブラインド方式で評価しました。trace-mcp 側はそのうち67%の変更内容を理解し、ファイルを単純に読み込む方式の65%を上回りました。一方、誤検出はPRあたり0.80件で、単純なファイル読み込み方式の0.58件を上回りました。ベンチマークの品質評価 →

_{デスクトップアプリ：MCP サーバーが提供するものと同じインデックスを使う GPU グラフエクスプローラーです。}

問題

AI エージェントは、すでに完了した作業に何度もコストを支払っています。ターンごとに、同じファイルを再び読み、同じ依存関係を再びたどり、5ステップ前に発見した構造をコンテキストウィンドウに再び詰め込みます。この反復作業が、長いセッションで発生するトークンとレイテンシのコストの大部分を占めています。

trace-mcp は、コードベースのフレームワークを認識したグラフを一度だけ構築し、それを MCP 経由で提供します。これにより、エージェントはリポジトリを力任せに読み込むのではなく、事前計算された構造をもとに推論できます。*「このモデルを変更したら、何が壊れるか」*と尋ねる場合、80回の Grep 呼び出しと190回のファイル読み込みの代わりに、エージェントは get_change_impact を1回呼び出すだけで、PHP、Vue、マイグレーション、DI にまたがる影響範囲を取得できます。81言語に対応した91のフレームワーク統合と182のツールを備えています。

制約となるのはモデルの能力ではなく、再計算です。トークン料金、レイテンシ、ハルシネーションは、タスクの複雑さではなくプロジェクトの規模に応じて増加します。trace-mcp は、この再計算の漏れを解消します。グラフは一度構築され、継続的に最新の状態に保たれ、リクエストするすべてのエージェントに提供されます。そのため、同じ作業に何度もコストを支払う必要はありません。

• コストの削減 — 成功した回答あたりのトークン数を、平均でもピーク時でも削減
• レイテンシの低減 — ツールの逐次呼び出しと、モデルとの往復を削減
• 精度の向上 — コンテキスト内のノイズを減らし、ハルシネーションを抑えて、初回応答の正確性を向上
• 本番環境での安定性 — コンテキストの増加をリポジトリの規模ではなく、タスクの複雑さに連動

まず、反復処理のコストが最も高いコードインテリジェンスから始めました。同じエンジンで、現在は Markdown のナレッジボルト（Obsidian、Logseq、プレーンな MD）も同等のドメインとしてインデックス化できます。ウィキリンク、タグ、フロントマター、埋め込みはグラフのエッジとシンボルのメタデータになり、search、find_usages、get_change_impact、apply_rename はどちらのドメインでも同じように動作します。

trace-mcp ができること

隣接するツールでは珍しい 4 つの機能：

1. フレームワークを認識したエッジ — trace-mcp は、Inertia::render('Users/Show') が PHP と Vue をつなぐこと、@Injectable() が DI 依存関係を作ること、$user->posts() がマイグレーションで定義された posts テーブルを意味することを理解します。91 のフレームワーク統合に対応しています。

2. コードにリンクされた決定のメモリー — 「JSONB をサポートするために PostgreSQL を選んだ」と記録すると、src/db/connection.ts::Pool#class にリンクされます。誰かがそのシンボルに対して get_change_impact を実行すると、その決定が表示されます。MemPalace は決定をテキストとして保存しますが、trace-mcp は依存関係グラフに結び付けます。

3. セッションをまたいだインテリジェンス — 過去のセッションから決定事項を抽出し、検索用にインデックス化します。新しいセッションを開始すると、get_wake_up が約 300 トークンで状況を把握できる情報を提供し、plan_turn がタスクに関連する過去の決定を表示します。また、get_wake_up { scope: "resume" } は、以前のセッションから構造的なコンテキストを引き継ぎます。

4. コードとナレッジを 1 つのグラフに統合 — trace-mcp に Markdown Vault（Obsidian、Logseq、プレーンな MD）を指定すると、同じエンジンでインデックス化されます。各ノートは note:<basename> シンボルになり、見出しは入れ子のセクションになり、[[wikilinks]] と ![[embeds]] はグラフエッジになり、フロントマターと #tags はメタデータとして扱われます。PageRank、Signal Fusion によるランキング、埋め込み、名前変更のリファクタリングも、そのまま適用されます。エージェントが新たに別のツールを学ぶ必要はありません。コードベースとノートの両方を保持する、同じグラフを使います。

エージェントが何度も読み直す理由

AI コーディングエージェントは、ターンごとに同じ作業を再計算します。そのうえ、その作業中はフレームワークを認識できません。

UserController.php を読み直し、次のターンでもまた読み直します。Inertia::render('Users/Show', $data) が Laravel コントローラーと resources/js/Pages/Users/Show.vue をつなぐことを理解していません。$user->posts() が、3 回前のマイグレーションで定義された posts テーブルを意味することも理解していません。URL からレンダリングされた画素までリクエストをたどれないため、セッションのたびに何度もたどり直します。

その結果、1 つのタスク内で頻繁に使うファイルを 5～15 倍も繰り返し読み、コンテキストウィンドウを一時的なデータベースとして使うことになります。プロジェクトが大きくなるほど、能力が高まるのではなく、エージェントのコストが増えていきます。

ソリューション

trace-mcp はソースコードからクロス言語の依存関係グラフを構築し、Model Context Protocol を通じて公開します。これは Claude Code、Cursor、Windsurf などの AI コーディングエージェントが使用するプラグイン形式です。MCP 互換エージェントなら、最初からフレームワークレベルの理解を得られます。

デスクトップアプリ

trace-mcp にはオプションの Electron デスクトップアプリ（packages/app）が付属しており、MCP サーバーと同じインデックスを視覚的に確認できます。複数のプロジェクトを管理し、MCP クライアントを接続し、GPU アクセラレーション対応のグラフエクスプローラーを利用できます。ターミナルを開く必要はありません。

プロジェクトとクライアント。 メニューウィンドウには、インデックス化されたプロジェクトがライブステータス（Ready／インデックス作成中／エラー）とともに一覧表示され、再インデックス作成／削除の操作ができます。MCP Clients タブでは、インストール済みのクライアント（Claude Code、Claw Code、Claude Desktop、Cursor、Windsurf、Continue、Junie、JetBrains AI、Codex、AMP、Warp、Factory Droid）を検出し、適用レベル（Base／Standard／Max — CLAUDE.md のみ、+ hooks、+ tweakcc とエージェント動作ルール。Max ティアの機能は Claude Code 専用）を含め、ワンクリックで trace-mcp を接続します。Warp と JetBrains AI は設定を GUI でしか保存できないため、IDE 内で手動貼り付けが必要です。

プロジェクトごとの概要。 各プロジェクトは専用のタブ付きウィンドウで開きます。Overview（ファイル、シンボル、エッジ、カバレッジ、連携サービス、再インデックス作成）、Ask（インデックスに対する自然言語クエリ）、Graph を利用できます。Overview には Most Symbols ファイル、最終インデックス作成日時、依存関係カバレッジメーターも表示されます。

GPU グラフエクスプローラー。 Graph タブでは cosmos.gl を使って依存関係グラフ全体を GPU 上に描画します。数万のノード／エッジをインタラクティブなフレームレートで表示できます。ファイル／シンボルでフィルターし、検出されたコミュニティを重ねて表示し、グループを強調表示し、ラベル／FPS の表示を切り替え、グラフの深さを段階的に確認できます。ツールを使い始める前に、結合度やホットスポット、コードベースの実際の構造を把握するのに役立ちます。

Windows へのインストール： リリースから trace-mcp.Setup.<version>.exe を実行します。

アプリ内アップデーターが古いビルドのまま動かない場合： macOS／Windows のバージョン 3.10.0 以前のアプリは、自動でアップデートできません。「アップデートを確認…」を選ぶと Cannot set properties of undefined (setting 'autoDownload') と表示され、何も起こりません。この不具合は 3.11.0 で修正されていますが、影響を受けるビルドは自力でアップデートして解決できません。手動で再インストールしてください。macOS の場合は .dmg をダウンロード、Windows の場合はリリースから最新の trace-mcp.Setup.<version>.exe を入手します。または、CLI がインストール済みであれば、trace-mcp install-app を実行してください。

アプリは、MCP クライアントが使用するものと同じ trace-mcp デーモン（http://127.0.0.1:3741）と通信するため、アプリからインデックスを作成した内容は、すぐに Claude Code／Cursor などから利用できます。MCP サーバーと CLI だけが必要な場合、アプリは必要ありません。npm install -g trace-mcp だけでインストールできます。

trace-mcp の比較

trace-mcp は、コードグラフナビゲーション、セッションをまたいだメモリ、リアルタイムのコード理解を単一のツールに統合しています。近接するプロジェクトの多くは、このうちの 1 つを解決します。trace-mcp は 3 つすべてを統合し、フレームワークを考慮した言語間エッジ（91 のフレームワーク統合）とコードに紐づいた判断メモリを備える唯一のツールです。

• トークン効率の高い探索ツールとの比較（Repomix、jCodeMunch、cymbal） — trace-mcp は、シンボル検索にフレームワークエッジ、リファクタリング、セキュリティ、サブプロジェクトを追加します。
• セッションメモリツールとの比較（MemPalace、claude-mem、ConPort） — trace-mcp は判断を特定のシンボル／ファイルに紐づけるため、影響分析で自動的に表示されます。
• RAG／ドキュメント生成ツールとの比較（DeepContext、smart-coding-mcp） — trace-mcp は「このクエリに似たコードを見つける」のではなく、「実行パス、依存関係、テストを表示して」といった質問に答えます。
• コードグラフ MCP サーバーとの比較（Serena、Roam-Code） — trace-mcp は最も幅広い言語をカバーし（81 言語）、言語間のフレームワークエッジを備える唯一のツールです。

GitHub スター数、言語、機能ごとの対応範囲を含む、詳細な比較表はこちらです：trace-mcp と他のコードインテリジェンス MCP サーバーの比較。

直接比較：Repomix との比較 · Serena との比較 · codegraph との比較 · codebase-memory-mcp との比較 · Claude Code context mode との比較 · code-review-graph との比較 · Repomix と codegraph の比較。

トークン削減 — 測定結果

AI エージェントは、前のターンですでに発見した内容を再計算するためにトークンを消費します。ファイルを読み直し、依存関係をたどり直し、コンテキストを再び膨らませるのです。trace-mcp は、精密なコンテキストでこれを置き換えます。クエリに関連するシンボル、エッジ、シグネチャだけを、一度だけ計算されたグラフから提供します。 まず、自分たちが測定したものではない指標から始めます。 このセクションのほかのすべての数値は、trace-mcp 自身のリポジトリを対象に trace-mcp が測定したものです。最初の表の行は実際のレスポンスに基づき、それ以降はすべて trace-mcp 独自の合成推定値です。例外はPR レビューコンテキストのベンチマークです。これは、6 つのオープンソースリポジトリ（hono、axios、express、requests、flask、got）におけるマージ済みプルリクエスト 60 件のレビューコンテキストを組み立てる場合、中央値で 3,291 入力トークンを要するのに対し、差分と変更対象の全ファイルを読み込む場合は 13,595 トークンを要し、72.7% 少ないことを示しています。推定ではなく gpt-tokenizer で数えた結果です。ベース SHA とヘッド SHA は benchmarks/pr-context/dataset.json に固定されており、npx tsx scripts/bench-pr-context.ts で再実行できます。また、インデックスが効果を発揮しなかったプルリクエスト 56 件も、効果があったものと合わせて公開しています。ファイルをそのまま読むよりコストが高かったものが 13 件、そしてバンドルのトークン予算では変更されたすべてのシンボルの本文を取得できなかったものが 42 件です。この不足は、今回の実行で一覧表示ではなく取得内容を評価するまで、ベンチマークでは検出できませんでした。

ワークロード別の目安：

計画の基準とすべき正直な数値は 67.4% です。また、この数値が変わった理由は、製品が速くなったからではありません。 以前は「平均で約 40〜50%」と表示していました。この数値は、ツールの実行前に各呼び出しをスコアリングするカウンター、つまり分散のない定数 RAW_COST_ESTIMATES[tool] × 0.15 に由来していました。これを見つけ、自分たちで #915 で修正しました。記録された呼び出しのカバレッジが 97.2% に達するにつれ、正直な代替値は 29.3%、次に 21.1%、さらに 21.0% となりました。その後、重みの 76% を占める 3 つのツールが、それぞれ 1 つのサンプルに基づいて価格付けされており、サンプルの選び方として妥当な 4 通りの方法で、同じビルドの値が 21.0%、30.7%、56.0%、67.4% になることが判明しました。そこで現在は、サンプリング枠を生成して固定し、それを使う実行の前にコミットしています。また、その作成方法に関するすべての主張を、CI でリポジトリと照合して再確認しています（事前登録）。67.4% は登録済みの枠で測定した値です。21% からの上昇は、製品の変化ではなく枠組みの変化として捉えてください。 これは、1 台のマシンで記録された 18,329 件の呼び出しについて、実際のレスポンスを o200k_base で数えた結果を重み付けしたものです（ツール別の表。docs/_data/response_tokens.json に生成されます）。これには 3 つの注意点があります。まず、ベースライン側、つまり代わりに Read／Grep を使った場合のコストは、依然として手書きの推定値です。次に、測定した 23 個のツールのうち 4 個は、置き換える処理より多くのトークンを返しますが、以前のカウンターではそれらにも節約分を計上していました。さらに、あと 2 つのツール（register_edit、reindex）はファイル読み取りをまったく置き換えないため、現在は節約分をゼロとし、オーバーヘッドに計上しています。これらを支出側に含めた総合値は 66.5% です。以下のピーク値（構造化された個別の呼び出しで最大 99%）は、セッション単位ではなく、呼び出し単位の合成推定値です。 trace-mcp 3.31.0（76996eb9）で2026年9月21日に測定しました。事前登録では、測定前に設定した25%の基準を初めて通過した結果として公開しています。同時に、この通過は製品の高速化ではなく、サンプリングフレームの登録によるものだとも述べています。実行前に記した予測では、結果が上回る区間を示していました。これは誤りであり、そのまま掲載しています。

ベンチマークラボ — アプリが同じ質問をします。 デスクトップアプリの「ベンチマークラボ」タブでは、3つのアームにわたる8件の固定された想起フィクスチャを実行し、すべての実行結果を ~/.trace/benchmark-runs に保存します。trace-mcp 3.33.0（4e1ac4fd）で2026年9月26日に測定したところ、ファイル読み取りの対照群は13回の呼び出しで82,412トークンを使用し、8問すべてに回答しました。最小アームは512トークンで8問中7問に回答（−99.4%）、標準アームは13,657トークンで8問すべてに回答（−83.4%）しました。最小アームの不正解は実測結果です。生の search_text では src/indexer/pipeline.ts が上位10件にランクインしません。この結果は、合格するまで再実行するのではなく、そのまま公開しています。測定方法、バッテリーのハッシュ、再実行 →

ベンチマーク：trace-mcp のコードベース自体（694ファイル、3,831シンボル → v1.30では929ファイル、5,197シンボル）：

Task                    Without trace-mcp    With trace-mcp    Reduction
───────────────────────────────────────────────────────────────────────────
Symbol lookup                42,518 tokens       1,162 tokens       97.3%
File exploration             27,486 tokens         855 tokens       96.9%
Search                       22,860 tokens       8,000 tokens       65.0%
Find usages                  11,430 tokens       1,720 tokens       85.0%
Context bundle               12,847 tokens       3,485 tokens       72.9%
Batch overhead               16,831 tokens       8,299 tokens       50.7%
Impact analysis              49,141 tokens       1,856 tokens       96.2%
Call graph                  178,345 tokens       9,285 tokens       94.8%
Type hierarchy               94,762 tokens         855 tokens       99.1%
Tests for                    22,590 tokens       1,150 tokens       94.9%
Composite task              223,721 tokens      14,245 tokens       93.6%
───────────────────────────────────────────────────────────────────────────
Total                       702,532 tokens      50,812 tokens       92.8%

11種類の構造化タスク全体で、エージェントがファイルを読み直す代わりにグラフを再利用すると、再計算量は呼び出しあたり最大約99%減少します。これは、サポートが充実したTS/Vueコードベースでの、構造化タスクにおけるピーク時の結果とお考えください。すべてのプロジェクトで期待できる数値ではありません。本番環境の混合ワークロードで期待できるのは、上記の実測値である**67.4%**です。この合成結果ではありません。コンテキスト内のノイズが減ることで、ハルシネーションが減り、初回応答の精度も向上します。これはトークン数には表れない品質面のメリットです。

節約量はプロジェクトの規模に応じて増加します — これは主張であり、実測値ではありません。trace-mcpを使わない場合、エージェントは正しいファイルを見つけるまでに、より多くの誤ったファイルを読みます。一方、グラフの走査は、全ファイル数に対する O ではなく、関連エッジ数に対する O です。プロジェクト規模ごとの測定値はないため、このREADMEでは数値を引用していません。以前ここに記載していたセッションあたりのトークン数は、「40–50%」と同じく、#915より前の推定器によるものでした。

複合タスクで最大の効果が得られます。 1回の get_task_context 呼び出しで、約10回の連続した操作（search → get_symbol × 5 → Read × 3 → Grep × 2）を置き換えられます。これは10回ではなく1回のラウンドトリップであり、レイテンシ削減の大部分はここから生まれます。

自分で実行する

npx trace-mcp benchmark .

実際のリポジトリでカテゴリごとのトークン削減量を約5分で確認できます。インストールも登録も不要で、すべてローカルで実行されます。既存のインデックスを読み込むため、プロジェクトがまだ登録されていない場合は、まず trace-mcp index . を実行してください。上記の数値は、構造化ベンチマークにおける trace-mcp 自身の TypeScript/Vue コードベース（929ファイル、5,197シンボル）のものです。混合ワークロードでの本番環境における削減率はこれより低く（実測値は67.4％。上記参照）、タスクごとの傾向は、サポート対象のスタックであればどれでも当てはまります。

これは合成による推定値であり、実測された削減量ではありません。「trace-mcp なし」の値はインデックス内のファイルサイズから算出し、「trace-mcp あり」の値はシナリオごとの倍率から算出しています。実際のツール呼び出しに基づくものではありません。理論上の上限を示しています。ご自身の利用状況で実際の削減量を測定するには、trace-mcp をしばらく実行してから、次の操作を行ってください。

trace-mcp analytics savings   # real sessions: reads vs. what trace-mcp would have cost
trace-mcp analytics optimize  # recommendations based on your actual usage

詳しくは、セッション分析とトークン削減量の追跡をご覧ください。

# Via CLI (no install)
npx trace-mcp benchmark /path/to/project

# Or via MCP tool
benchmark_project  # runs against the current project

主な機能

• リクエストフローのトレース — URL → Route → Middleware → Controller → Service を、バックエンドフレームワーク全体で追跡します
• コンポーネントツリー — props／emits／slots を含むレンダリング階層（Vue、React、Blade）
• マイグレーションからスキーマを取得 — データベース接続は不要です
• イベントチェーン — Event → Listener → Job のファンアウト（Laravel、Django、NestJS、Celery、Socket.io）
• 変更影響分析 — 言語をまたいだ依存関係の逆方向トラバースを、関連するアーキテクチャ上の決定で強化します
• グラフを活用したタスクコンテキスト — 開発タスクを説明すると、最適なコードサブグラフ（実行パス、テスト、型）と関連する過去の決定を取得します。バグ修正／機能追加／リファクタリングの意図に応じて調整されます
• 呼び出しグラフと DI ツリー — 4 段階の解決信頼度を備えた双方向の呼び出しグラフ、コンパイラー級の精度を実現するオプションの LSP 強化、NestJS の依存性注入
• ORM モデルのコンテキスト — 7 種類の ORM のリレーションシップ、スキーマ、メタデータ
• デッドコードとテスト不足の検出 — テストされていないエクスポート／シンボル（「未到達」と「インポート済み・未呼び出し」の分類付き）、デッドコード、影響分析におけるシンボルごとのテスト到達状況を検出します
• セキュリティスキャン — OWASP Top-10 パターンのスキャンとテイント分析（ソース→シンクのデータフロー）。skill-scan 用にエクスポート可能な MCP サーバーセキュリティコンテキスト
• セマンティック検索（デフォルトでオフライン） — 同梱の ONNX エンベディングがすぐに使え、API キーは不要です。LLM による要約には Ollama／OpenAI に切り替えられます
• 決定メモリー — セッションから決定事項を抽出し、シンボル／ファイルに紐付けて、影響分析で自動的に提示します
• マルチサービスのサブプロジェクト — API コントラクトを介してサービス間のグラフをリンクし、サービス横断の影響分析とサービス単位の決定事項に対応します
• CI／PR の変更影響レポート — すべての PR で、影響範囲、リスクスコア、テスト不足の検出、アーキテクチャ違反を自動的に報告します

対応スタック

言語： PHP、TypeScript、JavaScript、Python、Go、Java、Kotlin、Ruby、Rust、C、C++、C#、Swift、Objective-C、Objective-C++、Dart、Scala、Groovy、Elixir、Erlang、Haskell、Gleam、Bash、Lua、Perl、GDScript、R、Julia、Nix、SQL、PL/SQL、HCL/Terraform、Protocol Buffers、GraphQL、Prisma、Vue SFC、HTML、CSS/SCSS/SASS/LESS、XML/XUL/XSD、YAML、JSON、TOML、Assembly、Fortran、AutoHotkey、Verse、AL、Blade、EJS、Zig、OCaml、Clojure、F#、Elm、CUDA、COBOL、Verilog/SystemVerilog、GLSL、Meson、Vim Script、Common Lisp、Emacs Lisp、Dockerfile、Makefile、CMake、INI、Svelte、Astro、Markdown、MATLAB、Lean 4、FORM、Magma、Wolfram/Mathematica、Ada、Apex、D、Nim、Pascal、PowerShell、Solidity、Tcl

フレームワーク： Laravel（+ Livewire、Nova、Filament、Pennant）、Django（+ DRF）、FastAPI、Flask、Express、NestJS、Fastify、Hono、Next.js、Nuxt、Rails、Spring、tRPC

ORM： Eloquent、Prisma、TypeORM、Drizzle、Sequelize、Mongoose、SQLAlchemy

フロントエンド： Vue、React、React Native、Blade、Inertia、shadcn/ui、Nuxt UI、MUI、Ant Design、Headless UI

その他： GraphQL、Socket.io、Celery、Zustand、Pydantic、Zod、n8n、React Query/SWR、Playwright/Cypress/Jest/Vitest/Mocha

ナレッジ保管庫： Obsidian、Logseq、プレーンな Markdown — [[wikilinks]]、![[embeds]]、[text](path.md)、フロントマター（YAML）、#tags、ATX 見出し。各ノートは note:<basename> シンボルとなり、その中にセクションがネストされます。wikilinks はノート間の references／embeds エッジに解決されます。保管庫とコードを同じプロジェクトに混在させることもできます。両方を含むディレクトリを root に指定し、find_usages を一度実行してください。

詳細はこちら：対応フレームワーク · すべてのツール

クイックスタート

まずは無駄を確認しましょう — 5 分、セットアップもサインアップも不要です：

npx trace-mcp benchmark .

プロジェクトにインデックスを作成し、11 種類の構造化タスクベンチマーク（シンボル検索、影響分析、呼び出しグラフ、型階層など）を実行して、タスクごとの推定トークンコストを表示します — トレースなしの場合とありの場合を比較できます。エージェントが再利用できる作業をどこで再計算しているかを正確に確認できます。これはインデックスから算出した合成推定値であり、実際のツール呼び出しの記録ではありません（上記の「トークン削減」の下にある方法論のブロックを参照）。実際のセッションで測定した削減量を確認するには、trace-mcp analytics savings を使用してください。

次に、AI エージェントに接続します：

npm install -g trace-mcp
trace init        # one-time global setup (MCP clients, hooks, CLAUDE.md)
trace add         # register current project for indexing

• init — MCP クライアント（Claude Code、Cursor、Windsurf、Claude Desktop など）を設定し、ガードフックをインストールして、ルーティングルールを ~/.claude/CLAUDE.md に追加します。
• add — フレームワークを検出し、プロジェクトごとのインデックスを作成して、プロジェクトを登録します。trace に認識させたい各プロジェクトで、もう一度実行してください。

（npm パッケージ名は引き続き trace-mcp です — 短縮されるのはインストールされるコマンド名だけです。trace-mcp init、trace-mcp add、その他すべての trace-mcp … 呼び出しは引き続き使用できます。）

すべての状態は ~/.trace/ に保存されます（~/.trace-mcp/ から自動的にフォールバックします）。.traceignore または .trace/.config.json を使わない限り、プロジェクトディレクトリはクリーンな状態に保たれます。

Claude Code または Codex CLI をお使いですか？ npm install -g trace-mcp の後、trace init のクライアント接続手順を省略して、プラグインを直接インストールしてください — どちらの方法でも git clone は不要です：

# Claude Code
claude plugin install @nikolai-vysotskyi/trace-mcp

# Codex CLI
codex plugin marketplace add nikolai-vysotskyi/trace-mcp
codex plugin install trace-mcp@nikolai-vysotskyi-trace-mcp

どちらも、trace-mcp MCP サーバーと Bash ガードフックを一度の手順で登録します。詳細はこちら：.claude-plugin/README.md · .codex-plugin/README.md。

次に、MCP クライアントで：

> get_project_map to see what frameworks are detected
> get_task_context("fix the login bug") to get full execution context for a task
> get_change_impact on app/Models/User.php to see what depends on it

Markdown の保管庫（Obsidian／Logseq／プレーンな MD）のインデックス作成。 保管庫のルートを trace add に指定してください — .md／.mdx／.markdown はデフォルトで対象になります。各ノートは note:<basename> シンボルになり、見出しはセクションとしてネストされ、[[wikilinks]] と ![[embeds]] はグラフのエッジに解決されます。フロントマターの aliases: によって別名でも解決できるようになり、#tags は集約されるため、#sgr を含むすべてのノートを find_usages で見つけられます。

> find_usages on note:my-concept     // backlinks across the vault
> find_usages on tag:sgr             // every note tagged #sgr
> get_change_impact on note:legacy   // what breaks if I rename or delete it
> search "schema-guided reasoning"   // PageRank + embeddings over the vault

GUI をお好みですか？デスクトップアプリを使えば、ターミナルに触れることなく、インストール、インデックス作成、MCP クライアントへの接続、再インデックス作成を行えます。

さらに詳しく：プロジェクトの追加／アップグレード／手動セットアップ · stdio と HTTP のセットアップ（リポジトリ単位またはチーム単位） · セマンティック検索（ローカル ONNX） · インデックス作成とファイルウォッチャー · .traceignore。

trace-mcp から trace への移行

プロジェクト名は引き続き trace-mcp です。コマンド名が trace になりました。 名前変更が適用されるのは、この境界だけです。それ以外は変更されません。npm パッケージ、リポジトリ、ドメイン、レジストリエントリの名前はすべて trace-mcp のままです。これは、ripgrep の rg や kubernetes の kubectl と同じく、使いやすさを理由とするものです。トークン削減が目的ではありません。MCP ツールのプレフィックスが短くなることで削減されるトークン数は実測でも確かにありますが、その量はわずかです。トークナイザーとプリセットに応じて、1 ターンあたり 66～366 トークン、すでに 8k～45k トークンを消費するツールリストの 0.74～1.23% です。

npm パッケージ名は変わりません。 引き続き trace-mcp であり、今後も変わりません。npm 上の trace は、別の作者による無関係なパッケージです。npm install -g trace-mcp または npx -y trace-mcp@latest でインストールしてください。

変更されるものと、変更されないものは次のとおりです。

• コマンド名 — 新しい表記は trace <cmd> です。trace-mcp <cmd> はエイリアスとして今後もずっと残ります。macOS では /usr/bin/trace は Apple 独自の trace(1) なので、スクリプト、CI、自分で管理していない PATH では、引き続き trace-mcp を使用してください。
• MCP クライアントのエントリ — trace init と trace upgrade は、既存の mcpServers["trace-mcp"] エントリを mcpServers["trace"] に変更し、新しいコマンドを指定します。削除されるものはありません。trace-mcp のままのエントリも引き続き動作しますが、トークンをより多く消費します。
• 状態ディレクトリ — ~/.trace/ を使用します。旧ディレクトリが存在し、新しいディレクトリが存在しない場合は ~/.trace-mcp/ にフォールバックします。インデックスは再構築されません。
• プロジェクト設定 — .trace.json を先に読み込み、その後に .trace-mcp.json を読み込みます。既存のファイルは、現在の場所で引き続き使用できます。
• プラグインとレジストリの識別子 — 変更されません。Claude Code プラグインは @nikolai-vysotskyi/trace-mcp、MCP レジストリでは io.github.nikolai-vysotskyi/trace-mcp です。

init では対応できないことが 1 つあります。 MCP ツールのプレフィックスも変わります。mcp__trace-mcp__search は mcp__trace__search になります。init は自身が管理する mcpServers エントリを移行しますが、自分で記述したテキストは対象外です。これには、Claude Code の権限許可リスト、フックのマッチャー、CLAUDE.md／AGENTS.md の本文に記載した独自の mcp__trace-mcp__* の記述が含まれます。アップグレード後にフックがマッチしなくなったり、許可リストに登録したツールで再度確認を求められたりした場合は、自分の設定で mcp__trace-mcp__ を検索し、mcp__trace__ に置き換えてください。上記以外は、次回 trace init または trace upgrade を実行すると自動的に処理されます。詳細：設定。

ローカルファーストな設計

trace-mcp はすべてお使いのマシン上で動作します。ソースコードがアップロードされることはなく、アカウントを作成する必要もありません。

• インデックス作成はローカルで行われます。 MCP サーバーは、お客様自身が実行する Node プロセスです。stdio または http://127.0.0.1:3741 で動作します。
• インデックスは ~/.trace/ に保存されます（すでに ~/.trace-mcp/ をお使いの場合は、そちらを使用します）。プロジェクト内に保存されることも、アップロードされることもありません。.traceignore または .trace/.config.json を利用しない限り、リポジトリのディレクトリはクリーンなままです。
• セマンティック検索はデフォルトでオフラインです。ONNX 埋め込みモデルがバンドルされているため、API キーも外部への通信も不要です。設定で Ollama（ローカル）または OpenAI（オプトイン）に切り替えられます。
• コード、クエリ、利用状況に関するテレメトリーはありません。 お使いのマシンから外部に送信されるのは、以下およびプライバシーページに記載されているものだけです。それ以外が送信されることはありません。
• AI クライアントが認識する情報は、その AI クライアントの仕様に従います。 trace-mcp は MCP 経由でグラフの結果を返します。それを Claude Code／Cursor／Codex／Windsurf がモデルにどう渡すかは、各クライアントのプライバシーモデルに委ねられています。
• デーモンが信頼するのはループバックだけです。 serve-http は意図的に認証なしで動作します。127.0.0.1 上の呼び出し元は、すでにお客様自身だからです。そのため、--allow-remote を指定し、ポートの前段に独自の認証を配置しない限り、ループバック以外の --host は拒否されます。詳しくは設定をご覧ください。
• すべてを消去するには、~/.trace/（まだ移行していないインストールでは ~/.trace-mcp/）を削除してください。このディレクトリにすべてのデータが含まれています。

利用状況テレメトリー

trace-mcp は、アクティブなインストール数を集計するため、インストールごとに 1 日あたり最大 1 回、匿名の ping を送信します。送信されるのは、バージョン、OS、MCP クライアント、および集計された件数です。コード、パス、IP アドレス、またはお使いのマシンでローカルに生成された UUID 以外のインストール識別子は送信されません。CI では送信が抑制されます。また、送信先を確認できるよう、GA4 の認証情報は公開バンドルにプレーンテキストで含まれています。

TRACE_MCP_TELEMETRY=off を設定するか、~/.trace/.config.json に "telemetry": { "usage_ping": false } を設定すると無効にできます。

送信されるフィールドの全一覧、どちらのオプトアウト方法も、ローカル状態の削除方法も、プライバシーページに記載されています。ソース： src/telemetry/usage-ping.ts。

セキュリティ上の配慮が必要な環境では、使用前に SECURITY.md をご確認ください。

trace-mcp を最大限に活用する

trace-mcp は 3 つのレベルで動作し、AI エージェントがファイルを直接読み取る代わりに、trace-mcp のツールを使うようにします。

レベル 1：自動（そのまま使えます）

MCP サーバーは、AI エージェントが標準の Read／Grep／Glob より trace-mcp を優先すべき場面を示すルーティングヒント付きの指示とツールの説明を提供します。MCP 互換クライアントであれば、設定なしで利用できます。

レベル 2：CLAUDE.md（推奨）

trace-mcp init は、~/.claude/CLAUDE.md（またはプロジェクトの CLAUDE.md）に Code Navigation Policy ブロックを追加します。このブロックにより、タスクの種類ごとに、Read／Grep／Glob より優先すべき trace-mcp ツールをエージェントに指示します。init をスキップした場合は、完全なブロックと適用の調整方法について、システムプロンプトのルーティングをご覧ください。

レベル 3：フックによる強制（Claude Code のみ）

強制力を高めるため、trace-mcp init は PreToolUse ガードフックをインストールします。これにより、ソースファイルに対する Read／Grep／Glob をブロックし、エージェントを trace-mcp のツールに誘導します（コード以外のファイル、Edit 前の Read、安全な Bash コマンドはそのまま実行できます）。手動で管理するには、trace-mcp setup-hooks --global／--uninstall を実行します。詳しくはシステムプロンプトのルーティングをご覧ください。

レベル 4：Max ティア — システムプロンプトの書き換え＋エージェントの動作ルール

trace-mcp init で Max を選択すると（デフォルト）、さらに 2 つの強化機能が適用されます。

• tweakcc によるシステムプロンプトの書き換えで Claude Code のコアツールの説明をパッチし、モデルが最初から「Grep を使う」ではなく「trace-mcp search を使う」と理解するようにします。Claude Code のみ。
• agent_behavior: "strict" では、MCP の指示を通じて簡潔な規律ルールを適用します。お世辞を言わない、誤った前提には異議を唱える、決して捏造しない、目標に沿って実行する、セッションの衛生管理は 2 ストライク制、ついでのリファクタリングはしない、というルールです。クライアントを問わず（Claude Code、Cursor、Codex、Windsurf）適用され、init を再実行しなくても npm upgrade trace-mcp で自動更新されます。

誰にも設定を求めず、すべてのチームメンバーのエージェントに同じ規律ルールを適用するための設定です。~/.trace/.config.json の tools.agent_behavior で調整または無効化できます。詳しくはツールの公開とエージェントの動作をご覧ください。

意思決定の記憶

AI エージェントとの会話で生まれた意思決定、トレードオフ、発見は、通常セッションの終了とともに消えてしまいます。trace-mcp はそれらを記録し、各意思決定を関連するコードにリンクします。そのため、後から誰かが src/db/connection.ts::Pool#class に対して get_change_impact を実行すると、「JSONB のために PostgreSQL を選んだ」という意思決定が自動的に表示されます。

• 抽出 — mine_sessions は Claude Code / Claw Code の JSONL ログをスキャンし、パターンマッチングで意思決定を抽出します（LLM の呼び出しは 0 回）。種類：アーキテクチャ、技術選定、バグの根本原因、トレードオフ、規約。
• リンク — 各意思決定をシンボルまたはファイルに紐付けます。サブプロジェクト単位の意思決定にも対応します。
• 表示 — 意思決定は get_change_impact、plan_turn、get_wake_up を自動的に補足します。時間的な有効性（valid_from／valid_until）により、「2025-01-15 時点で正しかったことは何か？」というクエリが可能になります。
• 検索 — 意思決定には query_decisions（FTS5 ＋フィルター）を、過去のすべてのセッションにわたる生の会話内容には search_sessions を使用します。

trace memory mine                           # extract decisions from sessions
trace memory search "GraphQL migration"     # search past conversations
trace memory timeline --file src/auth.ts    # decision history for a file

ツールの全一覧、CLI、時間的な有効性、サービス単位のスコープ設定については、意思決定の記憶をご覧ください。

サブプロジェクト

サブプロジェクトとは、マイクロサービス、フロントエンド、共有ライブラリ、CLI ツールなど、プロジェクトのエコシステム内にある任意のリポジトリです。trace はサブプロジェクト間の依存関係グラフをリンクします。サービス A がサービス B のエンドポイントを呼び出している場合、B のエンドポイントを変更すると、A に対する破壊的変更として表示されます。

検出は自動で行われます。インデックス作成のたびに、trace はサブプロジェクト（Docker Compose、フラット／グループ化されたワークスペース、モノリスへのフォールバック）を検出し、API コントラクト（OpenAPI、GraphQL SDL、Protobuf/gRPC）を解析し、コード内の HTTP クライアント呼び出し（fetch、axios、Http::、requests、http.Get、gRPC スタブ、GraphQL オペレーション）をスキャンして、その呼び出しを既知のエンドポイントにリンクします。

cd ~/projects/my-app && trace add
# → auto-detects user-service (openapi.yaml) and order-service
# → links order-service → user-service via /api/users/{id}

trace subproject impact --endpoint=/api/users
# → [order-service] src/services/user-client.ts:42 (axios, confidence: 85%)

外部サブプロジェクトは trace subproject add --repo=... --project=... で手動追加できます。MCP ツール：get_subproject_graph、get_subproject_impact、get_subproject_clients、subproject_add_repo、subproject_sync。

CLI の全容、検出モード、MCP ツールのリファレンス、トポロジー設定については、設定 — トポロジーとサブプロジェクトをご覧ください。

CI／PR の変更影響レポート

trace ci-report --base main --head HEAD は、プルリクエストごとに Markdown または JSON 形式のレポートを生成します。内容は概要、影響範囲（深さ 2 の逆依存関係のたどり）、テストカバレッジの不足（シンボルごとの hasTestReach）、リスク分析（複雑さ 30% ＋変更頻度 25% ＋結合度 25% ＋影響範囲 20%）、アーキテクチャ違反（クリーン／ヘキサゴナルのプリセットを自動検出）、および新たに発生した未使用のエクスポートです。

--fail-on high を使うと、リスクの高い変更がある場合にマージをブロックできます。すぐに使える GitHub Action については .github/workflows/ci.yml をご覧ください。このアクションは build → test → impact-report を実行し、プッシュのたびにプルリクエストへ固定コメントを投稿します。

パイロットプログラム — LLMを本番環境で運用しているチーム向け

本番環境でAI機能（社内コパイロット、顧客向けアシスタント、コードまたはナレッジベースを対象としたRAGなど）を提供しており、コスト、レイテンシ、品質の限界に直面している場合は、重点を絞ったパイロットを一緒に実施します。

形式： 2～4週間。統合は最小限です。実際の本番ユースケースを1つまたは2つ対象とし、デモでは終わりません。

測定する項目（導入前／導入後）：

• 正常に回答できたケースあたりのトークン数
• 初回応答の精度（再試行なしで解決したクエリの割合）
• 再試行とフォールバック呼び出し
• エンドツーエンドのレイテンシ
• 固定の評価セットにおけるユーザー成功率

得られるもの： コンテキスト最適化によって、お使いのスタックで重要な指標が改善するかどうかを示す、明確な導入前／導入後レポートです。また、コストを理由に利用を制限するのではなく、確信を持って利用を拡大するための道筋も得られます。

目指すのは、一時的なコスト削減ではなく、利用が増えても予測可能性を保つシステムです。チームは通常、まず信頼性の高い本番環境への導入を実現し、その後にLLMの活用範囲を広げたいと考えています。

お問い合わせ： pilot タグを付けて github.com/nikolai-vysotskyi/trace-mcp/issues にイシューを作成するか、@nikolai-vysotskyi までご連絡ください。

仕組み

Source files (PHP, TS, Vue, Python, Go, Java, Kotlin, Ruby, HTML, CSS, Blade)
    │
    ▼
┌──────────────────────────────────────────┐
│  Pass 1 — Per-file extraction            │
│  tree-sitter → symbols                   │
│  integration plugins → routes,           │
│    components, migrations, events,       │
│    models, schemas, variants, tests      │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Pass 2 — Cross-file resolution          │
│  PSR-4 · ES modules · Python modules    │
│  Vue components · Inertia bridge         │
│  Blade inheritance · ORM relations       │
│  → unified directed edge graph           │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Pass 3 — LSP enrichment (opt-in)       │
│  tsserver · pyright · gopls ·           │
│  rust-analyzer → compiler-grade         │
│  call resolution, 4-tier confidence     │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  SQLite (WAL mode) + FTS5               │
│  nodes · edges · symbols · routes       │
│  + embeddings (local ONNX by default)   │
│  + optional: LLM summaries              │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Decision Memory (decisions.db)         │
│  decisions · session chunks · FTS5      │
│  temporal validity · code linkage       │
│  auto-mined from session logs           │
└────────────────────┬─────────────────────┘
                     │
                     ▼
          MCP server (stdio or HTTP/SSE)
          182 tools · 10 resources

デフォルトでインクリメンタル — ファイルはコンテンツハッシュで管理され、変更されていないファイルは再インデックス時にスキップされます。

プラグインアーキテクチャ — 言語プラグイン（シンボル抽出）と統合プラグイン（セマンティックエッジ）はプロジェクトの検出結果に基づいて読み込まれ、フレームワーク、ORM、ビュー、API、バリデーション、状態、リアルタイム、テスト、ツールのカテゴリに分類されます。

詳細：アーキテクチャとプラグインシステム — インデックス作成の仕組み

ドキュメント

ドキュメント全文は trace-mcp.com にあります（このリポジトリの docs/ と同じ内容です）。

Star History

Project health

License

MIT

Built by Nikolai Vysotskyi