grepai-mcp-cursor

用途

本技能用于将 GrepAI 通过 MCP（Model Context Protocol）集成到 Cursor IDE，使 Cursor 的 AI 能够进行语义代码搜索、调用图分析和基于索引的代码导航。

适用场景包括：在 Cursor 中设置 GrepAI、为 Cursor AI 启用语义搜索、为 Cursor 配置 MCP、排查 Cursor 集成问题。

主要能力

Cursor 是一款支持 MCP 外部工具的 AI 驱动 IDE。集成 GrepAI 后，Cursor 的 AI 可获得：

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

前置条件

• 已安装 GrepAI
• Ollama 正在运行（或其他嵌入提供方）
• 项目已建立索引（grepai watch）
• 已安装 Cursor IDE

使用方式

步骤 1：创建 MCP 配置文件

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

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

步骤 2：重启 Cursor

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

步骤 3：验证

向 Cursor 的 AI 提问：

"Search the codebase for authentication"

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 提问：

"Find code that handles user login"

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

理解依赖关系

向 Cursor 提问：

"What functions call validateToken?"

Cursor 使用 grepai_trace_callers 显示所有调用者。

代码导航

向 Cursor 提问：

"Show me the call graph for 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：工作区

# 创建工作区
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 工具

解决方案：

• 检查文件位置：项目根目录下的 .cursor/mcp.json
• 验证 JSON 语法（无尾随逗号）
• 完全重启 Cursor
• 检查 grepai 是否在 PATH 中

搜索无结果

问题：搜索结果为空

解决方案：

• 确保索引存在：grepai status
• 先运行 grepai watch
• 验证工作目录

连接错误

问题：MCP 连接失败

解决方案：

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

结果错误

问题：结果来自错误的项目

解决方案：

• 在配置中设置明确的 cwd
• 检查是否在 Cursor 中打开了正确的文件夹
• 使用 grepai_index_status 验证

性能建议

• 后台守护进程：保持 grepai watch --background 运行
• 使用紧凑模式：MCP 工具默认使用紧凑模式
• 限制结果：AI 会请求适当的限制
• 定期索引：尤其是在 git pull 之后

对比：Cursor 与 Claude Code

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

最佳实践

• 版本控制：将 .cursor/mcp.json 加入 git（不含密钥）
• 团队设置：在 README 中记录 MCP 配置
• 保持索引新鲜：运行 watch 守护进程
• 本地测试：先验证 grepai mcp-serve 可用
• 使用工作区：用于多项目设置

移除集成

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

或仅移除 GrepAI：

{
  "mcpServers": {
    // 移除 grepai 条目
  }
}

输出格式

成功的 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"