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文档。