MCP Intelligence Context

リポジトリのファイル、シンボル、インポート、依存関係グラフをインデックスし、Copilot やエージェントにリポジトリ全体をスキャンさせる代わりに、小さく焦点を絞ったコンテキストパッケージを渡す Repository Intelligence MCP サーバーです。

なぜ

エージェントが巨大なリポジトリについてあいまいな質問を受けたとき、関連するコードにたどり着くまでに、何度もディレクトリを一覧したり、無関係なファイルを開いたり、構造を再導出したりすることがよくあり、トークンと時間を費やします。このプロジェクトは、リポジトリの永続的かつ段階的に更新されるインデックス（ファイル、シンボル、インポート、逆依存関係）を構築し、クエリに関連するコンテキストだけをおおよそのトークン予算付きで返す MCP ツールを提供します。

Related MCP server: lens

仕組み

1. index_repository はリポジトリを走査し（.gitignore を尊重）、Python（ast 経由）と JS/TS（軽量な正規表現ヒューリスティック経由）ファイルの関数・クラス・メソッド・インポート・エクスポートを解析し、逆依存関係グラフを構築します。インデックスは .mcp_intel_cache/index.json にキャッシュされ、増分更新されます（mtime/サイズに基づき、変更されたファイルのみ再解析）。

2. search_code / get_relevant_context は、シンボル名、ファイル名、docstring/要約、インポート一致率でファイルをランク付けし（字句/シンボル検索。この MVP では埋め込みなし）、トークン予算内のコンテキストパッケージ（ファイル全体ではなくシンボル表＋小さなコード抜粋）を返します。get_relevant_context はまた、単純な全リポジトリ走査ベースラインと比較した token_savings を報告するため、削減効果がツールの応答自体に表れます。

3. get_file_summary / get_dependencies は、ファイル全体を読まずに、特定のファイルのシンボルや影響範囲（インポート元/インポート先）を調べることができます。

4. ツールは、キャッシュされたインデックスが5分以上経過し、かつ稼働中のウォッチャーがない場合、陳腐化の警告を報告します。実際には、リポジトリへの最初のツール呼び出し時にバックグラウンドのファイルウォッチャー（watchdog）が起動し、作成・変更・削除イベントを即座にメモリ内インデックスに適用するため、コード変更中もインデックスは継続的に最新の状態に保たれます（セッション内での手動再インデックス不要）。ディスクキャッシュへのフラッシュはデバウンス（約2秒）されるため、キース動ごとの書込みは発生しません。

リポジトリ構成

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

クイックスタート（新規ユーザー向け）

MCP と VS Code でこれをすぐ使いたい場合の手順です：

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

このスクリプトが行う処理：

1. pipx で mcp-intelligence-context をインストール（または更新）。

2. このワークスペースに .vscode/mcp.json を書き込む。

3. MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder} を設定することで、現在のワークスペースフォルダだけにインデックスを限定する。

その後 VS Code で：

1. コマンドパレット → MCP: List Servers。

2. mcp-intelligence-context を起動/再起動。

3. Copilot Chat のツールピッカーで mcp-intelligence-context を有効化。

スクリプトが pipx がないと表示したら、一度インストールしてください：

brew install pipx
pipx ensurepath

MCP サーバーのスタンドアロン実行

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

インデックス対象のリポジトリは MCP_INTEL_REPO_ROOT を設定するか、ツール呼び出しに明示的に repo_root を渡すかして指定します（デフォルトはサーバーの現在の作業ディレクトリ）。

このリポジトリをクローンせずにインストールする

他のユーザーはローカルチェックアウト不要で、Git リポジトリから直接インストールできます（PyPI に公開されればそこからも）：

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

mcp-intelligence-context のコンソールスクリプトと MCP_INTEL_REPO_ROOT 環境変数はどちらの場合もまったく同じ動作をします。違うのは pip install の取得先だけです。

MCP クライアント（例 VS Code）への登録

対象ワークスペースの .vscode/mcp.json に追加します：

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code 拡張機能

vscode-extension/ は、次の3コマンドをまとめた軽量ラッパーを含みます：

• MCP Intelligence: Setup Server — venv を作成して Python パッケージをインストールし、上記の .vscode/mcp.json エントリを書き込みます。

• MCP Intelligence: Reindex Repository — 開いているワークスペースを強制的に再インデックスします。

• MCP Intelligence: Show Status — キャッシュされたインデックスのファイル数、git commit、経過時間を表示します。

デフォルトでは "Setup Server" は、このプロジェクトの git リポジトリからパッケージを拡張機能のプライベートストレージ下の venv にインストールします。ローカルクローンは不要です。これを制御する設定が2つあります :

• mcpIntelligenceContext.serverPath — ローカルの編集可能なチェックアウトを指定します（このモノレポでの開発用）。それ以外の場合は空のままにします。

• mcpIntelligenceContext.pythonPackageSource — serverPath が空の場合に pip インストール先（例 PyPI パッケージ名）を上書きします。

ビルド手順：

cd vscode-extension
npm install
npm run compile

その後、VS Code で（vscode-extension/ を開いた状態で）F5 を押すと、Extension Development Host が起動します。

利用可能な MCP ツール

これが実際に役立つかの評価

eval/ には、このリポジトリのコード自体を対象とした小さくて公正なベンチマークが含まれています（LLM コールなし、数値の作り込みなし）。既知の正解ファイルを持つ手書きクエリ10件で、インデックス化ツールを素朴なベースライン（ツリー表示、grep、一致するファイル全体の読み込み）と比較します。

.venv/bin/python eval/run_eval.py

hit@1/hit@3（トップ結果が適切なファイルを指しているか）、平均トークン削減量、待機時間を報告します。これは検索/トークンの仕組みだけを測定するもので、実際の Copilot の返答が良くなるかを測定するわけではありません。それには生のモデル呼び出しが必要だからです。

現時点の制限事項（MVP）

• JS/TS の解析は正規表現ベース（完全な型ではなく非AST）のため、特殊な構文を見落とす可能性があります。Python は標準の ast モジュールを使用しており、正確です。

• 検索は語彙・シンボルベースのみ（ストップワードの除去と複数のシグナルによる累積スコアリング）。埋め込みや意味的検索はまだありません。

• ファイルウォッチャーはファイルごとの変更は反映しますが、実行中に .gitignore 自体の変更を再走査しません。.gitignore を編集した場合は、index_repository を refresh=true で一度実行して新しいルールを取り込んでください。

広範・本番利用前のセキュリティ検討事項

修正済みの項目：

• シェルインジェクション — VS Code 拡張は以前、ワークスペース設定をシェルコマンド文字列に埋め込んでいましたが、現在はシェルを使わず引数配列で execFile を使用し、信頼できないワークスペースでは "Setup Server" の実行を拒否します。

• シンボリックリンク逃が逃脱 — ウォーカーはリポジトリルートの外に解決するシンボリックリンクをスキップします（埋め込まれたリンクによる /etc/passwd などのファイル露出を防ぎます）。

• シークレットの漏洩 — 一般的な資格情報パターン（.env、*.pem、id_rsa、credentials.json など、config.py の SENSITIVE_FILENAME_PATTERNS を参照）に一致するファイル名は、gitignored でなくてもスキップされ、ツール出力に内容が含まれることはありません。

• 壊れたキャッシュによるクラッシュ — 破損や改ざんされた .mcp_intel_cache/index.json が、起動時にサーバーをクラッシュさせるのではなく、きれいな再構築を行うようになりました。

• ReDoS — JS/TS の正規表現パーサーは、過度に長い行（minified ファイル）をスキップして、壊滅的なバックトラッキングによる DoS を防ぎます。

• 無制限の repo_root — MCP_INTEL_ALLOWED_ROOTS（: 区切りの絶対パスリスト）を設定すると、サーバーがインデックスできるディレクトリを制限できます。デフォルトでは未設定のため、現在の柔軟なシングルユーザー向け動作を維持しています。

まだ構造上の課題、完全には解決していないもの（単一のローカルユーザーを超えて展開する前に読むこと）：

• 共有/マルチテナントのネットワークサービスとしては安全機能ではありません。 これはローカル向けに設計されており、ユーザーごとに1プロセスのstdioサーバです。メモリ内のインデックス/ウォッチャーキャッシュには、ユーザーごとの分離も認証もありません。呼び出し元ごとのサンドボックスと認証を追加せずに、共有 HTTP/SSE エンドポイントとして公開しないでください。

• 依存関係は固定されていません（>= のみ）。再現可能で検証済みの本番インストールには、正確なバージョン固定やロックファイルを使用してください（実際にこの制約で mcp 1.x から 2.0 への重大な API 変更で一度問題になりました）。

• このコードベースへの自動リグレッションテストは未だありません — 現在の変更検証は手動の eval/ ハーネスとアドホック実行で行われ、CI でゲートされたテストスイートではありません。