grepai-mcp-claude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GrepAI MCP Integration with Claude Code

GrepAI与Claude Code的MCP集成

This skill covers integrating GrepAI with Claude Code using the Model Context Protocol (MCP).

本技能介绍如何通过模型上下文协议（MCP）将GrepAI与Claude Code集成。

When to Use This Skill

何时使用此技能

Setting up GrepAI in Claude Code
Enabling semantic search for AI coding assistant
Configuring MCP server for Claude
Troubleshooting Claude Code integration

在Claude Code中设置GrepAI
为AI编码助手启用语义搜索
为Claude配置MCP服务器
排查Claude Code集成问题

What is MCP?

什么是MCP？

Model Context Protocol (MCP) allows AI assistants to use external tools. GrepAI provides an MCP server that gives Claude Code:

Semantic code search
Call graph analysis
Index status monitoring

模型上下文协议（MCP）允许AI助手使用外部工具。GrepAI提供的MCP服务器可为Claude Code提供以下功能：

语义代码搜索
调用图分析
索引状态监控

Prerequisites

前提条件

GrepAI installed
Ollama running (or other embedding provider)
Project indexed (
```
grepai watch
```
)
Claude Code installed

已安装GrepAI
Ollama正在运行（或其他嵌入模型提供商）
项目已建立索引（执行
```
grepai watch
```
）
已安装Claude Code

Quick Setup

快速设置

One command to add GrepAI to Claude Code:

bash

claude mcp add grepai -- grepai mcp-serve

That's it! Claude Code can now use GrepAI tools.

一条命令即可将GrepAI添加到Claude Code：

bash

claude mcp add grepai -- grepai mcp-serve

完成！Claude Code现在可以使用GrepAI工具了。

Manual Configuration

手动配置

If you prefer manual setup, add to Claude Code's MCP config:

如果偏好手动设置，请将以下内容添加到Claude Code的MCP配置中：

Location

配置文件位置

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

macOS/Linux：
```
~/.claude/mcp.json
```
Windows：
```
%APPDATA%\Claude\mcp.json
```

Configuration

配置内容

json

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

json

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

With Working Directory

指定工作目录

If you want GrepAI to always use a specific project:

json

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

如果希望GrepAI始终使用特定项目：

json

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

Verifying Installation

验证安装

Check MCP Server

检查MCP服务器

bash

undefined

bash

undefined

Start MCP server manually to test

手动启动MCP服务器进行测试

grepai mcp-serve


You should see:

GrepAI MCP Server started Listening for requests...

undefined

grepai mcp-serve


你应该看到如下输出：

GrepAI MCP Server started Listening for requests...

undefined

In Claude Code

在Claude Code中验证

Ask Claude:

"Search the codebase for authentication code"

Claude should use the

grepai_search

tool.

向Claude提问：

"搜索代码库中的认证代码"

Claude应使用

grepai_search

工具。

Available Tools

可用工具

Once connected, Claude Code has access to these tools:

Tool	Description	Parameters
`grepai_search`	Semantic code search	`query` (required), `limit` , `compact`
`grepai_trace_callers`	Find function callers	`symbol` (required), `compact`
`grepai_trace_callees`	Find function callees	`symbol` (required), `compact`
`grepai_trace_graph`	Build call graph	`symbol` (required), `depth`
`grepai_index_status`	Check index health	`verbose` (optional)

连接后，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` （可选）

Tool Usage Examples

工具使用示例

Semantic Search

语义搜索

Claude request:

"Find code related to user authentication"

Claude uses:

json

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

Claude请求：

"查找与用户认证相关的代码"

Claude会使用：

json

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

Trace Analysis

调用追踪分析

Claude request:

"What functions call the Login function?"

Claude uses:

json

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

Claude请求：

"哪些函数调用了Login函数？"

Claude会使用：

json

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

Index Status

索引状态检查

Claude request:

"Is the code index up to date?"

Claude uses:

json

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

Claude请求：

"代码索引是否是最新的？"

Claude会使用：

json

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

Compact Mode

紧凑模式

By default, MCP tools return compact JSON to minimize tokens:

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
}

This reduces token usage by ~80% compared to full content.

默认情况下，MCP工具返回紧凑格式的JSON以减少令牌使用：

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%的令牌使用量。

Working Directory

工作目录

The MCP server uses the current working directory. Ensure:

GrepAI is initialized in your project
Index exists (run
```
grepai watch
```
first)
Start Claude Code from your project directory

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

已在项目中初始化GrepAI
已建立索引（先执行
```
grepai watch
```
）
从项目目录启动Claude Code

Option 1: Start Claude from Project Directory

选项1：从项目目录启动Claude

bash

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

bash

cd /path/to/your/project
claude  # Claude Code现在会使用此目录

Option 2: Configure CWD in MCP Config

选项2：在MCP配置中指定CWD

json

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

json

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

Multiple Projects

多项目支持

For multiple projects, you can:

对于多项目场景，你可以：

Option 1: Multiple MCP Servers

选项1：配置多个MCP服务器

json

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

json

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

Option 2: Use Workspaces

选项2：使用工作区

bash

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

json

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

bash

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

json

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

Troubleshooting

故障排查

Tool Not Available

工具不可用

❌ Problem: Claude doesn't see GrepAI tools

✅ Solutions:

Restart Claude Code after config changes
Check MCP config syntax (valid JSON)
Verify
```
grepai
```
is in PATH
Test:
```
grepai mcp-serve
```
manually

❌ 问题： Claude无法看到GrepAI工具

✅ 解决方案：

修改配置后重启Claude Code
检查MCP配置语法（确保是有效的JSON）
验证
```
grepai
```
已添加到系统PATH中
手动测试：执行
```
grepai mcp-serve
```

Search Returns No Results

搜索无结果

❌ Problem: Searches return empty

✅ Solutions:

Ensure
```
grepai watch
```
has run
Check working directory has
```
.grepai/
```
Verify index exists:
```
grepai status
```

❌ 问题： 搜索返回空结果

✅ 解决方案：

确保已执行
```
grepai watch
```
检查工作目录中是否存在
```
.grepai/
```
文件夹
验证索引是否存在：执行
```
grepai status
```

Connection Refused

连接被拒绝

❌ Problem: MCP server won't start

✅ Solutions:

Check Ollama is running:
```
curl http://localhost:11434/api/tags
```
Verify config:
```
cat .grepai/config.yaml
```
Run
```
grepai mcp-serve
```
manually to see errors

❌ 问题： MCP服务器无法启动

✅ 解决方案：

检查Ollama是否在运行：执行
```
curl http://localhost:11434/api/tags
```
验证配置：执行
```
cat .grepai/config.yaml
```
手动执行
```
grepai mcp-serve
```
查看错误信息

Wrong Project Indexed

索引了错误的项目

❌ Problem: Results from wrong codebase

✅ Solutions:

Check
```
cwd
```
in MCP config
Start Claude from correct directory
Verify with
```
grepai_index_status
```
tool

❌ 问题： 搜索结果来自错误的代码库

✅ 解决方案：

检查MCP配置中的
```
cwd
```
参数
从正确的目录启动Claude
使用
```
grepai_index_status
```
工具验证

Best Practices

最佳实践

Keep index updated: Run
```
grepai watch --background
```
Use compact mode: Reduces token usage
Set working directory: Explicit
```
cwd
```
in config
Check status first: Use
```
grepai_index_status
```
Restart after config: Claude needs restart for MCP changes

保持索引更新： 执行
```
grepai watch --background
```
使用紧凑模式： 减少令牌使用量
设置工作目录： 在配置中显式指定
```
cwd
```
先检查状态： 使用
```
grepai_index_status
```
工具
修改配置后重启： Claude需要重启才能应用MCP配置更改

Removing Integration

移除集成

To remove GrepAI from Claude Code:

bash

claude mcp remove grepai

Or manually edit

~/.claude/mcp.json

and remove the grepai entry.

要从Claude Code中移除GrepAI：

bash

claude mcp remove grepai

或者手动编辑

~/.claude/mcp.json

并删除grepai相关条目。

Output Format

输出格式

Successful MCP setup:

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

MCP设置成功后的输出：

✅ GrepAI MCP集成已配置

   Claude Code配置文件：~/.claude/mcp.json
   服务器：grepai mcp-serve
   状态：已连接

   可用工具：
   - grepai_search（语义代码搜索）
   - grepai_trace_callers（查找调用方）
   - grepai_trace_callees（查找被调用方）
   - grepai_trace_graph（调用图）
   - grepai_index_status（索引健康状态）

   Claude现在可以对您的代码进行语义搜索了！