Deep Code Reasoning MCP

🚀 深度代码推理MCP服务器

深度代码推理MCP服务器将Claude Code与谷歌的Gemini AI相结合，用于互补性代码分析。该服务器支持多模型工作流程，其中Claude Code负责紧密的终端集成和多文件重构，而Gemini则利用其庞大的上下文窗口（100万个标记）和代码执行能力进行分布式系统调试和长跟踪分析。

🚀 快速开始

前提条件

• Node.js 18 或更高版本
• 拥有Gemini API访问权限的谷歌云账户
• 从 谷歌AI工作室 获取的Gemini API密钥

关键依赖项

• @google/generative-ai：谷歌用于Gemini API集成的官方SDK
• @modelcontextprotocol/sdk：用于Claude集成的MCP协议实现
• zod：工具参数的运行时类型验证
• dotenv：环境变量管理

安装步骤

1. 克隆仓库：

git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git
cd deep-code-reasoning-mcp

2. 安装依赖项：

npm install

3. 设置Gemini API密钥：

cp .env.example .env
# 编辑.env文件并添加你的GEMINI_API_KEY

4. 构建项目：

npm run build

配置

环境变量

• GEMINI_API_KEY（必需）：你的谷歌Gemini API密钥

Claude桌面配置

在你的Claude桌面配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下内容：

{
  "mcpServers": {
    "deep-code-reasoning": {
      "command": "node",
      "args": ["/path/to/deep-code-reasoning-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

✨ 主要特性

• Gemini 2.5 Pro预览版：使用谷歌最新的Gemini 2.5 Pro预览版（05 - 06）模型，具有100万个标记的上下文窗口
• 对话式分析：全新功能！Claude和Gemini之间的AI对AI对话，用于迭代解决问题
• 执行流程跟踪：不仅理解函数调用，还能理解数据流和状态转换
• 跨系统影响分析：模拟更改如何在服务边界之间传播
• 性能建模：识别N + 1模式、内存泄漏和算法瓶颈
• 假设测试：通过基于证据的验证来测试关于代码行为的理论
• 长上下文支持：利用Gemini 2.5 Pro预览版的100万个标记上下文来分析大型代码库

💻 使用示例

基础用法

对话式分析示例

当Claude需要与Gemini进行深度迭代分析时：

// 1. 开始对话
const session = await start_conversation({
  claude_context: {
    attempted_approaches: ["Checked for N+1 queries", "Profiled database calls"],
    partial_findings: [{ type: "performance", description: "Multiple DB queries in loop" }],
    stuck_description: "Can't determine if queries are optimizable",
    code_scope: { files: ["src/services/UserService.ts"] }
  },
  analysis_type: "performance",
  initial_question: "Are these queries necessary or can they be batched?"
});

// 2. 继续跟进
const response = await continue_conversation({
  session_id: session.sessionId,
  message: "The queries fetch user preferences. Could we use a join instead?",
  include_code_snippets: true
});

// 3. 准备好后完成对话
const results = await finalize_conversation({
  session_id: session.sessionId,
  summary_format: "actionable"
});

高级用法

案例1：分布式跟踪分析

当故障签名跨越多个服务且包含GB级别的日志时：

// Claude Code：识别错误模式和可疑代码段
// 当需要关联10多个服务中的数千个跟踪跨度时，升级到Gemini
// Gemini：处理完整的跟踪时间线，确定确切的竞争窗口

案例2：性能回归排查

当性能下降但原因不明显时：

// Claude Code：快速分析性能，识别热点路径
// 当需要分析数周的性能指标和代码更改时，升级到Gemini
// Gemini：将部署时间线与性能指标关联起来，确定确切的提交

案例3：基于假设的调试

当你有理论但需要大量测试时：

// Claude Code：根据症状形成初始假设
// 当需要使用合成数据测试20多个场景时，升级到Gemini
// Gemini：使用代码执行API系统地验证每个假设

📚 详细文档

可用工具

注意：工具参数使用蛇形命名法，并使用Zod模式进行验证。实际实现提供的类型安全比这些简化示例中显示的更详细。完整的TypeScript类型定义可在src/models/types.ts中找到。

对话式分析工具

服务器现在包含AI对AI的对话式工具，使Claude和Gemini能够进行多轮对话以进行复杂分析：

start_conversation

启动Claude和Gemini之间的对话式分析会话。

{
  claude_context: {
    attempted_approaches: string[];      // Claude尝试过的方法
    partial_findings: any[];            // Claude发现的部分结果
    stuck_description: string;          // Claude遇到困难的地方
    code_scope: {
      files: string[];                  // 要分析的文件
      entry_points?: CodeLocation[];    // 起始点
      service_names?: string[];         // 涉及的服务
    }
  };
  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  initial_question?: string;            // 可选的开场问题
}

continue_conversation

使用Claude的响应或后续问题继续进行活跃的对话。

{
  session_id: string;                   // 活跃的会话ID
  message: string;                      // Claude发送给Gemini的消息
  include_code_snippets?: boolean;      // 是否包含代码片段
}

finalize_conversation

完成对话并生成结构化的分析结果。

{
  session_id: string;                   // 活跃的会话ID
  summary_format: 'detailed' | 'concise' | 'actionable';
}

get_conversation_status

检查正在进行的对话的状态和进度。

{
  session_id: string;                   // 要检查的会话ID
}

传统分析工具

escalate_analysis

将复杂分析从Claude Code转移到Gemini的主要工具。

{
  claude_context: {
    attempted_approaches: string[];      // Claude尝试过的方法
    partial_findings: any[];            // Claude发现的部分结果
    stuck_description: string;          // Claude遇到困难的地方
    code_scope: {
      files: string[];                  // 要分析的文件
      entry_points?: CodeLocation[];    // 起始点（文件、行号、函数名）
      service_names?: string[];         // 涉及的服务
    }
  };
  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  depth_level: 1-5;                     // 分析深度
  time_budget_seconds?: number;         // 时间限制（默认：60）
}

trace_execution_path

利用Gemini的语义理解进行深度执行分析。

{
  entry_point: {
    file: string;
    line: number;
    function_name?: string;
  };
  max_depth?: number;              // 默认：10
  include_data_flow?: boolean;     // 默认：true
}

cross_system_impact

分析跨服务边界的影响。

{
  change_scope: {
    files: string[];
    service_names?: string[];
  };
  impact_types?: ('breaking' | 'performance' | 'behavioral')[];
}

performance_bottleneck

进行超越简单性能分析的深度性能分析。

{
  code_path: {
    entry_point: {
      file: string;
      line: number;
      function_name?: string;
    };
    suspected_issues?: string[];
  };
  profile_depth?: 1-5;              // 默认：3
}

hypothesis_test

测试关于代码行为的特定理论。

{
  hypothesis: string;
  code_scope: {
    files: string[];
    entry_points?: CodeLocation[];    // 可选的 {文件, 行号, 函数名?} 数组
  };
  test_approach: string;
}

🔧 技术细节

工作原理

1. Claude Code进行初步分析：利用其在多文件重构和测试驱动循环方面的优势。
2. 必要时，Claude将任务升级到MCP服务器：特别是在以下情况下：
   • 分析超过Claude上下文的巨大日志/跟踪转储
   • 运行带有代码执行的迭代假设测试
   • 关联多个微服务中的故障
3. 服务器准备全面的上下文：包括代码、日志和跟踪信息。
4. Gemini利用其100万个标记的上下文进行分析：并显示可见的“思考”痕迹。
5. 结果返回给Claude Code：用于实施修复。

架构

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│  MCP Server      │────▶│  Gemini API    │
│  (Fast, Local, │     │  (Router &       │     │  (1M Context,   │
│   CLI-Native)  │◀────│   Orchestrator)  │◀────│   Code Exec)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Code + Logs +   │
                        │  Traces + Tests  │
                        └──────────────────┘

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。

开发

# 以开发模式运行
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint

# 类型检查
npm run typecheck

安全考虑

• API密钥：将你的Gemini API密钥安全地存储在环境变量中。
• 代码访问：服务器会读取本地文件，请确保设置了适当的文件权限。
• 数据隐私：代码会发送到谷歌的Gemini API，请查看他们的数据政策。

故障排除

"GEMINI_API_KEY未找到"

• 确保你已在.env文件或环境中设置了GEMINI_API_KEY。
• 检查.env文件是否位于项目根目录。

"文件未找到"错误

• 验证传递给工具的文件路径是否为绝对路径。
• 检查文件权限。

Gemini API错误

• 验证你的API密钥是否有效且具有适当的权限。
• 检查API配额和速率限制。
• 确保你的谷歌云项目已启用Gemini API。

验证错误

• 服务器使用Zod进行参数验证。
• 确保提供了所有必需的参数。
• 检查参数名称是否使用蛇形命名法（例如，claude_context，而不是claudeContext）。
• 查看错误消息以了解具体的验证要求。

多模型调试的最佳实践

使用此MCP服务器调试分布式系统时：

1. 首先捕获时间线 - 使用带有请求ID的OpenTelemetry / Jaeger跟踪。
2. 从Claude Code开始 - 让它进行初步调查和快速修复。
3. 有策略地升级到Gemini：当你需要：
   • 分析超过100MB的跟踪信息。
   • 关联10个以上服务的信息。
   • 运行带有代码执行的迭代假设测试。
4. 结合传统工具：
   • 使用go test -race、ThreadSanitizer进行竞争检测。
   • 使用rr或JFR进行确定性重放。
   • 使用TLA + 或Alloy进行形式验证。

贡献

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 为新功能添加测试。
5. 提交拉取请求。

作者

Jonathan Haas - GitHub个人资料

致谢

• 为与Anthropic的Claude Code集成而构建。
• 由谷歌的Gemini AI提供支持。
• 使用模型上下文协议（MCP）进行通信。

支持

如果遇到任何问题或有疑问：

• 在 GitHub问题 中打开一个问题。
• 查看上面的 故障排除部分。
• 查看 MCP文档。