Deep Code Reasoning MCP

🚀 深度代碼推理MCP服務器

深度代碼推理MCP服務器將Claude Code與谷歌的Gemini AI相結合，用於互補的代碼分析。該服務器支持多模型工作流，Claude Code負責緊密的終端集成和多文件重構，而Gemini則利用其100萬個標記的巨大上下文窗口和代碼執行能力，進行分佈式系統調試和長跟蹤分析。

🚀 快速開始

前提條件

• Node.js 18 或更高版本
• 擁有Gemini API訪問權限的谷歌雲賬戶
• 從 Google AI Studio 獲取的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"
});

高級用法

分佈式跟蹤分析

當故障簽名跨越多個服務且涉及GB級別的日誌時：

// Claude Code：識別錯誤模式和可疑代碼段
// 當需要關聯10多個服務中的1000多個跟蹤跨度時，升級到Gemini
// Gemini：處理完整的跟蹤時間線，確定確切的競爭窗口

性能迴歸排查

當性能下降但原因不明顯時：

// Claude Code：快速分析，確定熱點路徑
// 當需要分析數週的性能指標和代碼更改時，升級到Gemini
// Gemini：將部署時間線與性能指標關聯起來，確定確切的提交

假設驅動的調試

當你有理論但需要進行大量測試時：

// 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文件。

⚙️ 故障排除

"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：當你需要：
   • 分析跨越數百MB的跟蹤
   • 關聯10個以上服務的信息
   • 進行帶有代碼執行的迭代假設測試
4. 結合傳統工具：
   • 使用go test -race、ThreadSanitizer進行競爭檢測
   • 使用rr或JFR進行確定性回放
   • 使用TLA + 或Alloy進行形式驗證

👥 貢獻說明

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 提交拉取請求

📧 支持與反饋

如果你遇到任何問題或有疑問：

• 在GitHub Issues上打開一個問題
• 查看上面的故障排除部分
• 查閱MCP文檔

🙏 致謝

• 為與Anthropic的Claude Code集成而構建
• 由谷歌的Gemini AI提供支持
• 使用模型上下文協議（MCP）進行通信

📝 作者

Jonathan Haas - GitHub個人資料