Deep Code Reasoning MCP

🚀 Deep Code Reasoning MCP Server

Claude CodeとGoogleのGemini AIを組み合わせた、相補的なコード分析を行うMCPサーバーです。このサーバーは、Claude Codeがターミナルとの密な統合やマルチファイルのリファクタリングを担当し、Geminiが大規模なコンテキストウィンドウ（100万トークン）とコード実行機能を活用して分散システムのデバッグや長いトレース分析を行う、マルチモデルワークフローを可能にします。

🚀 クイックスタート

このMCPサーバーは、Claude CodeとGoogleのGemini AIを組み合わせて、相補的なコード分析を行います。以下の手順でサーバーをセットアップし、利用を開始できます。

✨ 主な機能

• Gemini 2.5 Pro Preview：Googleの最新のGemini 2.5 Pro Preview（05-06）モデルを使用し、100万トークンのコンテキストウィンドウを持ちます。
• 会話型分析：新機能！ClaudeとGeminiの間でAI同士の対話を行い、反復的な問題解決を可能にします。
• 実行フロートレーシング：関数呼び出しだけでなく、データフローと状態変換を理解します。
• システム間影響分析：サービス境界を越えた変更の伝播をモデル化します。
• パフォーマンスモデリング：N+1パターン、メモリリーク、アルゴリズムのボトルネックを特定します。
• 仮説検証：コードの振る舞いに関する理論を、証拠に基づく検証でテストします。
• 長いコンテキストサポート：Gemini 2.5 Pro Previewの100万トークンのコンテキストを活用して、大規模なコードベースを分析します。

📦 インストール

前提条件

• Node.js 18以上
• Gemini APIへのアクセスがあるGoogle Cloudアカウント
• Google AI Studioから取得したGemini APIキー

インストール手順

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

💻 使用例

会話型分析の例

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: エラーパターンと疑わしいコードセクションを特定する
// Geminiにエスカレートするタイミング: 10以上のサービスにまたがる1000以上のトレーススパンを関連付ける必要がある場合
// Gemini: 完全なトレースタイムラインを処理し、正確な競合ウィンドウを特定する

ケース2: パフォーマンス劣化の調査

パフォーマンスが低下したが、原因が明らかでない場合：

// Claude Code: 迅速なプロファイリングを行い、ホットパスを特定する
// Geminiにエスカレートするタイミング: 数週間のパフォーマンスメトリクスとコード変更を分析する必要がある場合
// Gemini: デプロイメントタイムラインとパフォーマンスメトリクスを関連付け、正確なコミットを特定する

ケース3: 仮説駆動型デバッグ

理論があるが、広範なテストが必要な場合：

// Claude Code: 症状に基づいて初期の仮説を形成する
// Geminiにエスカレートするタイミング: 合成データを使用して20以上のシナリオをテストする必要がある場合
// Gemini: コード実行APIを使用して、各仮説を体系的に検証する

📚 ドキュメント

設定

環境変数

• 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が100万トークンのコンテキストで分析を行い、可視化された「思考」トレースを表示する
5. 結果がClaude Codeに返され、修正が実装される

利用可能なツール

注意：ツールのパラメータはsnake_caseの命名規則を使用し、Zodスキーマを使用して検証されます。実際の実装では、これらの簡略化された例よりも詳細な型安全性が提供されます。完全なTypeScript型定義はsrc/models/types.tsにあります。

会話型分析ツール

サーバーには、ClaudeとGeminiが複雑な分析のための複数回の対話を行うことを可能にするAI同士の会話型ツールが含まれています。

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[];    // オプションの{file, line, function_name?}の配列
  };
  test_approach: string;
}

🔧 技術詳細

アーキテクチャ

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

開発

# 開発モードで実行
npm run dev

# テストを実行
npm test

# コードをリント
npm run lint

# 型チェック
npm run typecheck

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

トラブルシューティング

"GEMINI_API_KEY not found"

• .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にエスカレートする：
   • 100MB以上のトレースの分析が必要な場合
   • 10以上のサービス間の関連付けが必要な場合
   • コード実行を伴う反復的な仮説検証が必要な場合
4. 従来のツールと組み合わせる：
   • go test -race、ThreadSanitizerを使用して競合検出を行う
   • rrまたはJFRを使用して決定的なリプレイを行う
   • TLA+またはAlloyを使用して形式検証を行う

貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新機能に対するテストを追加します。
5. プルリクエストを送信します。

作者

Jonathan Haas - GitHub Profile

謝辞

• AnthropicのClaude Codeとの統合のために構築されました。
• GoogleのGemini AIを使用しています。
• 通信にはModel Context Protocol（MCP）を使用しています。

サポート

問題が発生した場合や質問がある場合は、以下の方法で対応してください。

• GitHub Issuesで問題を報告します。
• 上記のトラブルシューティングセクションを確認します。
• MCPドキュメントを確認します。