SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场grepai-mcp-claude

grepai-mcp-claude

编程与开发

查看项目

更新于 10-15 16:36

技能介绍

用途

本技能用于将 GrepAI 通过 MCP（Model Context Protocol）集成到 Claude Code 中，为 Claude Code 启用语义化代码搜索能力。适用于在 Claude Code 中设置 GrepAI、为 AI 编程助手启用语义搜索、为 Claude 配置 MCP 服务器，以及排查 Claude Code 集成问题。

什么是 MCP

Model Context Protocol（MCP）允许 AI 助手使用外部工具。GrepAI 提供一个 MCP 服务器，为 Claude Code 带来：语义代码搜索、调用图分析、索引状态监控。

前置条件

  • 已安装 GrepAI
  • Ollama 正在运行（或其他嵌入提供方）
  • 项目已建立索引（grepai watch）
  • 已安装 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 服务器进行测试：

grepai mcp-serve

应看到：

GrepAI MCP Server started
Listening for requests...

在 Claude Code 中，可向 Claude 提问：“Search the codebase for authentication code”，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 请求：“Find code related to user authentication”

Claude 使用：

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

调用关系分析：

Claude 请求：“What functions call the Login function?”

Claude 使用：

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

索引状态：

Claude 请求：“Is the code index up to date?”

Claude 使用：

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

精简模式

默认情况下，MCP 工具返回精简 JSON 以最小化 token：

{
  "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% 的 token 使用量。

工作目录

MCP 服务器使用当前工作目录。请确保：

  • GrepAI 已在项目中初始化
  • 索引已存在（先运行 grepai watch）
  • 从项目目录启动 Claude Code

方式一：从项目目录启动 Claude

cd /path/to/your/project
claude  # Claude Code now uses this directory

方式二：在 MCP 配置中设置 CWD

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

多项目

方式一：多个 MCP 服务器

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

方式二：使用工作区

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 工具
  • 解决：配置更改后重启 Claude Code；检查 MCP 配置语法（有效 JSON）；确认 grepai 在 PATH 中；手动测试 grepai mcp-serve

搜索无结果：

  • 问题：搜索返回空
  • 解决：确保已运行 grepai watch；检查工作目录是否有 .grepai/；验证索引存在：grepai status

连接被拒绝：

  • 问题：MCP 服务器无法启动
  • 解决：检查 Ollama 是否运行：curl http://localhost:11434/api/tags；验证配置：cat .grepai/config.yaml；手动运行 grepai mcp-serve 查看错误

索引了错误的项目：

  • 问题：结果来自错误的代码库
  • 解决：检查 MCP 配置中的 cwd；从正确目录启动 Claude；使用 grepai_index_status 工具验证

最佳实践

  • 保持索引更新：运行 grepai watch --background
  • 使用精简模式：减少 token 使用
  • 设置工作目录：在配置中显式指定 cwd
  • 先检查状态：使用 grepai_index_status
  • 配置后重启：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!