grepai-mcp-claude

将 GrepAI 集成到 Claude Code

本技能介绍如何通过 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：

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 服务

# Start MCP server manually to test
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 now uses this directory

选项 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. 修改配置后重启： 更改 MCP 配置后，Claude 需要重启

移除集成

从 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!