Claude Code との GrepAI MCP 統合

このスキルは、Model Context Protocol (MCP) を使用して GrepAI を Claude Code と統合することをカバーしています。

このスキルを使用する場面

• Claude Code で GrepAI をセットアップする
• AI コーディングアシスタント用のセマンティック検索を有効にする
• Claude 用の MCP サーバーを構成する
• Claude Code 統合のトラブルシューティング

MCP とは？

Model Context Protocol (MCP) は、AI アシスタントが外部ツールを使用できるようにします。GrepAI は MCP サーバーを提供し、Claude Code に以下を提供します：

• セマンティックコード検索
• コールグラフ分析
• インデックスステータス監視

前提条件

1. GrepAI がインストールされている
2. Ollama が実行中（または他のエンベディングプロバイダー）
3. プロジェクトがインデックス化されている（grepai watch）
4. Claude Code がインストールされている

クイックセットアップ

GrepAI を Claude Code に追加する 1 つのコマンド：

claude mcp add grepai -- grepai mcp-serve

以上です！Claude Code が GrepAI ツールを使用できるようになりました。

手動構成

手動セットアップを希望する場合は、Claude Code の MCP 設定に以下を追加してください：

場所

• macOS/Linux: ~/.claude/mcp.json
• Windows: %APPDATA%\Claude\mcp.json

構成

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"]
    }
  }
}

作業ディレクトリ付き

GrepAI が常に特定のプロジェクトを使用するようにする場合：

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

インストールの確認

MCP サーバーの確認

# テスト用に MCP サーバーを手動で起動
grepai mcp-serve

以下のように表示されるはずです：

GrepAI MCP Server started
Listening for requests...

Claude Code 内

Claude に以下のように尋ねてください：

「コードベースで認証コードを検索してください」

Claude が grepai_search ツールを使用するはずです。

利用可能なツール

接続されたら、Claude Code は以下のツールにアクセスできます：

ツール	説明	パラメータ
grepai_search	セマンティックコード検索	query（必須）、limit、compact
grepai_trace_callers	関数の呼び出し元を検索	symbol（必須）、compact
grepai_trace_callees	関数の呼び出し先を検索	symbol（必須）、compact
grepai_trace_graph	コールグラフを構築	symbol（必須）、depth
grepai_index_status	インデックスの健全性を確認	verbose（オプション）

ツール使用例

セマンティック検索

Claude の要求：

「ユーザー認証に関連するコードを検索してください」

Claude が使用するもの：

{
  "tool": "grepai_search",
  "parameters": {
    "query": "user authentication",
    "limit": 5,
    "compact": true
  }
}

トレース分析

Claude の要求：

「Login 関数を呼び出している関数は何ですか？」

Claude が使用するもの：

{
  "tool": "grepai_trace_callers",
  "parameters": {
    "symbol": "Login",
    "compact": true
  }
}

インデックスステータス

Claude の要求：

「コードインデックスは最新ですか？」

Claude が使用するもの：

{
  "tool": "grepai_index_status",
  "parameters": {
    "verbose": true
  }
}

コンパクトモード

MCP ツールはデフォルトでコンパクト JSON を返し、トークンを最小化します：

{
  "q": "authentication",
  "r": [
    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"}
  ],
  "t": 2
}

これにより、完全なコンテンツと比較してトークン使用量を約 80% 削減します。

作業ディレクトリ

MCP サーバーは現在の作業ディレクトリを使用します。以下を確認してください：

1. GrepAI がプロジェクトで初期化されている
2. インデックスが存在する（まず grepai watch を実行）
3. プロジェクトディレクトリから Claude Code を開始する

オプション 1：プロジェクトディレクトリから Claude を開始

cd /path/to/your/project
claude  # Claude Code がこのディレクトリを使用するようになります

オプション 2：MCP 構成で CWD を構成

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

複数プロジェクト

複数のプロジェクトの場合、以下の方法があります：

オプション 1：複数の MCP サーバー

{
  "mcpServers": {
    "grepai-frontend": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "cwd": "/path/to/frontend"
    },
    "grepai-backend": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "cwd": "/path/to/backend"
    }
  }
}

オプション 2：ワークスペースを使用

grepai workspace create my-workspace
grepai workspace add my-workspace /path/to/frontend
grepai workspace add my-workspace /path/to/backend

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve", "--workspace", "my-workspace"]
    }
  }
}

トラブルシューティング

ツールが利用できない

❌ 問題： Claude が GrepAI ツールを認識しない

✅ 解決策：

1. 設定変更後に Claude Code を再起動する
2. MCP 設定の構文を確認する（有効な JSON）
3. grepai が PATH にあることを確認する
4. テスト：grepai mcp-serve を手動で実行

検索に結果が返されない

❌ 問題： 検索が空の結果を返す

✅ 解決策：

1. grepai watch が実行されていることを確認する
2. 作業ディレクトリに .grepai/ があることを確認する
3. インデックスが存在することを確認する：grepai status

接続が拒否される

❌ 問題： MCP サーバーが起動しない

✅ 解決策：

1. Ollama が実行中であることを確認する：curl http://localhost:11434/api/tags
2. 設定を確認する：cat .grepai/config.yaml
3. grepai mcp-serve を手動で実行してエラーを確認する

間違ったプロジェクトがインデックス化されている

❌ 問題： 間違ったコードベースから結果を得ている

✅ 解決策：

1. MCP 設定で cwd を確認する
2. 正しいディレクトリから Claude を開始する
3. grepai_index_status ツールで確認する

ベストプラクティス

1. インデックスを最新に保つ： grepai watch --background を実行する
2. コンパクトモードを使用する： トークン使用量を削減する
3. 作業ディレクトリを設定する： 設定で明示的に cwd を指定する
4. ステータスを最初に確認する： grepai_index_status ツールを使用する
5. 設定後に再起動する： Claude は MCP 変更のため再起動が必要です

統合の削除

Claude Code から GrepAI を削除するには：

claude mcp remove grepai

または ~/.claude/mcp.json を手動で編集して grepai エントリを削除します。

出力形式

成功した MCP セットアップ：

✅ GrepAI MCP Integration Configured

   Claude Code: ~/.claude/mcp.json
   Server: grepai mcp-serve
   Status: Connected

   Available tools:
   - grepai_search (semantic code search)
   - grepai_trace_callers (find callers)
   - grepai_trace_callees (find callees)
   - grepai_trace_graph (call graphs)
   - grepai_index_status (index health)

   Claude can now search your code semantically!