Code Rag MCP

🚀 Code RAG MCP 服務器

Code RAG MCP 服務器是一個用於語義代碼搜索的 MCP（模型上下文協議）服務器，它可以用基於理解的代碼搜索取代傳統的 grep/ripgrep 搜索方式。

🚀 快速開始

在使用 Code RAG MCP 服務器之前，你需要完成以下準備工作和安裝步驟。

📋 前提條件

1. Go 1.22+

   brew install go
   

2. Qdrant（向量數據庫）

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

3. 帶有嵌入模型的 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 "身份驗證"

📊 推薦的嵌入模型

在 LM Studio 中下載

1. 打開 LM Studio。
2. 搜索："nomic-embed-text"。
3. 下載：nomic-ai/nomic-embed-text-v1.5-GGUF (Q8)。
4. 在“本地服務器”中加載模型。

🐛 故障排除

無搜索結果

# 檢查索引
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

📚 詳細文檔

• Claude 使用說明
• 集成指南
• API 參考

🤝 貢獻代碼

歡迎貢獻代碼！詳情請參閱 CONTRIBUTING.md

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE

🙏 致謝

• MCP 協議
• Qdrant
• LM Studio
• Nomic AI