mcp-deepcontext

Claude Codeでシンボルを認識したセマンティック検索を可能にするMCPサーバー

動機

ほとんどのコード検索ツールはコードをテキストとして扱い、コードに意味を与えるセマンティックな構造を無視しています。大規模なコードベースで作業しているとき、単に文字列が出現する場所を見つけたいだけではありません。関数がどこで呼び出されているか、型がどこで実装されているか、あるいはどのモジュールが特定のシンボルに依存しているかを知りたいはずです。

このMCPサーバーは、セマンティックなコード分析機能をClaudeに公開することで、そのギャップを埋めます。Claudeはテキストをgrepする代わりに、「このインターフェースはどこで実装されていますか？」や「この関数の呼び出し元はすべてどこですか？」といった質問をして、正確でシンボルを認識した結果を得ることができます。これにより、馴染みのないコードベースについて実際に役立つ対話が可能になります。

アーキテクチャ

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

はじめに

インストール

npm install -g mcp-deepcontext

クイックスタート

Claude Desktopの設定（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

その後、Claude Desktopを再起動してください。サーバーは起動時にコードベースをインデックス化します。

仕組み

このサーバーはTypeScriptコンパイラAPIを使用して、コードベースの完全なシンボルグラフを構築します。これには、型定義、関数シグネチャ、クラス階層、インポート関係が含まれます。Claudeが情報を照会すると、サーバーは正確な場所とコンテキストで応答できます。

セマンティック検索のために、サーバーはコードシンボルとその周囲のコンテキストの埋め込みを生成します。これにより、正確なテキストではなく、意図に基づいた曖昧一致が可能になります。シンボルデータベースは、インクリメンタルな再インデックスをトリガーするファイルウォッチャーを通じて、ファイルの変更と同期が保たれます。

MCPプロトコルは、search_symbols、find_references、get_definition、find_implementationsといったツールを通じてこれを公開します。Claudeはこれらを連鎖させて、コードの構造や関係性に関する複雑な質問に答えることができます。

設定

サーバーは以下のコマンドライン引数を受け付けます：

• --workspace <path>: インデックス化するプロジェクトのルートディレクトリ（必須）

• --languages <list>: インデックス化する言語のカンマ区切りリスト（デフォルト: typescript,javascript）

• --exclude <patterns>: 除外するグロブパターン（デフォルト: node_modules,dist,build,.git）

• --max-file-size <bytes>: これより大きいファイルはスキップ（デフォルト: 1MB）

• --embedding-model <name>: 埋め込みに使用するモデル（デフォルト: text-embedding-3-small）

環境変数：

• OPENAI_API_KEY: 埋め込み生成に必須

• DEEPCONTEXT_LOG_LEVEL: 詳細なログを出力するには debug に設定

FAQ

Q: どの言語がサポートされていますか？

現在はTypeScriptとJavaScriptで、完全な型認識に対応しています。PythonとGoのサポートも予定されています。

Q: 大規模なコードベースでも動作しますか？

はい、インデックス化はインクリメンタルに行われ、シンボルデータベースは効率的なグラフ構造を使用しています。50万行までのコードベースで問題なくテスト済みです。

Q: 埋め込み生成にはいくらかかりますか？

一般的な10万行のコードベースの場合、初期インデックス作成で約1万個の埋め込みが生成され、text-embedding-3-small を使用すると約0.02ドルのコストがかかります。インクリメンタルな更新ははるかに安価です。

Q: 埋め込みなしで使用できますか？

はい、--no-embeddings を渡すとセマンティック検索を無効にできます。それでも、参照の検索や定義へのジャンプといった、シンボルを認識するすべてのツールは利用可能です。

Q: コードが外部サービスに送信されますか？

抽出されたシンボル名とその直近のコンテキストのみが、埋め込み生成のためにOpenAIに送信されます。完全にローカルで動作させるには、--no-embeddings でこれを無効にできます。

ライセンス

MIT