使用说明

MCP代码库RAG服务器

自托管MCP服务器，可将语义向量搜索添加到任何支持MCP的客户端（GitHub Copilot、Cline、Claude Desktop等）的本地代码库中。
目标：适用于Copilot（或任何MCP客户端）的强大RAG，无需支付Cursor/Windsurf费用。
零成本。零限制。完全控制。

📋 概述

问题解决了

GitHub Copilot Pro拥有出色的模型，但代码库RAG有限
Cursor/Windsurf具有良好的RAG，但每月费用为15-20美元
Continue.dev有RAG，但没有与MCP感知代理进行本地集成

解决方案

此MCP服务器提供：

索引使用向量嵌入的局部代码库
混合语义搜索 通过 search_codebase 工具——结合密集（嵌入）+稀疏（BM25）+RRF融合
多项目 支持独立的ChromaDB集合
通用集成 使用任何MCP客户端

技术栈

组件	技术	为什么
嵌入件	句子变换器 (`all-MiniLM-L6-v2`)	快速、轻便、384昏暗
代码嵌入	microsoft/unixcoder库（可选）	特定代码型号，通过激活 `EMBEDDING_MODEL`
矢量数据库	色度数据库	简单、持久、零配置
代码解析	树保姆 +BM25+RRF	通用语言无关分块和混合搜索
MCP-SDK	模型上下文协议/python sdk	官方标准
运行时	Python 3.11+	--

🚀 安装

先决条件

Python 3.11+
pip 或 uv

安装

git clone https://github.com/di5rupt0r/codebase-rag.git
cd codebase-rag

# Install as a package (adds the `codebase-rag` command to ~/.local/bin)
pip install -e .

健康检查

python scripts/health_check.py

预期产量：

🔍 MCP Codebase RAG Server Health Check
==================================================
Checking Embedding Provider... ✓ OK (3.03s)
Checking ChromaDB Connection... ✓ OK (0.14s)
Checking Search Functionality... ✓ OK (2.36s)
Checking Data Directory... ✓ OK (0.00s)
==================================================
Health Check Summary: 4/4 checks passed
🎉 All systems operational!

📖 快速开始

1.为项目编制索引

# Index the current directory
python scripts/index_project.py . --name my-project

# Index a specific path
python scripts/index_project.py ~/projects/api --name api-backend

# Force full reindex
python scripts/index_project.py . --name my-project --force

# Dry run to preview what will be indexed
python scripts/index_project.py . --name my-project --dry-run

2.启动MCP服务器

stdio（默认值--用于本地客户端）

codebase-rag

HTTP（用于远程客户端或始终在线服务）

MCP_TRANSPORT=streamable-http MCP_PORT=8080 codebase-rag

3.配置您的MCP客户端

VS代码（GitHub Copilot/Cline）--stdio模式

添加到您的VS代码 mcp.json:

{
  "servers": {
    "codebase-rag": {
      "type": "stdio",
      "command": "codebase-rag"
    }
  }
}

VS代码--HTTP模式（作为服务运行时）

{
  "servers": {
    "codebase-rag": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

克劳德桌面版

{
  "mcpServers": {
    "codebase-rag": {
      "command": "codebase-rag"
    }
  }
}

� 搜索功能

混合搜索架构

服务器实现了 混合搜索 该系统结合了：

密集搜索 （矢量嵌入）
- 使用句子变换器的语义相似性
- 查找概念上相似的代码
- 基数：ChromaDB向量相似度
稀疏搜索 （BM25）
- 精确的词汇匹配
- 查找精确的标识符和关键字
- 基数：rank-bm25，带有正则表达式标记
Reciprocal Rank Fusion：RRF（相互排名融合） （RRF）
- 密集+稀疏结果的智能融合
- k=60（标准文献值）
- 提高精确度和召回率

搜索结果

{
  "results": [
    {
      "path": "src/auth.py",
      "content": "def authenticate_user(user, password): ...",
      "score": 0.0325,
      "type": "function",
      "name": "authenticate_user", 
      "line_start": 15,
      "line_end": 25
    }
  ],
  "total_indexed_chunks": 1247,
  "query_time_ms": 23.4,
  "search_type": "hybrid_rrf"
}

性能特征

度量	目标	描述
树型解析	<50ms/文件	通用语言解析
BM25索引	<10ms/查询	内存重建
RRF融合	<1ms	内存分数计算
总查询时间	<100ms	端到端混合搜索
内存开销	<50MB	适用于5k块

回退行为

树保姆不可用 → 基于线条的组块
BM25不可用 → 仅密集搜索
两者均不可用 → 原始密集搜索，关键字重新排序

�️ MCP工具

`search_codebase`

使用向量嵌入+BM25+RRF融合对索引项目进行混合语义搜索。

输入:

{
  "query": "where is the authentication logic?",
  "top_k": 5,
  "project": "my-project",
  "file_types": [".py", ".js"]
}

输出:

{
  "results": [
    {
      "path": "src/auth.py",
      "content": "def authenticate_user(user, password):\n    ...",
      "score": 0.89
    }
  ],
  "total_indexed_chunks": 1247,
  "query_time_ms": 23
}

`reindex_project`

在发生重大更改后重新索引项目。

输入:

{
  "project_path": "/path/to/your/project",
  "project_name": "my-project",
  "force": false
}

`list_indexed_projects`

列出所有索引项目。

`get_files`

列出项目中的索引文件。

输入: { "project": "my-project" }

`get_file_content`

返回索引文件的完整内容。

输入: { "path": "src/main.py" }

⚙️ 配置

环境变量

# ChromaDB path (default: ./data/chroma_db relative to install dir)
export CHROMA_DB_PATH="/custom/path/to/chroma"

# Embedding model (default: all-MiniLM-L6-v2)
# Use microsoft/unixcoder-base for better code-specific embeddings (~2GB, requires torch)
export EMBEDDING_MODEL="microsoft/unixcoder-base"

# HTTP transport settings (only needed in HTTP/service mode)
export MCP_TRANSPORT="streamable-http"
export MCP_HOST="127.0.0.1"
export MCP_PORT="8080"
# Set this when exposing via reverse proxy or Tailscale Funnel
export MCP_ALLOWED_HOST="your-hostname.example.com"

# Log level (default: INFO)
export LOG_LEVEL="DEBUG"

分块（高级）

编辑 src/codebase_rag/config.py:

CHUNK_SIZE = 500          # characters per chunk
CHUNK_OVERLAP = 50        # overlap between chunks
DEFAULT_TOP_K = 5         # default results per search

支持的文件类型

Python、JavaScript、TypeScript、JSX、TSX、Java、C、C++、Go、Rust、Ruby、PHP、C#、Shell、YAML、JSON。

忽略模式

*.pyc, __pycache__, .git, node_modules, .venv, venv, *.egg-info, .pytest_cache

📊 基准测试

操作	预计时间	注意事项
索引20.py文件（~5k LOC）	~5-8s	第一次运行；增量要快得多
矢量搜索（top_k=5）	~20–50ms	ChromaDB正在处理中
查询嵌入	~10-20ms	语句转换器，CPU
服务器冷启动	~2-3s	模型已加载到内存中

🤖 自动化脚本

自动发现

扫描目录中的Git存储库并自动为其建立索引：

python scripts/auto_index.py ~/projects

观看模式

观察项目的文件更改，并逐步重新索引（取消公告，5秒）：

python scripts/watch.py /path/to/project --name my-project

Git钩子（提交后重新索引）

安装一个提交后挂钩，以便在每次提交后自动重新索引更改的文件：

python scripts/setup_git_hook.py /path/to/your/repo my-project

🧪 测试

# All tests (116 passing)
pytest -v

# Specific modules
pytest tests/test_config.py -v
pytest tests/test_embeddings.py -v
pytest tests/test_indexer.py -v
pytest tests/test_server.py -v

# With coverage
pytest --cov=codebase_rag --cov-report=html

🔧 作为系统部署d服务（Linux）

模板服务文件提供于 systemd/codebase-rag-server.service.
替换 YOUR_USERNAME 安装前使用您的实际Linux用户名：

# Substitute your username in-place
sed -i "s/YOUR_USERNAME/$USER/g" systemd/codebase-rag-server.service

# Install and start
sudo cp systemd/codebase-rag-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable codebase-rag-server
sudo systemctl start codebase-rag-server

# Check
sudo systemctl status codebase-rag-server
sudo journalctl -u codebase-rag-server -f

通过尾鳞片漏斗远程曝光（可选）

从远程机器（代码空间、公司笔记本电脑等）使用服务器：

# Expose port 8080 via Tailscale Funnel
tailscale funnel 8080

# Add to your service file:
# Environment="MCP_ALLOWED_HOST=your-machine.your-tailnet.ts.net"

# Then in your remote mcp.json:
# "url": "https://your-machine.your-tailnet.ts.net/mcp"

🐛 故障排除

首次启动缓慢：首次使用时下载嵌入模型（~100MB）。跑 health_check.py 对其进行预加载。

内存使用率高：默认型号使用~500MB RAM。如果需要，请通过以下方式使用更小的型号 EMBEDDING_MODEL.

权限错误：确保正在运行的用户具有对的写入权限 data/chroma_db/.

调试模式:

LOG_LEVEL=DEBUG codebase-rag

📝 贡献

分叉项目
创建要素分支： git checkout -b feature/your-feature
严格遵循TDD:RED→ 绿色→ 重构
原子性、描述性提交
打开带有测试的拉取请求

# Dev setup
pip install -e ".[dev]"
pytest -v --cov=codebase_rag

📄 许可证

MIT许可证——见许可证.