MCP Repo Rag

mcp仓库

A. 最小，基于MCP的检索系统，让Claude Sonnet 4.5搜索您的本地代码库 没有 将整个文件加载到模型中。

这通过以下方式使令牌使用率极低：

• 在本地为您的仓库建立索引
• 嵌入小块
• 将它们存储在矢量数据库（Chroma）中
• 仅检索相关片段
• 通过MCP工具将它们暴露给Claude

建筑

┌─────────────┐
│   Claude    │
│  Sonnet 4.5 │
└─────┬───────┘
      │ MCP Protocol
      ▼
┌─────────────┐      HTTP      ┌────────────┐      HTTP      ┌─────────────┐
│ MCP Server  │◄───────────────►│ Retriever  │◄──────────────►│  ChromaDB   │
│  (stdio)    │                 │    API     │                │   Server    │
│   Local     │                 │  :8000     │                │   :8001     │
└─────────────┘                 └──────┬─────┘                └─────────────┘
                                       │ HTTP                     (Docker)
                                       ▼
                                ┌─────────────┐
                                │   Ollama    │
                                │   Server    │
                                │   :11434    │
                                └─────────────┘
                                   (Docker)
                            (Embeddings: nomic-embed-text)

组件

1. Ollama服务器 （Docker）

• 用于嵌入的本地LLM服务器
• 用途 nomic-embed-text 型号（768尺寸）
• 在端口11434上运行
• 100%本地，无外部API调用
• 使用官方 ollama/ollama 图像

2. ChromaDB服务器 （Docker）

• 在Docker中运行的独立HTTP服务器
• 存储代码块的嵌入+元数据
• 保存到本地磁盘 ./chroma_db
• 在端口8001上运行
• 使用官方 chromadb/chroma 图像

3. 索引器脚本 (indexer/index.py)

• 扫描中列出的存储库 repos.json
• 块文件（每个块50行，10行重叠）
• 通过Ollama生成嵌入
• 连接到ChromaDB HTTP服务器以插入块
• 在本地运行（不在Docker中）

4. 检索器API (retriever/server.py)

• FastAPI服务器暴露 /search 端点
• 拿 { "query": "...", "top_k": 5 }
• 返回带有元数据的前k个相关块
• 使用Ollama进行查询嵌入
• 连接到ChromaDB HTTP服务器
• 在Docker的8000端口上运行

5. MCP服务器 (mcp_server/server.py)

• 暴露 search_codebase 克劳德的工具
• 使用MCP协议通过stdio进行通信
• 通过HTTP调用检索器API
• 返回格式化的代码片段
• 在本地运行（MCP需要stdio）

快速开始

1.安装依赖项

pip install -r requirements.txt

2.配置存储库

编辑 repos.json 指定要索引的存储库：

{
  "repos": [
    "./sample_repo",
    "/path/to/your/repo",
    "/Users/you/projects/another-repo"
  ]
}

3.启动所有服务

make docker-up
# or
docker-compose up -d

这将启动三项服务：

• 奥拉玛 在端口11434上（用于嵌入）
• ChromaDB 在端口8001上（矢量数据库）
• 检索器API 在端口8000上（搜索API）

验证服务是否正在运行：

make test

4.拉动Olama嵌入模型

make ollama-pull
# or
docker exec mcp-repo-rag-ollama ollama pull nomic-embed-text

这将下载 nomic-embed-text 模型（~274MB），在本地生成嵌入。

验证模型是否已安装：

make ollama-models

5.为您的存储库建立索引

make index
# or
python -m indexer.index

这将：

• 连接到ChromaDB服务器 localhost:8001
• 连接到Ollama服务器 localhost:11434
• 扫描中的所有存储库 repos.json
• 块代码文件（Python、JS、TS、Go、Rust等）
• 通过Ollama生成嵌入（本地，无外部API！）
• 将块存储在矢量数据库中

输出：

============================================================
MCP Repo RAG - Indexer with Ollama
============================================================
Connecting to ChromaDB at localhost:8001...
✓ Connected to ChromaDB
Setting up Ollama embeddings at localhost:11434...
✓ Using Ollama model: nomic-embed-text
Found 1 repositories to index
Scanning repository: /Users/you/mcp-repo-rag/sample_repo
  Indexed: /Users/you/mcp-repo-rag/sample_repo/auth.py (3 chunks)
  Indexed: /Users/you/mcp-repo-rag/sample_repo/readme.md (1 chunks)

Total chunks to index: 4
Indexed batch 1 (4 chunks)

✓ Successfully indexed 4 chunks into Chroma

Indexing complete!

测试搜索：

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "password hashing", "top_k": 3}'

6.配置克劳德桌面

将MCP服务器添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "repo-rag": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server.server"
      ],
      "cwd": "/Users/you/Documents/mcp-repo-rag",
      "env": {}
    }
  }
}

重要提示： 使用 绝对路径 到您的项目目录 cwd.

7.重新启动克劳德桌面

更新配置后，重新启动Claude Desktop。现在你应该看到 search_codebase Claude中提供的工具。

用法

配置后，您可以让Claude搜索您的代码库：

示例查询：

• “在代码库中搜索密码哈希函数”
• “查找用户身份验证码”
• “显示API中的错误处理”
• “查找数据库连接设置”

克劳德将使用 search_codebase 该工具会自动显示相关代码块，而无需加载整个文件。

项目结构

mcp-repo-rag/
├── sample_repo/           # Sample code repository
│   ├── auth.py           # Example Python authentication module
│   └── readme.md         # Sample documentation
├── indexer/              # Indexing scripts
│   ├── __init__.py
│   └── index.py          # Main indexer that scans and chunks repos
├── retriever/            # Retriever API
│   ├── __init__.py
│   └── server.py         # FastAPI server for searching
├── mcp_server/           # MCP integration
│   ├── __init__.py
│   └── server.py         # MCP server exposing search_codebase tool
├── chroma_db/            # Vector database (created by ChromaDB)
├── docker-compose.yml    # Docker orchestration (ChromaDB + Retriever)
├── Dockerfile.retriever  # Dockerfile for retriever API
├── requirements.txt      # Python dependencies
├── repos.json            # Repository configuration
├── Makefile             # Convenient commands
├── .gitignore           # Git ignore file
└── README.md            # This file

配置

repos.json

指定要索引的存储库：

{
  "repos": [
    "./sample_repo",                    # Relative path
    "/absolute/path/to/repo",          # Absolute path
    "/Users/you/projects/my-project"   # Another repo
  ]
}

支持的文件类型

索引器支持：

• 语言： .py, .js, .ts, .jsx, .tsx, .java, .cpp, .c, .h, .go, .rs, .rb, .php, .swift, .kt, .scala, .sql
• 文档： .md, .txt
• 配置： .json, .yaml, .yml, .toml, .xml
• 网状物： .html, .css

分块设置

编辑 indexer/index.py 调整：

CHUNK_SIZE = 50        # Lines per chunk
CHUNK_OVERLAP = 10     # Overlapping lines between chunks

API 参考

检索器API

基本URL: http://localhost:8000

POST /search

搜索代码库。

请求：

{
  "query": "password hashing",
  "top_k": 5,
  "filter_extensions": [".py", ".js"]
}

答复：

{
  "results": [
    {
      "text": "def hash_password(password: str):\n    ...",
      "file_path": "/path/to/auth.py",
      "start_line": 10,
      "end_line": 20,
      "filename": "auth.py",
      "score": 0.89
    }
  ],
  "total": 1
}

GET /health

健康检查端点。

GET /stats

获取收集统计数据。

MCP工具

search_codebase

参数：

• query （字符串，必填）：自然语言搜索查询
• top_k （整数，可选）：结果数（默认值：5，最大值：20）
• filter_extensions （数组，可选）：按文件扩展名筛选

例子：

Search the codebase for: "user authentication logic"

故障排除

ChromaDB问题

问题： 无法连接到ChromaDB

解决方案：

• 确保ChromaDB正在运行： docker-compose up -d chromadb
• 检查ChromaDB日志： docker-compose logs chromadb
• 验证端口8001是否未使用： lsof -i :8001
• 测试连接： curl http://localhost:8001/api/v1/heartbeat

索引器问题

问题： “无法连接到ChromaDB”

解决方案：

• 首先启动ChromaDB： docker-compose up -d chromadb
• 等待几秒钟，让ChromaDB准备就绪
• 检查ChromaDB是否正常： curl http://localhost:8001/api/v1/heartbeat

问题： 没有文件被索引

解决方案：

• 检查路径 repos.json 是正确的
• 验证是否支持文件扩展名（请参阅 SUPPORTED_EXTENSIONS 在 indexer/index.py)
• 确保目录不在跳过列表中(node_modules, venv等等）

检索器API问题

问题： API返回503“集合未初始化”

解决方案：

• 确保ChromaDB正在运行： docker-compose ps
• 首先运行索引器： make index
• 检查检索器日志： docker-compose logs retriever

MCP服务器问题

问题： 工具未出现在Claude中

解决方案：

• 验证 claude_desktop_config.json 具有正确的绝对路径
• 完全重新启动克劳德桌面
• 检查MCP服务器日志是否有错误

问题： “无法连接到检索器API”

解决方案：

• 确保检索器API正在运行： python -m retriever.server
• 或者从Docker开始： docker-compose up -d
• 验证它是否可访问 http://localhost:8000/health

重新索引

要在添加新存储库或更新代码后重新索引，请执行以下操作：

# Make sure ChromaDB and Retriever are running
docker-compose up -d

# Re-run the indexer (it will delete and recreate the collection)
make index
# or
python -m indexer.index

# Restart retriever to pick up changes
docker-compose restart retriever

发展

运行测试

# Start all services
make docker-up

# Test ChromaDB
curl http://localhost:8001/api/v1/heartbeat

# Test the retriever API
curl http://localhost:8000/health

# Run all health checks
make test

# View logs
make docker-logs

# Test the MCP server (requires retriever running)
python -m mcp_server.server

添加新文件类型

编辑 indexer/index.py:

SUPPORTED_EXTENSIONS = {
    '.py', '.js', '.ts',
    '.your_extension'  # Add here
}

自定义块大小

调整 indexer/index.py:

CHUNK_SIZE = 100       # Increase for larger chunks
CHUNK_OVERLAP = 20     # More overlap for better context

演出

• 小型仓库 （\10K文件）：考虑按目录过滤

代币节省： 使用RAG，Claude只能看到5-10个相关块（约500行），而不是整个文件（可能有数千行）。

局限性

这是一个 最小MVP未来的改进可能包括：

• 更好的组块策略（基于AST）
• 多种嵌入模型
• 按编程语言或目录筛选
• 缓存频繁访问的块
• 检索器API的身份验证
• 用于浏览索引代码的Web UI

许可证

麻省理工学院

贡献

PR欢迎！这是有意最小化的，以使其易于理解和修改。

鸣谢

内置：

• 色度 -矢量数据库
• 快速API -API框架
• MCP-SDK -模型上下文协议