grepai-mcp-cursor

GrepAI 与 Cursor 的 MCP 集成

本技能介绍如何使用模型上下文协议（MCP）将 GrepAI 集成到 Cursor IDE 中。

何时使用此技能

• 在 Cursor 中设置 GrepAI
• 为 Cursor AI 启用语义搜索
• 为 Cursor 配置 MCP
• 排查 Cursor 集成问题

什么是 Cursor？

Cursor 是一款支持通过 MCP 使用外部工具的 AI 驱动 IDE。集成 GrepAI 后，Cursor 的 AI 可以：

• 执行超越简单文本匹配的语义代码搜索
• 分析调用图以理解依赖关系
• 基于索引导航代码

前置条件

1. 已安装 GrepAI
2. Ollama 正在运行（或使用其他嵌入提供方）
3. 项目已建立索引（grepai watch）
4. 已安装 Cursor IDE

配置

步骤 1：创建 MCP 配置文件

在项目根目录中创建 .cursor/mcp.json：

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

步骤 2：重启 Cursor

关闭并重新打开 Cursor，使配置生效。

步骤 3：验证

向 Cursor 的 AI 提问：

“搜索代码库中的身份验证”

Cursor 应使用 grepai_search 工具。

全局配置

若要在所有 Cursor 项目中使用 GrepAI，请使用全局配置：

位置

• macOS： ~/.cursor/mcp.json
• Linux： ~/.cursor/mcp.json
• Windows： %APPDATA%\Cursor\mcp.json

内容

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

项目专属配置

若要设置项目专属配置：

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

可用工具

配置完成后，Cursor 可以使用以下工具：

工具	说明
grepai_search	语义代码搜索
grepai_trace_callers	查找调用此函数的函数
grepai_trace_callees	查找此函数调用的函数
grepai_trace_graph	构建调用图
grepai_index_status	检查索引状态

使用示例

查找代码

向 Cursor 提问：

“查找处理用户登录的代码”

Cursor 会使用 grepai_search 查找语义相关的代码。

理解依赖关系

向 Cursor 提问：

“哪些函数调用了 validateToken？”

Cursor 会使用 grepai_trace_callers 显示所有调用方。

代码导航

向 Cursor 提问：

“显示 processPayment 的调用图”

Cursor 会使用 grepai_trace_graph 展示依赖关系。

Cursor 设置集成

在设置中启用 MCP

1. 打开 Cursor 设置（Cmd+, / Ctrl+,）
2. 搜索“MCP”
3. 确认已启用 MCP

验证 MCP 状态

1. 打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）
2. 搜索“MCP”
3. 检查已连接的服务

Windsurf 配置

Windsurf 使用与 Cursor 相同的 MCP 格式：

位置

创建 .windsurf/mcp.json：

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

多项目设置

选项 1：单独配置

每个项目都有自己的 .cursor/mcp.json，并设置相应的 cwd。

选项 2：工作区

# Create workspace
grepai workspace create dev
grepai workspace add dev /path/to/project1
grepai workspace add dev /path/to/project2

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

环境变量

如果 GrepAI 使用环境变量（例如 API 密钥）：

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

更好的做法： 在 shell 配置文件中设置环境变量。

故障排除

无法识别 MCP

❌ 问题： Cursor 找不到 GrepAI 工具

✅ 解决方案：

1. 检查文件位置：项目根目录中的 .cursor/mcp.json
2. 验证 JSON 语法（不能有尾随逗号）
3. 完全重启 Cursor
4. 检查 grepai 是否在 PATH 中

搜索无结果

❌ 问题： 搜索结果为空

✅ 解决方案：

1. 确保索引存在：grepai status
2. 先运行 grepai watch
3. 验证工作目录

连接错误

❌ 问题： MCP 连接失败

✅ 解决方案：

1. 手动测试：grepai mcp-serve
2. 检查 Ollama：curl http://localhost:11434/api/tags
3. 查看 Cursor 的开发者控制台中的错误

结果有误

❌ 问题： 返回了错误项目的结果

✅ 解决方案：

1. 在配置中显式设置 cwd
2. 检查在 Cursor 中打开的是否是正确的文件夹
3. 使用 grepai_index_status 进行验证

性能提示

1. 后台守护进程： 保持 grepai watch --background 运行
2. 使用精简模式： MCP 工具默认使用精简模式
3. 限制结果数量： AI 会请求适当的数量上限
4. 定期建立索引： 尤其是在 git pull 之后

对比：Cursor 与 Claude Code

功能	Cursor	Claude Code
配置位置	.cursor/mcp.json	~/.claude/mcp.json
设置命令	手动配置 JSON	claude mcp add
项目范围	按项目或全局	全局
IDE 集成	原生支持	终端

最佳实践

1. 版本控制： 将 .cursor/mcp.json 添加到 git（不包含密钥）
2. 团队设置： 在 README 中记录 MCP 配置
3. 保持索引最新： 运行监视守护进程
4. 本地测试： 先确认 grepai mcp-serve 正常运行
5. 使用工作区： 适用于多项目设置

移除集成

删除 .cursor/mcp.json 并重启 Cursor。

或者仅移除 GrepAI：

{
  "mcpServers": {
    // Remove grepai entry
  }
}

输出格式

Cursor 设置成功后：

✅ GrepAI MCP Integration for Cursor

   Config: .cursor/mcp.json
   Server: grepai mcp-serve
   Status: Ready

   Available tools:
   - grepai_search
   - grepai_trace_callers
   - grepai_trace_callees
   - grepai_trace_graph
   - grepai_index_status

   Cursor AI can now search your code semantically!

   Test: Ask Cursor "search for authentication code"