Code Graph Context

🚀 代碼圖上下文MCP服務器

代碼圖上下文MCP服務器是一個模型上下文協議（MCP）服務器，它能夠構建豐富的代碼圖，為大語言模型提供對TypeScript代碼庫的深度上下文理解。該服務器通過抽象語法樹（AST）分析來解析代碼庫，在Neo4j中構建全面的圖表示，並通過語義搜索和圖遍歷提供智能查詢功能。

配置驅動且可擴展：除了內置的NestJS支持外，你還可以定義自定義框架模式，以捕獲特定領域的模式。解析器可以完全配置，以識別你的架構模式、裝飾器和關係。

🚀 快速開始

前提條件

• 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"
      }
    }
  }
}

注意：環境變量可以針對任何Neo4j實例進行配置，包括本地、Docker、雲（Aura）或企業版。

驗證安裝

安裝完成後，驗證一切是否正常工作：

1. 檢查Neo4j是否正在運行：

# 打開Neo4j瀏覽器
open http://localhost:7474
# 登錄：neo4j / PASSWORD

2. 測試APOC插件：

CALL apoc.help("apoc")

應該返回一個APOC函數列表。

3. 測試MCP服務器連接：

claude mcp list

應該顯示：code-graph-context: ✓ 已連接

故障排除

“未找到APOC插件”

# 檢查Neo4j日誌
docker logs code-graph-neo4j

# 驗證APOC是否已加載
docker exec code-graph-neo4j cypher-shell -u neo4j -p PASSWORD "CALL apoc.help('apoc')"

# 如果需要，重啟Neo4j
docker restart code-graph-neo4j

“需要OPENAI_API_KEY環境變量”

• 從 https://platform.openai.com/api-keys 獲取你的API密鑰
• 添加到Claude Code MCP配置的env部分
• 使用 echo $OPENAI_API_KEY 進行驗證（如果使用shell環境變量）

“拒絕連接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

✨ 主要特性

• 豐富的代碼圖生成：解析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端點等）

工具使用指南和順序工作流

順序工具使用模式

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 // 推薦：清除之前的數據
});

// 響應: 成功確認，包含節點/邊計數
"✅ 成功: 解析了2,445個節點和4,892條邊。圖已導入Neo4j。"

性能注意事項：

• 大型項目（>1000個文件）可能需要幾分鐘。
• 嵌入生成會增加大量時間，但可以啟用語義搜索。
• 使用 clearExisting: true 避免重複數據。

4. test_neo4j_connection - 健康檢查

用途：驗證數據庫連接和APOC插件的可用性。

// 簡單的健康檢查
await mcp.call('test_neo4j_connection');

// 響應指示數據庫狀態
"Neo4j已連接: 已連接！於2025-07-25T19:48:42.676Z
APOC插件可用，有438個函數"

工作流示例

示例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(`在${response.uniqueFiles}個文件中找到了${response.totalConnections}個連接`);

// 2. 檢查起始節點
const startNode = response.nodes[response.startNodeId];
console.log(`從${startNode.name}開始，位於${startNode.filePath}`);

// 3. 探索第一個深度級別
const firstDepth = response.depths[0];
firstDepth.chains.forEach(chain => {
  console.log(`通過${chain.via}: ${chain.count}個連接 (${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)，以智能地確定要探索的關係優先級。通過在每個深度級別對每個節點進行評分，產生更相關的結果。

評分機制： 每個潛在路徑的評分由三個因素相乘得出：

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是持久的；保存感興趣的節點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	人工智能驅動的查詢生成 - 使用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	用於嵌入和大語言模型的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 由Anthropic提供
• Neo4j 提供圖數據庫技術
• ts-morph 用於TypeScript AST操作
• OpenAI 提供嵌入和自然語言處理
• NestJS 提供框架模式和約定

🛠️ 支持

• 若要報告錯誤或請求功能，請創建 Issue。
• 加入 MCP Discord 獲取社區支持。
• 有關MCP特定問題，請查看 MCP文檔。