Code Graph Context

🚀 コードグラフコンテキストMCPサーバー

このサーバーは、大規模言語モデルにTypeScriptコードベースの深いコンテキスト理解を提供するために、豊富なコードグラフを構築するModel Context Protocol (MCP) サーバーです。このサーバーは、AST解析を使用してコードベースを解析し、Neo4jに包括的なグラフ表現を構築し、セマンティック検索とグラフトラバーサルを通じてインテリジェントなクエリ機能を提供します。

設定駆動型で拡張可能：含まれるNestJSサポートを超えたドメイン固有のパターンをキャプチャするために、カスタムフレームワークスキーマを定義できます。パーサーは、アーキテクチャパターン、デコレータ、および関係を認識するように完全に構成可能です。

✨ 主な機能

• 豊富なコードグラフ生成：TypeScriptプロジェクトを解析し、ASTレベルの精度で詳細なグラフ表現を作成します。
• セマンティック検索：OpenAI埋め込みを使用したベクトルベースのセマンティック検索で、関連するコードパターンと実装を見つけます。
• 自然言語クエリ：OpenAIアシスタントAPIを使用して、自然言語の質問をCypherクエリに変換します。
• フレームワーク対応かつカスタマイズ可能：組み込みのNestJSスキーマがあり、設定を介してカスタムフレームワークパターンを定義できます。
• 重み付きグラフトラバーサル：関係の重要性、クエリの関連性、および深さに基づいてパスをスコアリングするインテリジェントなトラバーサル。
• 高性能：高速な検索のためにベクトルインデックス付きの最適化されたNeo4jストレージ。
• MCP統合：Claude Codeや他のMCP互換ツールとのシームレスな統合。

🔧 アーキテクチャ

MCPサーバーはいくつかの主要なコンポーネントで構成されています。

コアコンポーネント

1. TypeScriptパーサー (src/core/parsers/typescript-parser-v2.ts)：ts-morphを使用してTypeScript ASTを解析し、コードエンティティを抽出します。
2. グラフストレージ (src/storage/neo4j/neo4j.service.ts)：コードグラフの保存とクエリのためのNeo4j統合。
3. 埋め込みサービス (src/core/embeddings/embeddings.service.ts)：セマンティック検索機能のためのOpenAI統合。
4. MCPサーバー (src/mcp/mcp.server.ts)：コード分析ツールを提供する主要なMCPサーバー。

グラフスキーマ

システムはデュアルスキーマアプローチを使用しています。

• コアスキーマ：ASTレベルのノード（クラス、メソッド、プロパティ、インポートなど）
• フレームワークスキーマ：セマンティック解釈（NestJSコントローラー、サービス、HTTPエンドポイントなど）

📦 インストール

前提条件

• Node.js >= 18
• Neo4j >= 5.0 （APOCプラグイン付き）
• OpenAI APIキー （埋め込みと自然言語処理用）
• Docker （Neo4jのセットアップに推奨）

インストール方法

最適なインストール方法を選択してください。

オプション1: 開発用インストール（ソースから）

プロジェクトへの貢献やコードのカスタマイズに最適です。

1. リポジトリをクローンします：

git clone https://github.com/drewdrewH/code-graph-context.git
cd code-graph-context

2. 依存関係をインストールします：

npm install

3. Dockerを使用してNeo4jをセットアップします：

docker-compose up -d

これにより、以下の設定でNeo4jが起動します。

• ウェブインターフェイス：http://localhost:7474
• Bolt接続：bolt://localhost:7687
• ユーザー名：neo4j、パスワード：PASSWORD

4. 環境変数を設定します：

cp .env.example .env
# .envを編集して設定を入力します

5. プロジェクトをビルドします：

npm run build

6. Claude Codeに追加します：

claude mcp add code-graph-context node /absolute/path/to/code-graph-context/dist/mcp/mcp.server.js

オプション2: NPMインストール（グローバルパッケージ）

簡単なセットアップと自動更新に最適です。

1. パッケージをグローバルにインストールします：

npm install -g code-graph-context

2. Neo4jをセットアップします（いずれかを選択）。

オプションA: Docker（推奨）

docker run -d \
  --name code-graph-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/PASSWORD \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5.15

オプションB: Neo4j Desktop

• neo4j.com/download からダウンロードします。
• APOCプラグインをインストールします。
• データベースを起動します。

オプションC: Neo4j Aura（クラウド）

• neo4j.com/cloud/aura で無料アカウントを作成します。
• 接続URIと資格情報をメモします。

3. Claude Codeに追加します：

claude mcp add code-graph-context code-graph-context

次に、MCP設定ファイル (~/.config/claude/config.json) で設定します。

{
  "mcpServers": {
    "code-graph-context": {
      "command": "code-graph-context",
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "PASSWORD"
      }
    }
  }
}

注意：環境変数は、ローカル、Docker、クラウド（Aura）、またはエンタープライズなど、任意のNeo4jインスタンスに対して構成できます。

インストールの確認

インストール後、すべてが正常に動作していることを確認します。

1. Neo4jが実行中であることを確認します：

# Neo4jブラウザを開きます
open http://localhost:7474
# ログイン：neo4j / PASSWORD

2. APOCプラグインをテストします：

CALL apoc.help("apoc")

APOC関数のリストが返されるはずです。 3. MCPサーバーの接続をテストします：

claude mcp list

code-graph-context: ✓ Connected が表示されるはずです。

トラブルシューティング

"APOCプラグインが見つかりません"

# Neo4jのログを確認します
docker logs code-graph-neo4j

# APOCがロードされていることを確認します
docker exec code-graph-neo4j cypher-shell -u neo4j -p PASSWORD "CALL apoc.help('apoc')"

# 必要に応じて再起動します
docker restart code-graph-neo4j

"OPENAI_API_KEY環境変数が必要です"

• https://platform.openai.com/api-keys からAPIキーを取得します。
• Claude Code MCP設定の env セクションに追加します。
• （シェル環境を使用している場合）echo $OPENAI_API_KEY で確認します。

"Connection refused bolt://localhost:7687"

# Neo4jが実行中であることを確認します
docker ps | grep neo4j

# ポートが使用中でないことを確認します
lsof -i :7687

# Neo4jが停止している場合は起動します
docker start code-graph-neo4j

# Neo4jのログを確認します
docker logs code-graph-neo4j

"Neo4jメモリエラー"

# docker-compose.ymlまたはdocker runでメモリを増やします
-e NEO4J_server_memory_heap_max__size=8G
-e NEO4J_dbms_memory_transaction_total_max=8G

docker restart code-graph-neo4j

"MCPサーバーが応答しません"

# Claude Codeのログを確認します
cat ~/Library/Logs/Claude/mcp*.log

# サーバーを直接テストします
node /path/to/code-graph-context/dist/mcp/mcp.server.js

# 必要に応じて再ビルドします
npm run build

💻 使用例

逐次的なツール使用パターン

MCPツールは、強力なワークフローで連携するように設計されています。以下は最も効果的なパターンです。

パターン1: 探索 → 焦点化 → 深掘り

graph LR
    A[search_codebase] --> B[traverse_from_node] --> C[traverse_from_node with skip]
    A --> D[traverse_from_node] --> E[traverse_from_node deeper]

パターン2: 広範な検索 → ターゲット分析

1. 広範に開始する：search_codebase を使用して関連する開始点を見つけます。
2. 焦点を絞る：traverse_from_node を使用して特定の関係を探索します。
3. ページネーションする：skip パラメータを使用してグラフの異なるセクションを探索します。

ツールの詳細

1. search_codebase - 開始点

目的：ベクトル埋め込みを使用したセマンティック検索で、最も関連するコードノードを見つけます。

レスポンス構造：JSON:APIパターンを使用して正規化されたJSONを返し、重複を排除します。

• nodes：一意のノードのマップ（一度だけ保存され、IDで参照されます）
• depths：関係チェーンを持つ深さレベルの配列
• ソースコード：デフォルトで含まれます（1000文字に切り捨てられます：最初の500 + 最後の500）
• 統計情報：総接続数、一意のファイル数、最大深さ

実際のレスポンス例：

// クエリ: "JWT token validation"
// 返される結果:
{
  "totalConnections": 22,
  "uniqueFiles": 2,
  "maxDepth": 3,
  "startNodeId": "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b",
  "nodes": {
    "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b": {
      "id": "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b",
      "type": "MethodDeclaration",
      "filePath": "/packages/jwt-validation/src/lib/jwt.strategy.ts",
      "name": "validate",
      "sourceCode": "validate(payload: EmJwtPayload): EmJwtPayload {\n  ...\n\n... [truncated] ...\n\n  return payload;\n}",
      "hasMore": true,
      "truncated": 1250
    },
    "ClassDeclaration:abc-123": {
      "id": "ClassDeclaration:abc-123",
      "type": "Service",
      "filePath": "/packages/jwt-validation/src/lib/jwt.strategy.ts",
      "name": "JwtStrategy"
    }
  },
  "depths": [
    {
      "depth": 1,
      "count": 8,
      "chains": [
        {
          "via": "HAS_MEMBER",
          "direction": "INCOMING",
          "count": 1,
          "nodeIds": ["ClassDeclaration:abc-123"]
        },
        {
          "via": "HAS_PARAMETER",
          "direction": "OUTGOING",
          "count": 2,
          "nodeIds": ["Parameter:xyz-456", "Parameter:def-789"]
        }
      ]
    },
    {
      "depth": 2,
      "count": 14,
      "chains": [
        {
          "via": "HAS_MEMBER → INJECTS",
          "direction": "INCOMING",
          "count": 3,
          "nodeIds": ["Service:auth-service", "Service:user-service", "Repository:user-repo"],
          "hasMore": 2
        }
      ]
    }
  ]
}

主要な機能：

• JSON:API正規化：ノードは nodes マップに一度だけ保存され、IDで参照されて重複が排除されます。
• ソースコードの切り捨て：スニペットごとに最大1000文字（最初の500 + 最後の500文字）。
• 関係チェーン："HAS_MEMBER → INJECTS → USES_REPOSITORY" のような完全なパスを示します。
• 方向インジケーター：OUTGOING（これが呼び出すもの）、INCOMING（これを呼び出すもの）

プロのヒント：

• 特定のドメイン用語を使用します："JWT token validation" 対 "authentication"
• 初期探索では limit=1-3 から始めて、トークン制限を回避します。
• nodes マップのノードIDを探して、traverse_from_node で使用します。
• truncated フィールドを確認して、ソースコードから隠されたバイト数を確認します。

2. traverse_from_node - 深い関係の探索

目的：特定のノードからのすべての接続を深さとページネーションを精密に制御して探索します。

レスポンス構造：search_codebase と同じJSON:API形式です。

• 焦点化されたトラバーサル：指定したノードから開始します。
• 深さ制御：構成可能な最大深さ（1-10、デフォルトは3）
• ページネーション：大規模なグラフをチャンクで探索するための skip パラメータ
• ソースコードはデフォルトで含まれます：includeCode: false を設定して構造のみのビューにします。

実際のレスポンス例：

// サービスクラスから開始
// maxDepth: 2, skip: 0, includeCode: true
{
  "totalConnections": 15,
  "uniqueFiles": 4,
  "maxDepth": 2,
  "startNodeId": "ClassDeclaration:credit-check-service",
  "nodes": {
    "ClassDeclaration:credit-check-service": {
      "id": "ClassDeclaration:credit-check-service",
      "type": "Service",
      "filePath": "/src/modules/credit/credit-check.service.ts",
      "name": "CreditCheckService",
      "sourceCode": "@Injectable([CreditCheckRepository, OscilarClient])\nexport class CreditCheckService {\n  ...\n\n... [truncated] ...\n\n}",
      "truncated": 3200
    },
    "Repository:credit-check-repo": {
      "id": "Repository:credit-check-repo",
      "type": "Repository",
      "filePath": "/src/modules/credit/credit-check.repository.ts",
      "name": "CreditCheckRepository"
    }
  },
  "depths": [
    {
      "depth": 1,
      "count": 5,
      "chains": [
        {
          "via": "INJECTS",
          "direction": "OUTGOING",
          "count": 2,
          "nodeIds": ["Repository:credit-check-repo", "VendorClient:oscilar"]
        },
        {
          "via": "HAS_MEMBER",
          "direction": "OUTGOING",
          "count": 3,
          "nodeIds": ["Method:processCheck", "Method:getResult", "Method:rerun"]
        }
      ]
    },
    {
      "depth": 2,
      "count": 10,
      "chains": [
        {
          "via": "INJECTS → USES_DAL",
          "direction": "OUTGOING",
          "count": 1,
          "nodeIds": ["DAL:application-dal"]
        }
      ]
    }
  ]
}

パラメータ：

• nodeId （必須）：search_codebase の結果からのノードID
• maxDepth （デフォルト: 3）：トラバーサルの深さ（1-10）
• skip （デフォルト: 0）：ページネーションのオフセット
• includeCode （デフォルト: true）：ソースコードスニペットを含める
• summaryOnly （デフォルト: false）：ファイルパスと統計情報のみ
• direction （デフォルト: BOTH）：OUTGOING/INCOMING/BOTH でフィルタリング
• relationshipTypes （オプション）：["INJECTS", "USES_REPOSITORY"] のような特定の関係でフィルタリング

ページネーション戦略：

// 注: 最近のコミットでページネーションは削除されました - すべての結果が返されます
// 代わりに深さと関係のフィルタリングを使用します
traverse_from_node({
  nodeId,
  maxDepth: 2,
  relationshipTypes: ["INJECTS"]  // 依存性注入のみに焦点を当てます
})

3. parse_typescript_project - グラフ生成

目的：TypeScript/NestJSプロジェクトを解析し、初期のグラフデータベースを構築します。

// 完全なプロジェクトの解析
await mcp.call('parse_typescript_project', {
  projectPath: '/path/to/your/nestjs/project',
  tsconfigPath: '/path/to/your/nestjs/project/tsconfig.json',
  clearExisting: true // 推奨: 以前のデータをクリアします
});

// レスポンス: ノード/エッジ数を含む成功確認
"✅ SUCCESS: Parsed 2,445 nodes and 4,892 edges. Graph imported to Neo4j."

パフォーマンスに関する注意事項：

• 大規模なプロジェクト（1000ファイルを超える）は数分かかる場合があります。
• 埋め込み生成は時間がかかりますが、セマンティック検索を有効にします。
• clearExisting: true を使用して重複データを回避します。

4. test_neo4j_connection - ヘルスチェック

目的：データベースの接続とAPOCプラグインの可用性を確認します。

// 簡単なヘルスチェック
await mcp.call('test_neo4j_connection');

// レスポンスはデータベースの状態を示します
"Neo4j connected: Connected! at 2025-07-25T19:48:42.676Z
APOC plugin available with 438 functions"

ワークフローの例

例1: 認証フローの理解

// ステップ1: 認証関連のコードを検索
const searchResult = await mcp.call('search_codebase', {
  query: 'JWT token validation authentication',
  limit: 2
});

// ステップ2: 最も関連する結果からノードIDを抽出
const nodeId = "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b";

// ステップ3: 直接の関係を探索
const immediateConnections = await mcp.call('traverse_from_node', {
  nodeId,
  maxDepth: 2,
  skip: 0
});

// ステップ4: 完全な認証チェーンを理解するために深く掘り下げる
const deepConnections = await mcp.call('traverse_from_node', {
  nodeId,
  maxDepth: 4,
  skip: 0
});

// ステップ5: 異なる接続ブランチを探索
const alternateConnections = await mcp.call('traverse_from_node', {
  nodeId,
  maxDepth: 3,
  skip: 10  // 最初の10をスキップして異なる接続を表示
});

例2: APIエンドポイントの分析

// ステップ1: コントローラーエンドポイントを検索
const controllerSearch = await mcp.call('search_codebase', {
  query: 'HTTP controller endpoints routes POST GET',
  limit: 1
});

// ステップ2: 結果からコントローラーノードIDを見つける
const controllerNodeId = "ClassDeclaration:controller-uuid";

// ステップ3: このコントローラーが公開するエンドポイントを探索
const endpoints = await mcp.call('traverse_from_node', {
  nodeId: controllerNodeId,
  maxDepth: 2,
  skip: 0
});

// ステップ4: 見つかった各エンドポイントについて、その依存関係を探索
const endpointNodeId = "MethodDeclaration:endpoint-uuid";
const endpointDeps = await mcp.call('traverse_from_node', {
  nodeId: endpointNodeId,
  maxDepth: 3,
  skip: 0
});

例3: サービス依存関係のマッピング

// ステップ1: 特定のサービスを検索
const serviceSearch = await mcp.call('search_codebase', {
  query: 'UserService injectable dependency injection',
  limit: 1
});

// ステップ2: すべての依存関係（注入するもの）をマッピング
const serviceDeps = await mcp.call('traverse_from_node', {
  nodeId: "ClassDeclaration:user-service-uuid",
  maxDepth: 2,
  skip: 0
});

// ステップ3: このサービスに依存するもの（逆の関係）を見つける
const serviceDependents = await mcp.call('search_codebase', {
  query: 'UserService injection constructor parameter',
  limit: 5
});

高度な使用方法のヒント

レスポンス形式の理解（JSON:API正規化）

重要な洞察：すべてのレスポンスはJSON:APIパターンを使用して、各ノードを一度だけ保存し、IDで参照することで重複を排除します。

レスポンスの読み方：

1. nodes マップから始めます：すべての一意のノードはここに一度だけ保存されます。
2. depths 配列を見ます：各深さレベルでノードがどのように接続されているかを示します。
3. nodeIds 参照をたどります：IDを使用して nodes マップで完全なノードデータを検索します。
4. truncated フィールドを確認します：ソースコードから隠されたバイト数を示します。

読み方の例：

const response = await search_codebase({ query: "authentication" });

// 1. 概要統計情報を取得
console.log(`Found ${response.totalConnections} connections across ${response.uniqueFiles} files`);

// 2. 開始ノードを調べる
const startNode = response.nodes[response.startNodeId];
console.log(`Starting from: ${startNode.name} in ${startNode.filePath}`);

// 3. 最初の深さレベルを探索
const firstDepth = response.depths[0];
firstDepth.chains.forEach(chain => {
  console.log(`Via ${chain.via}: ${chain.count} connections (${chain.direction})`);

  // 4. 実際のノード詳細を検索
  chain.nodeIds.forEach(nodeId => {
    const node = response.nodes[nodeId];
    console.log(`  - ${node.name} (${node.type})`);
  });
});

大規模なレスポンスの管理

• 小さく始める：初期検索では limit: 1-3 を使用します。
• 関係のフィルタリング：relationshipTypes を使用して特定の接続に焦点を当てます。
• 構造のみのビュー：includeCode: false を設定してソースコードスニペットを除外します。
• 要約モード：summaryOnly: true を使用してファイルパスと統計情報のみを取得します。

効率的なグラフ探索

• 幅優先：概要を把握するために低い maxDepth （1-2）から始めます。
• 深さ優先：詳細な分析のために maxDepth （3-5）を増やします。
• 方向フィルタリング：direction: "OUTGOING" または "INCOMING" を使用して探索を絞り込みます。
• 必要に応じてソースコードを取得：ソースコードはデフォルトで含まれますが、1000文字に切り捨てられます。

重み付きトラバーサル

search_codebase ツールはデフォルトで 重み付きトラバーサル を使用して（useWeightedTraversal: true）、探索する関係をインテリジェントに優先順位付けします。これにより、各深さレベルでノードをスコアリングすることで、より関連性の高い結果が得られます。

スコアリングの仕組み： 各潜在的なパスは、3つの要素を掛け合わせた値でスコアリングされます。

1. エッジの重み（0.0-1.0）：この関係タイプの重要性はどれくらいですか？
   • 重要（0.9-0.95）：INJECTS, EXPOSES, ROUTES_TO - コアのアーキテクチャ関係
   • 高（0.8-0.88）：EXTENDS, IMPLEMENTS, USES_REPOSITORY - 重要なセマンティックリンク
   • 中（0.5-0.6）：IMPORTS, EXPORTS, HAS_MEMBER - 構造的な関係
   • 低（0.3-0.4）：DECORATED_WITH, HAS_PARAMETER - メタデータ関係
2. ノードの類似度：ノードの埋め込みとクエリの埋め込みのコサイン類似度。検索に意味的に関連するノードは上位にランク付けされます。
3. 深さペナルティ：指数関数的な減衰（デフォルトはレベルごとに0.85）。近いノードが優先されます。
   • 深さ1: 1.0（ペナルティなし）
   • 深さ2: 0.85
   • 深さ3: 0.72

無効にする場合：

// 網羅的な探索のために標準のトラバーサルを使用します
search_codebase({
  query: "...",
  useWeightedTraversal: false
})

パフォーマンスの最適化

• トークンの効率性：JSON:API正規化により、レスポンス内の重複ノードが排除されます。
• コードの切り捨て：ソースコードは1000文字（最初の500 + 最後の500）に制限され、トークンオーバーフローを防ぎます。
• メモリ：大規模なトラバーサルはNeo4jのメモリ制限に達する場合があります（必要に応じてヒープサイズを増やします）。
• キャッシング：ノードIDは永続的です。興味深いものを保存して後で探索します。

📚 ドキュメント

利用可能なMCPツール

コアツール

ツール	説明	パラメータ	使用例
hello	挨拶をするテストツール	なし	MCP接続を確認
test_neo4j_connection	Neo4j接続とAPOCプラグインをテスト	なし	操作前のヘルスチェック

解析ツール

ツール	説明	パラメータ	使用例
parse_typescript_project	TypeScript/NestJSプロジェクトをグラフに解析	projectPath, tsconfigPath, clearExisting?	初期設定: グラフデータベースを構築

検索と探索ツール

ツール	説明	パラメータ	最適なシナリオ
search_codebase	ベクトルベースのセマンティック検索 - OpenAI埋め込みを使用して最も関連するコードを見つけます	query, limit?, useWeightedTraversal? （デフォルト: true）	コード探索の開始点。重み付きスコアリングによるインテリジェントなトラバーサルを使用
traverse_from_node	焦点化されたグラフトラバーサル - 既知のノードから特定の関係を探索します	nodeId （文字列）, maxDepth? （1-10、デフォルト: 3）, skip? （デフォルト: 0）	特定のコード関係の深掘り。大規模なグラフのページネーション
natural_language_to_cypher	AIによるクエリ生成 - GPT-4を使用して自然言語をCypherクエリに変換します	query （文字列）	高度なクエリ - 現在はOpenAIアシスタントの設定が必要

ツール選択ガイド

ここから始める：search_codebase

• 特定のノードIDがわからない場合に使用します。
• 新しいコードベースを探索するのに最適です。
• コードスニペットを含む豊富なコンテキストを返します。

深く掘り下げる：traverse_from_node

• 検索結果から特定のノードIDがある場合に使用します。
• 関係と依存関係を理解するのに最適です。
• skip パラメータを使用して大規模な結果セットをページネーションします。

高度な使用：natural_language_to_cypher

• 追加のOpenAIアシスタント構成が必要です。
• 単純な検索/トラバーサルを超えた複雑なクエリに最適です。
• 現在開発中です - 設定が必要な場合があります。

Claude Code統合のヒント

claude.mdでのツール使用のガイド

リポジトリのルートに claude.md ファイルを追加することで、Claude CodeがこれらのMCPツールを効果的に使用するタイミングを理解するのに役立てることができます。以下はいくつかの有用なパターンです。

トリガーワードヒント

## コード検索ツール

**`search_codebase` を使用する場合**：
- "Where is...", "Find...", "Show me [specific thing]"
- 例: "Where is the authentication middleware?"

**`natural_language_to_cypher` を使用する場合**：
- "List all...", "How many...", "Count..."
- 例: "List all API controllers"

**`traverse_from_node` を使用する場合**：
- 初期検索後の深い依存関係分析
- "What depends on X?", "Trace the flow..."

重み付きトラバーサルヒント

**`useWeightedTraversal: true` を使用する場合**：
- 多くの依存関係を持つサービス/コントローラークラス
- 深さ > 3 または制限 > 10 のクエリ
- クリーンで関連性の高い結果

**推奨設定**：
- デフォルト: `limit: 15, maxDepth: 5, snippetLength: 900`
- 単純な検索: `limit: 5, maxDepth: 2`

フレームワーク固有のパターン

カスタムノードタイプと関係を文書化することで、Claudeが検索対象を理解できるようにします。

**カスタムノードタイプ**：
- `PaymentProcessor` - 支払い統合
- `EmailTemplate` - メールテンプレート

**カスタム関係**：
- `PROCESSES_PAYMENT` - サービス → 支払いプロセッサー
- `SENDS_EMAIL` - サービス → メールテンプレート

一般的なクエリ例

**認証の検索**：
search_codebase({ query: "JWT authentication middleware" })

**依存関係の追跡**：
traverse_from_node({ nodeId: "...", direction: "OUTGOING", maxDepth: 5 })

**影響分析**：
traverse_from_node({ nodeId: "...", direction: "INCOMING", maxDepth: 4 })

フレームワークサポート

NestJSフレームワークスキーマ

サーバーはNestJSパターンを深く理解しています。

ノードタイプ

• コントローラー：ルート分析を伴うHTTPエンドポイントハンドラー
• サービス：依存性注入マッピングを伴うビジネスロジックプロバイダー
• モジュール：インポート/エクスポート関係を持つアプリケーション構造
• ガード：認証と承認コンポーネント
• パイプ：リクエストの検証と変換
• インターセプター：リクエスト/レスポンス処理ミドルウェア
• DTO：検証デコレータを持つデータ転送オブジェクト
• エンティティ：関係マッピングを持つデータベースモデル

関係タイプ

• モジュールシステム：MODULE_IMPORTS, MODULE_PROVIDES, MODULE_EXPORTS
• 依存性注入：INJECTS, PROVIDED_BY
• HTTP API：EXPOSES, ACCEPTS, RESPONDS_WITH
• セキュリティ：GUARDED_BY, TRANSFORMED_BY, INTERCEPTED_BY

グラフ構造の例

┌─────────────────┐    EXPOSES     ┌──────────────────┐
│   UserController│──────────────→│  POST /users     │
│   @Controller   │                │  @Post()         │
└─────────────────┘                └──────────────────┘
         │                                   │
      INJECTS                           ACCEPTS
         ↓                                   ↓
┌─────────────────┐                ┌──────────────────┐
│   UserService   │                │   CreateUserDto  │
│   @Injectable   │                │   @IsString()    │
└─────────────────┘                └──────────────────┘
         │
      MANAGES
         ↓
┌─────────────────┐
│   User Entity   │
│   @Entity()     │
└─────────────────┘

設定

環境変数

変数	説明	デフォルト
OPENAI_API_KEY	埋め込みとLLMのためのOpenAI APIキー	必須
OPENAI_ASSISTANT_ID	既存のOpenAIアシスタントを再利用	オプション
NEO4J_URI	Neo4jデータベースのURI	bolt://localhost:7687
NEO4J_USER	Neo4jのユーザー名	neo4j
NEO4J_PASSWORD	Neo4jのパスワード	PASSWORD

解析オプション

解析動作をカスタマイズします。

const parseOptions = {
  includePatterns: ['**/*.ts', '**/*.tsx'],
  excludePatterns: [
    'node_modules/',
    'dist/',
    'coverage/',
    '.d.ts',
    '.spec.ts',
    '.test.ts'
  ],
  maxFiles: 1000,
  frameworkSchemas: [NESTJS_FRAMEWORK_SCHEMA]
};

制限事項

現在の制限事項

1. 言語サポート：現在はTypeScript/NestJSのみをサポートしています。
2. フレームワークサポート：主にNestJSパターンに焦点を当てています。
3. ファイルサイズ：大きなファイル（10MBを超える）は解析パフォーマンスに問題を引き起こす可能性があります。
4. メモリ使用量：非常に大規模なプロジェクトのグラフ生成はメモリを大量に消費します。
5. ベクトル検索：セマンティック検索機能にはOpenAI APIが必要です。
6. リアルタイム更新：ファイル監視はなく、コードの変更には手動での再解析が必要です。
7. レスポンスサイズ：大規模なグラフトラバーサルはトークン制限（最大25,000トークン）を超える可能性があります。
8. Neo4jメモリ：大規模なグラフではデータベースのメモリ制限によりクエリが失敗する可能性があります。

パフォーマンスに関する考慮事項

• 大規模なプロジェクト：10,000ファイルを超えるプロジェクトはメモリ割り当てを増やす必要がある場合があります。
• グラフトラバーサル：深いトラバーサル（5レベルを超える）は高度に接続されたグラフでは遅くなる場合があります。
• 埋め込み生成：埋め込みを含む初期解析は大規模なコードベースでは数分かかる場合があります。
• Neo4jメモリ：大規模なグラフではNeo4jに少なくとも4GBのRAM割り当てを推奨します。

既知の問題

1. 複雑な型推論：高度なTypeScript型体操は完全にキャプチャされない場合があります。
2. 動的インポート：静的分析ではランタイムモジュールのロードが追跡されません。
3. デコレータ引数：複雑なデコレータ引数パターンは完全に解析されない場合があります。
4. モノレポサポート：複雑なモノレポ構造のサポートは限られています。

トラブルシューティング

一般的な問題

Neo4j接続が失敗した場合

# Neo4jが実行中であることを確認します
docker ps | grep neo4j

# Neo4jのログを確認します
docker logs codebase-neo4j

# APOCプラグインを確認します
curl -u neo4j:PASSWORD http://localhost:7474/db/neo4j/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"CALL apoc.help(\"apoc\") YIELD name RETURN count(name) as count"}]}'

Neo4jのメモリ問題

"allocation of an extra X MiB would use more than the limit" のようなエラーが発生した場合：

# docker-compose.ymlでNeo4jのメモリ制限を増やします
NEO4J_server_memory_heap_max__size=8G
NEO4J_server_memory_pagecache_size=4G
NEO4J_dbms_memory_transaction_total_max=8G

# Neo4jを再起動します
docker-compose restart neo4j

トークン制限を超えた場合

レスポンスが25,000トークンを超える場合：

// limitパラメータを減らします
search_codebase({ query: "...", limit: 1 })

// skipを使用したページネーションを使用します
traverse_from_node({ nodeId: "...", maxDepth: 2, skip: 0 })
traverse_from_node({ nodeId: "...", maxDepth: 2, skip: 20 })

OpenAI APIの問題

# APIキーをテストします
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 埋め込みモデルの可用性を確認します
curl https://api.openai.com/v1/models/text-embedding-3-large \
  -H "Authorization: Bearer $OPENAI_API_KEY"

解析失敗

# TypeScriptの設定を確認します
npx tsc --noEmit --project /path/to/tsconfig.json

# ファイルのパーミッションを確認します
ls -la /path/to/project

# 解析中のメモリ使用量を確認します
node --max-old-space-size=8192 dist/mcp/mcp.server.js

デバッグモード

詳細なログを有効にします。

export DEBUG=mcp:*
export NODE_ENV=development

貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します。

開発環境のセットアップ

# 依存関係をインストールします
npm install

# 開発モードで実行します
npm run dev

# テストを実行します
npm test

# コードをリントします
npm run lint

# コードをフォーマットします
npm run format

📄 ライセンス

このプロジェクトは独自ソフトウェアです。すべての権利は予約されています - 詳細については LICENSE ファイルを参照してください。

謝辞

• Model Context Protocol by Anthropic
• Neo4j のグラフデータベース技術
• ts-morph のTypeScript AST操作
• OpenAI の埋め込みと自然言語処理
• NestJS のフレームワークパターンと規約

サポート

• バグ報告や機能リクエストについては Issue を作成してください。
• コミュニティサポートについては MCP Discord に参加してください。
• MCPに関する質問については MCP Documentation を確認してください。