金大哥 - code-rag-mcp MCP 详情

article

README

🚀 Code RAG MCP 服务器

Code RAG MCP 服务器是一个用于语义代码搜索的 MCP（模型上下文协议）服务器，它可以用基于理解的代码搜索取代传统的 grep/ripgrep 搜索方式。

🚀 快速开始

在使用 Code RAG MCP 服务器之前，你需要完成以下准备工作和安装步骤。

📋 前提条件

Go 1.22+
```
brew install go
```

Qdrant（向量数据库）

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_data:/qdrant/storage \
  qdrant/qdrant

带有嵌入模型的 LM Studio
- 下载地址：https://lmstudio.ai
- 加载模型：nomic-ai/nomic-embed-text-v1.5-GGUF
- 在端口 1234 上启动本地服务器

🔧 安装步骤

# 1. 克隆仓库
git clone <your-repo>
cd code-rag-mcp

# 2. 安装依赖
go mod download

# 3. 构建项目
go build -o code-rag-mcp

# 4. 配置文件
cp config.yaml ~/.config/code-rag-mcp/config.yaml
# 使用你的代码路径编辑 config.yaml

# 5. 全局安装（可选）
sudo cp code-rag-mcp /usr/local/bin/

✨ 主要特性

✅ 语义搜索：基于概念查找代码，而非仅仅依赖文本匹配。
✅ 本地嵌入：使用 LM Studio，无需依赖 OpenAI。
✅ 多语言支持：支持 Go、Python、JS/TS、Terraform、YAML 等多种编程语言。
✅ MCP 集成：与 Claude Code 和 Zed 兼容。
✅ HTTP API：支持 Git 钩子，在提交代码时自动重新索引。
✅ 快速高效：使用 Qdrant 进行内存索引。

⚙️ 配置说明

1. Config.yaml

编辑 ~/.config/code-rag-mcp/config.yaml 文件：

embedding_type: "local"
embedding_model: "nomic-ai/nomic-embed-text-v1.5-GGUF"
embedding_base_url: "http://localhost:1234/v1"
embedding_dim: 768

code_paths:
  - "/Users/you/projects"  # 你的代码目录

2. Claude Desktop

文件路径：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "code-rag": {
      "command": "/usr/local/bin/code-rag-mcp",
      "env": {
        "LM_STUDIO_URL": "http://localhost:1234/v1"
      }
    }
  }
}

修改完成后，完全重启 Claude Desktop（退出并重新启动）。

3. Claude Code

选项 A：通过 CLI（推荐） 🚀

# 添加 code-rag MCP 服务器
claude mcp add code-rag \
  --type stdio \
  --command /usr/local/bin/code-rag-mcp \
  --scope user

# 验证安装
claude mcp list
claude mcp get code-rag

选项 B：手动配置 Claude Code 使用与 Claude Desktop 相同的文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "code-rag": {
      "command": "/usr/local/bin/code-rag-mcp",
      "env": {
        "LM_STUDIO_URL": "http://localhost:1234/v1"
      }
    }
  }
}

完整的复制粘贴命令（构建后）：

# 1. 安装二进制文件
sudo cp code-rag-mcp /usr/local/bin/
sudo chmod +x /usr/local/bin/code-rag-mcp

# 2. 添加到 Claude Code
claude mcp add code-rag \
  --type stdio \
  --command /usr/local/bin/code-rag-mcp \
  --scope user \
  --env LM_STUDIO_URL=http://localhost:1234/v1

# 3. 验证
claude mcp list

4. Zed

文件路径：~/.config/zed/settings.json

{
  "context_servers": {
    "code-rag": {
      "source": "custom",
      "command": {
        "path": "/usr/local/bin/code-rag-mcp",
        "args": [],
        "env": {
          "LM_STUDIO_URL": "http://localhost:1234/v1"
        }
      }
    }
  }
}

完整的复制粘贴命令：

# 1. 安装二进制文件（如果尚未完成）
sudo cp code-rag-mcp /usr/local/bin/
sudo chmod +x /usr/local/bin/code-rag-mcp

# 2. 将配置添加到 Zed
cat << 'EOF' >> ~/.config/zed/settings.json
{
  "context_servers": {
    "code-rag": {
      "source": "custom",
      "command": {
        "path": "/usr/local/bin/code-rag-mcp",
        "args": [],
        "env": {
          "LM_STUDIO_URL": "http://localhost:1234/v1"
        }
      }
    }
  }
}
EOF

# 3. 重启 Zed

注意：对于 Zed，你也可以在代理面板中使用“添加自定义服务器”按钮。

💻 使用示例

1. 启动服务

# 终端 1：启动 Qdrant
docker start qdrant

# 终端 2：启动 LM Studio
# 打开 LM Studio UI 并启动服务器

# 终端 3：测试服务器
./code-rag-mcp

2. 在 Claude 中使用

Claude: 你好！让我检查一下索引状态。
[调用：get_index_stats]

你：对我的 Terraform 项目进行索引
Claude: [调用：index_codebase /path/to/terraform]

你：VPC 配置在哪里？
Claude: [调用：semantic_code_search "VPC 网络配置"]

3. 示例查询

语义搜索：

"身份验证中间件"
"数据库连接逻辑"
"错误处理模式"
"Terraform AWS VPC 模块"
"API 速率限制"

查找相似代码：

"查找与 func (s *Server) HandleAuth() 相似的代码"

带上下文解释代码：

"解释 handlers/auth.go 及其相关依赖"

🔍 可用的 MCP 工具

`semantic_code_search`

主要的语义搜索工具，可替代 grep。

{
  "query": "身份验证逻辑",
  "limit": 5,
  "min_score": 0.7,
  "language": "go"
}

`find_similar_code`

查找与给定代码片段相似的代码。

{
  "code_snippet": "func HandleError(err error) { ... }",
  "limit": 5
}

`explain_code_with_context`

解释文件及其上下文。

{
  "file_path": "/path/to/file.go",
  "focus": "dependencies"
}

`index_codebase`

对目录进行索引，请先运行此命令。

{
  "path": "/Users/you/projects/myapp",
  "extensions": [".go", ".py"]
}

`get_index_stats`

检查索引状态。

🧪 测试

# 测试嵌入
go run scripts/test_embeddings.go

# 测试索引
go run scripts/test_indexing.go /path/to/code

# 测试搜索
go run scripts/test_search.go "身份验证"

📊 推荐的嵌入模型

| 模型 | 内存占用 | 维度 | 质量 | 使用场景 | |--------|-----|-----|---------|-------| | nomic-embed-v1.5 (Q8) | 548MB | 768 | ⭐⭐⭐⭐⭐ | 推荐使用 | | bge-small-en-v1.5 | 133MB | 384 | ⭐⭐⭐⭐ | 轻量级场景 | | all-MiniLM-L6-v2 | 90MB | 384 | ⭐⭐⭐ | 快速搜索场景 |

在 LM Studio 中下载

打开 LM Studio。
搜索："nomic-embed-text"。
下载：nomic-ai/nomic-embed-text-v1.5-GGUF (Q8)。
在“本地服务器”中加载模型。

🐛 故障排除

无搜索结果

# 检查索引
get_index_stats

# 重新索引
index_codebase /path/to/code

# 降低最低分数
semantic_code_search "查询内容" min_score=0.5

LM Studio 连接失败

# 检查 LM Studio 是否正在运行
curl http://localhost:1234/v1/models

# 检查日志
./code-rag-mcp --config config.yaml

Qdrant 无响应

# 重启 Qdrant
docker restart qdrant

# 检查日志
docker logs qdrant

code-rag-mcp