evalops/deep-code-reasoning-mcp

# 深度代码推理 MCP 服务器 [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.com) [](https://nodejs.org) 这是一个将 Claude Code 与 Google 的 Gemini AI 配对以进行互补代码分析的 MCP 服务器。该服务器启用了一种多模型工作流，其中 Claude Code 负责处理紧密的终端集成和多文件重构，而 Gemini 则利用其庞大的上下文窗口（1M tokens）和代码执行能力来进行分布式系统调试和长链路分析。 ## 核心价值 Claude 和 Gemini 都能处理深层的语义推理和分布式系统 Bug。该服务器实现了一种智能路由策略，其中： - **Claude Code** 擅长本地上下文操作、增量补丁和 CLI 原生工作流 - **Gemini 2.5 Pro** 在大范围上下文扫描、合成测试执行以及分析跨越日志 + 链路追踪 + 代码的故障时大放异彩 这种“升级”模型将 LLM 视为异构微服务——根据每个子任务的能力路由到最适合的模型上。 ## 功能特性 - **Gemini 2.5 Pro Preview**：使用 Google 最新的 Gemini 2.5 Pro Preview (05-06) 模型，具有 1M token 上下文窗口 - **对话式分析**：全新功能！Claude 与 Gemini 之间的 AI 对 AI 对话，用于迭代解决问题 - **执行流追踪**：理解数据流和状态转换，而不仅仅是函数调用 - **跨系统影响分析**：模拟变更如何跨服务边界传播 - **性能建模**：识别 N+1 模式、内存泄漏和算法瓶颈 - **假设检验**：通过基于证据的验证来测试关于代码行为的理论 - **长上下文支持**：利用 Gemini 2.5 Pro Preview 的 1M token 上下文来分析大型代码库 ## 前置条件 - Node.js 18 或更高版本 - 具有 Gemini API 访问权限的 Google Cloud 账户 - 来自 [Google AI Studio](https://makersuite.google.com/app/apikey) 的 Gemini API 密钥 ## 主要依赖 - **@google/generative-ai**：用于集成 Gemini API 的 Google 官方 SDK - **@modelcontextprotocol/sdk**：用于集成 Claude 的 MCP 协议实现 - **zod**：用于工具参数的运行时类型验证 - **dotenv**：环境变量管理 ## 安装说明 ### Cursor 快速安装 [](https://cursor.com/install-mcp?name=deep-code-reasoning&config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiL3BhdGgvdG8vZGVlcC1jb2RlLXJlYXNvbmluZy1tY3AvZGlzdC9pbmRleC5qcyJdLCJlbnYiOnsiR0VNSU5JX0FQSV9LRVkiOiJ5b3VyLWdlbWluaS1hcGkta2V5In19) *注意：安装完成后，您需要将文件路径更新为您实际的安装目录，并设置您的 `GEMINI_API_KEY`。* ### 手动安装 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`（必填）：您的 Google Gemini API 密钥 ### Claude Desktop 配置 将以下内容添加到您的 Claude Desktop 配置中（`~/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" } } } } ``` ## 工作原理 1. **Claude Code 执行初步分析**，发挥其在多文件重构和测试驱动循环方面的优势 2. **在条件允许时，Claude 会将任务升级到此 MCP 服务器** —— 特别适用于： - 分析超出 Claude 上下文限制的超大日志/链路追踪转储 - 通过代码执行运行迭代假设测试 - 关联多个微服务之间的故障 3. **服务器准备全面的上下文**，包括代码、日志和链路追踪 4. **Gemini 利用其 1M token 上下文**和可见的“思考”链路进行分析 5. **结果返回给 Claude Code** 以便实施修复 ## 可用工具 **注意**：工具参数使用 snake_case 命名约定，并使用 Zod schema 进行验证。实际的实现提供了比这些简化示例中所示的更详细的类型安全。完整的 TypeScript 类型定义可在 `src/models/types.ts` 中找到。 ### 对话式分析工具 该服务器现在包含 AI 到 AI 的对话式工具，使 Claude 和 Gemini 能够进行多轮对话以进行复杂分析： #### start_conversation 启动 Claude 和 Gemini 之间的对话式分析会话。 ``` { claude_context: { attempted_approaches: string[]; // What Claude tried partial_findings: any[]; // What Claude found stuck_description: string; // Where Claude got stuck code_scope: { files: string[]; // Files to analyze entry_points?: CodeLocation[]; // Starting points service_names?: string[]; // Services involved } }; analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test'; initial_question?: string; // Optional opening question } ``` #### continue_conversation 通过 Claude 的回复或后续问题继续进行中的对话。 ``` { session_id: string; // Active session ID message: string; // Claude's message to Gemini include_code_snippets?: boolean; // Enrich with code context } ``` #### finalize_conversation 完成对话并生成结构化的分析结果。 ``` { session_id: string; // Active session ID summary_format: 'detailed' | 'concise' | 'actionable'; } ``` #### get_conversation_status 检查正在进行的对话的状态和进度。 ``` { session_id: string; // Session ID to check } ``` ### 传统分析工具 #### escalate_analysis 用于将复杂分析任务从 Claude Code 移交给 Gemini 的主要工具。 ``` { claude_context: { attempted_approaches: string[]; // What Claude tried partial_findings: any[]; // What Claude found stuck_description: string; // Where Claude got stuck code_scope: { files: string[]; // Files to analyze entry_points?: CodeLocation[]; // Starting points (file, line, function_name) service_names?: string[]; // Services involved } }; analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test'; depth_level: 1-5; // Analysis depth time_budget_seconds?: number; // Time limit (default: 60) } ``` ### trace_execution_path 利用 Gemini 的语义理解进行深度执行分析。 ``` { entry_point: { file: string; line: number; function_name?: string; }; max_depth?: number; // Default: 10 include_data_flow?: boolean; // Default: 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; // Default: 3 } ``` ### hypothesis_test 测试关于代码行为的特定理论。 ``` { hypothesis: string; code_scope: { files: string[]; entry_points?: CodeLocation[]; // Optional array of {file, line, function_name?} }; test_approach: string; } ``` ## 示例用例 ### 对话式分析示例 当 Claude 需要与 Gemini 进行深度迭代分析时： ``` // 1. Start conversation 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. Continue with follow-ups 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. Finalize when ready const results = await finalize_conversation({ session_id: session.sessionId, summary_format: "actionable" }); ``` ### 案例 1：分布式链路追踪分析 当故障特征跨越带有 GB 级别日志的多个服务时： ``` // Claude Code: Identifies the error pattern and suspicious code sections // Escalate to Gemini when: Need to correlate 1000s of trace spans across 10+ services // Gemini: Processes the full trace timeline, identifies the exact race window ``` ### 案例 2：性能回退排查 当性能下降但原因不明显时： ``` // Claude Code: Quick profiling, identifies hot paths // Escalate to Gemini when: Need to analyze weeks of performance metrics + code changes // Gemini: Correlates deployment timeline with perf metrics, pinpoints the exact commit ``` ### 案例 3：假设驱动调试 当您有理论但需要广泛测试时： ``` // Claude Code: Forms initial hypotheses based on symptoms // Escalate to Gemini when: Need to test 20+ scenarios with synthetic data // Gemini: Uses code execution API to validate each hypothesis systematically ``` ## 开发说明 ``` # 在开发模式下运行 npm run dev # 运行测试 npm test # Lint code npm run lint # Type check npm run typecheck ``` ## 架构设计 ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Claude Code │────▶│ MCP Server │────▶│ Gemini API │ │ (Fast, Local, │ │ (Router & │ │ (1M Context, │ │ CLI-Native) │◀────│ Orchestrator) │◀────│ Code Exec) │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Code + Logs + │ │ Traces + Tests │ └──────────────────┘ ``` ## 安全注意事项 - **API 密钥**：将您的 Gemini API 密钥安全地存储在环境变量中 - **代码访问权限**：服务器会读取本地文件 —— 请确保文件权限设置正确 - **数据隐私**：代码将发送至 Google 的 Gemini API —— 请查阅其数据政策 ## 常见问题排查 ### "未找到 GEMINI_API_KEY" - 确保您已在 `.env` 文件或环境中设置了 `GEMINI_API_KEY` - 检查 `.env` 文件是否位于项目根目录中 ### "File not found" 错误 - 验证传递给工具的文件路径是否为绝对路径 - 检查文件权限 ### Gemini API 错误 - 验证您的 API 密钥是否有效并具有适当的权限 - 检查 API 配额和速率限制 - 确保您的 Google Cloud 项目已启用 Gemini API ### 验证错误 - 服务器使用 Zod 进行参数验证 - 确保提供了所有必需的参数 - 检查参数名称是否使用 snake_case（例如，`claude_context`，而不是 `claudeContext`） - 查看错误消息以了解特定的验证要求 ## 多模型调试的最佳实践 使用此 MCP 服务器调试分布式系统时： 1. **首先捕获时间线** —— 使用带有请求 ID 的 OpenTelemetry/Jaeger 链路追踪 2. **从 Claude Code 开始** —— 让它处理初步调查和快速修复 3. **策略性地升级**到 Gemini，当您需要： - 分析跨越数百 MB 的链路追踪 - 跨 10 个以上服务进行关联 - 使用代码执行进行迭代假设测试 4. **与传统工具结合使用**： - `go test -race`、ThreadSanitizer 用于竞态检测 - rr 或 JFR 用于确定性重放 - TLA+ 或 Alloy 用于形式化验证 ## 许可证 本项目基于 MIT 许可证授权 —— 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 作者 **Jonathan Haas** —— [GitHub 主页](https://github.com/Haasonsaas) ## 致谢 - 专为集成 Anthropic 的 Claude Code 而构建 - 由 Google 的 Gemini AI 提供支持 - 使用 Model Context Protocol (MCP) 进行通信 ## 支持 如果您遇到任何问题或有疑问： - 在 [GitHub Issues](https://github.com/Haasonsaas/deep-code-reasoning-mcp/issues) 中提交一个问题 - 查看上方的[常见问题排查部分](#troubleshooting) - 阅读 [MCP 文档](https://modelcontextprotocol.com)

标签：AI辅助编程, Claude, CVE检测, DLL 劫持, Gemini, MCP服务器, MITM代理, 代码分析, 凭证管理, 多模型协同, 大语言模型, 自动化攻击