代码RAG MCP服务器

Local Code RAG MCP Server

一个高可用、零依赖的本地代码检索增强生成（RAG）MCP 服务器。专为配合大语言模型（LLM）进行代码库问答、调试和功能开发而设计。

✨ 核心特性

本项目致力于解决本地代码检索中的痛点，提供企业级的稳定性和检索精度：

• 🚀 高可用性 (High Resilience)

  • 自动降级策略：启动时自动检测环境。如果高性能组件（如 LanceDB）初始化失败，自动无缝切换到纯内存模式（Memory Mode），保证 99.9% 的启动成功率。
  • 多级 Worker 池：Embedding 服务采用 Worker Pool 并行处理，若失败则自动降级为单 Worker 甚至主线程模式。

• 🎯 混合检索 (Hybrid Search)

  • 精度 >85%：结合了语义向量检索 (Vector Search) 和 关键词匹配 (Keyword Matching)。
  • 智能重排序 (Reranking)：先通过向量检索召回 3 倍候选集，再利用关键词覆盖率进行加权重排序（70% 语义 + 30% 关键词），有效解决了纯向量检索无法精准定位函数名、变量名的问题。

• ⚡ 极致性能

  • 并行索引：支持多流并发读取文件和 Batch 批量 Embedding 生成，速度提升 3-5 倍。
  • 智能缓存：内置去重和 Embedding 缓存机制，增量索引极其迅速。
  • 低延迟：千级文件项目查询延迟 < 200ms。

• 🔒 隐私与离线

  • 完全本地化：所有模型（Embeddings）和向量库均在本地运行，无需任何外网 API 调用，确保代码隐私安全。

🏗 技术架构

本项目采用了分层架构设计，确保了模块的解耦和扩展性。

graph TD
    Client[MCP Client (Claude/Cursor)] --> Transport[Stdio Transport]
    Transport --> Server[MCP Server]

    subgraph Core Logic
        Server --> SearchHandler[Code Search Handler]
        Server --> FileIndexer[File Indexer]

        SearchHandler --> HybridRanker[Hybrid Reranker]
        SearchHandler --> VectorStore[Vector Store Adapter]

        FileIndexer --> Chunker[Chunker Adapter]
        FileIndexer --> EmbeddingSvc[Embedding Service]
        FileIndexer --> VectorStore

        EmbeddingSvc --> WorkerPool[Worker Pool]
        WorkerPool -- Parallel --> Model[Local ONNX Model]
    end

    subgraph Storage Layer
        VectorStore -- Primary --> LanceDB[(LanceDB Filesystem)]
        VectorStore -- Fallback --> MemoryDB[(In-Memory Map)]
    end

关键模块说明

1. VectorStoreAdapter (存储适配器)

   • 实现策略模式，自动选择最佳存储引擎。
   • Primary: LanceDB (C++ Native)，高性能持久化存储。
   • Fallback: MemoryVectorStore (纯 JS)，无本机依赖，兼容性极强。

2. EmbeddingService (向量化服务)

   • 管理本地量化模型 (Quantized ONNX models)。
   • 实现 Worker 线程池，避免阻塞 Node.js 主线程。
   • 支持 auto | bge-small | all-minilm 多种模型选择。

3. CodeSearchHandler (检索处理器)

   • Context Injection: 在 Chunk 中注入文件路径、AST 上下文（类名/函数名），提升语义理解。
   • 执行“向量召回 -> 关键词提取 -> 混合打分”的流水线。

📦 安装与使用

环境要求

• Node.js >= 18.0.0
• (可选) Python 环境（如果涉及特定构建脚本）

快速开始

1. 安装依赖

   复制

   npm install
   # 可选：安装高性能向量库（推荐）
   npm install @lancedb/lancedb
   

2. 构建项目

   复制

   npm run build
   

3. 下载模型 (首次运行自动，或手动预下载)

   复制

   # 脚本会自动下载所需的 ONNX 模型到 resources/models
   npm run download-grammars
   

4. 配置 MCP (以 Claude Desktop 为例) 在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

   复制

   {
     "mcpServers": {
       "local-code-rag": {
         "command": "node",
         "args": ["/绝对路径/to/rag-mcp/dist/index.js"],
         "env": {
           "EMBEDDING_WORKERS": "4"
         }
       }
     }
   }
   

🛠 配置选项

你可以通过环境变量来调整服务器行为：

本地 Jina Reranker v3（/v1/rerank）

本项目的 RERANK_PROVIDER=jina 通过 HTTP 调用 POST /v1/rerank（可对接你自己在本机/内网部署的服务），因此可以做到“权重本地、请求不出网”（首次下载模型权重除外）。

最小配置示例（假设你的本地服务跑在 http://127.0.0.1:8000）：

export RERANK_PROVIDER=jina
export JINA_RERANK_BASE_URL=http://127.0.0.1:8000
export JINA_RERANK_MODEL=jina-reranker-v3

本地 Transformers Reranker（Xenova/bge-reranker-base）

启用方式：

export SEARCH_TOP_K=5
export RETRIEVAL_CANDIDATES=50
export RERANK_PROVIDER=transformers
export RERANK_MODEL=Xenova/bge-reranker-base
export RERANK_MODEL_PATH=./resources/models
export RERANK_OFFLINE=true

注意：当 RERANK_OFFLINE=true 时，模型必须已存在于 RERANK_MODEL_PATH（也可用 TRANSFORMERS_RERANK_MODEL_PATH）。

Ollama Embedding (GPU 模式)

如果你希望用 GPU 跑更大的 Embedding 模型（Node 进程只做索引/搜索逻辑），确保本机已启动 Ollama 服务，然后设置：

export EMBEDDING_PROVIDER=ollama
export OLLAMA_EMBED_MODEL=nomic-embed-text   # 或你本地已有的 embedding 模型
# 可选：export OLLAMA_HOST=http://127.0.0.1:11434

# 如果从 384 维模型切换到 1024 维（如 BGE-M3），请先清理旧库或启用自动重建：
# npm run clean
# 或：export VECTORSTORE_RESET_ON_DIM_MISMATCH=1

📂 项目结构

src/
├── embeddings/     # Embedding 生成服务与 Worker 线程管理
├── handlers/       # MCP 请求处理器 (Search Logic)
├── indexing/       # 文件扫描、分块 (Chunking)、AST 解析
├── storage/        # 向量数据库适配器 (LanceDB/Memory)
├── utils/          # 通用工具 (Logger, Performance Monitor)
└── index.ts        # 程序入口与 MCP Server 定义

📊 性能基准

在 M1 Macbook Pro 上对 1000 个 TypeScript 文件的测试数据：

• 索引速度: ~50 files/sec
• 查询延迟: < 150ms (P95)
• 内存占用: ~300MB (Memory Mode) / ~150MB (LanceDB Mode)

🤝 贡献

欢迎提交 Pull Request 或 Issue！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

MIT License