RAG项目-用于代码理解的MCP服务器

![Tests](https://github.com/Brainwires/project-rag) ![Coverage](https://github.com/Brainwires/project-rag) ![Rust](https://www.rust-lang.org/) ![Crates.io](https://crates.io/crates/project-rag) ![License: MIT](https://opensource.org/licenses/MIT)

一种基于Rust的模型上下文协议（MCP）服务器，为AI助手提供强大的RAG（检索增强生成）功能，用于理解海量代码库。

概述

此MCP服务器使AI助手能够通过以下方式高效搜索和理解大型项目：

创建代码文件的语义嵌入
将它们存储在本地矢量数据库中
提供快速语义搜索功能
支持增量更新以提高效率

特性

本地优先：所有处理都使用fastembed-rs在本地进行（不需要API密钥）
混合搜索：使用往复式秩融合（RRF）将向量相似性与BM25关键字匹配相结合，以获得最佳结果
基于AST的分块：使用Tree sitter为12种语言提取语义单元（函数、类、方法）
全面的文件支持：索引40多种文件类型，包括代码、文档（带PDF）→Markdown转换）和配置文件
Git历史搜索：使用智能按需索引搜索提交历史记录（默认值：10次提交，仅根据需要进行更深入的索引）
多项目支持：通过项目筛选同时索引和查询多个代码库
智能索引：自动为新代码库执行完整索引，或为以前索引的代码库执行增量更新
跨进程锁定：基于文件系统的锁可防止多个进程（例如多个Claude Code会话）同时对同一代码库进行索引
并发访问保护：安全锁管理可防止多个代理尝试同时索引时索引损坏
稳定的嵌入式数据库：LanceDB矢量数据库（默认，无外部依赖），具有可选的Qdrant支持
语言检测：自动检测40多种文件类型（编程语言、文档格式和配置文件）
高级过滤：按文件类型、语言或路径模式搜索
尊敬的吉吉尼奥尔：在索引过程中自动排除忽略的文件
代码导航：查找定义、引用和调用图（轻量级LSP类功能）
自适应搜索阈值：未找到结果时自动降低相似性阈值（0.7→0.6→0.5→0.4→0.3）
Slash命令：通过MCP Prompts提供9个方便的斜线命令

MCP Slash命令

服务器提供了9个斜线命令，用于在Claude Code中快速访问：

/project:index -索引代码库目录（自动执行完整或增量）
/project:query -搜索索引代码库
/project:stats -获取索引统计信息
/project:clear -清除所有索引数据
/project:search -使用过滤器进行高级搜索
/project:git-search -使用按需索引搜索git提交历史记录
/project:definition -查找符号的定义位置（类似LSP）
/project:references -查找对某个符号的所有引用
/project:callgraph -获取函数的调用图（调用者/被调用者）

看 slash-commands.md 详细用法。

支持的文件类型

Project RAG自动索引和搜索 40+文件类型 分为三类：

编程语言（24种语言）

支持这些语言的基于AST的语义分块：

锈 (.rs)
python (.py)
JavaScript (.js, .mjs, .cjs), TypeScript (.ts), JSX (.jsx), 多伦多证券交易所 (.tsx)
去 (.go)
Java (.java)
C (.c), C (.cpp, .cc, .cxx), C/C++头文件 (.h, .hpp)
C (.cs)
迅速 (.swift)
Kotlin (.kt, .kts)
Scala (.scala)
红宝石 (.rb)
PHP (.php)
外壳 (.sh, .bash)
结构化查询语言 (.sql)
超文本标记语言 (.html, .htm)
层叠样式表 (.css), SCSS (.scss, .sass)

文档格式（8种格式）

对丰富内容进行特殊处理：

标记语言 (.md, .markdown)
PDF (.pdf) - 自动转换为Markdown 有桌子保护
重新结构化文本 (.rst)
AsciiDoc (.adoc, .asciidoc)
组织模式 (.org)
纯文本 (.txt)
日志文件 (.log)

PDF转换功能：

使用提取文本内容 pdf-extract 图书馆
自动转换为Markdown格式
蜜饯 表格结构 （检测制表符/空格分隔的列）
检测和格式化标题（所有大写线条和剖面标记）
智能处理多列布局
与任何其他文本文件一样的块（默认情况下每个块50行）

配置文件（8种格式）

为了全面了解项目：

JSON (.json)
YAML (.yaml, .yml)
汤姆 (.toml)
可扩展标记语言 (.xml)
INI (.ini)
配置文件 (.conf, .config, .cfg)
属性 (.properties)
环境 (.env)

示例用例

# Index documentation PDFs in your project
query_codebase("API authentication flow")  # Finds content in .pdf, .md, .rst files

# Search configuration files
query_codebase("database connection string")  # Finds .yaml, .toml, .env, .conf files

# Find code implementations
search_by_filters(query="JWT validation", file_extensions=["rs", "go"])

MCP工具

服务器提供了9个可以直接使用的工具：

指数_贬值 -智能地索引代码库目录

- 自动为新代码库执行完整索引 - 自动对以前索引的代码库执行增量更新 - 尊重、尊重和排除模式 - 返回模式信息（完整或增量）

查询_降级 -跨索引代码的混合语义+关键字搜索

- 将向量相似性与BM25关键字匹配相结合（默认启用） - 返回包含向量和关键字分数的相关代码块 - 可配置的结果限制和分数阈值 - 多项目设置的可选项目筛选

get_统计 -获取索引代码库的统计信息

- 文件计数、块计数、嵌入计数 - 语言细分

clear_index -清除所有索引数据

- 删除整个矢量数据库集合 - 为新索引做准备

search_by_filters -带过滤器的高级混合搜索

- 始终使用混合搜索以获得最佳结果 - 按文件扩展名过滤（例如，\[“rs”，“toml”\]） - 按编程语言筛选 - 按路径模式过滤 - 可选项目筛选

search_git_历史 -使用语义搜索搜索git提交历史

- 按需自动索引提交（默认：10次提交，可配置） - 搜索提交消息、差异、作者信息和更改的文件 - 智能缓存：只根据需要索引新的提交 - 按作者姓名/电子邮件和文件路径过滤正则表达式 - 日期范围过滤（ISO 8601或Unix时间戳） - 分行选择支持

find_definition -查找符号的定义位置（类似LSP）

- 指定文件路径、行号和列 - 返回包含符号元数据的定义位置 - 使用混合方法：高精度堆栈图（Python、TypeScript、Java、Ruby）或基于AST的RepoMap回退 - 报告结果的精度水平

查找引用 -查找对某个符号的所有引用

- 指定文件路径、行号和列 - 返回使用该符号的所有位置 - 对引用类型进行分类：调用、读取、写入、导入、类型引用、继承、实例化 - 可选：在结果中包含定义站点

get_call_graph -获取函数的调用图

- 为函数指定文件路径、行号和列 - 返回调用者（调用此函数的内容）和被调用者（此函数调用的内容） - 可配置的遍历深度（默认值：1级） - 有助于理解代码流和影响分析

先决条件

锈：1.88+支持Rust 2024版本
protobuf编译器：建筑所需（通过安装 sudo apt-get install protobuf-compiler 在Ubuntu/Debian上）

矢量数据库选项

LanceDB（默认-嵌入式，稳定）

无需额外设置！LanceDB是一个直接在应用程序中运行的嵌入式矢量数据库。它将数据存储在 ./.lancedb 默认情况下为目录。

为什么LanceDB是默认设置：

嵌入式 -无需外部依赖或服务器
稳定 -ACID交易证明了生产
丰富 -完整的SQL类过滤功能
内置混合搜索 -具有互易秩融合的Tantivy BM25+LanceDB向量
柱状存储器 -使用Apache Arrow高效处理大型数据集
零拷贝 -用于快速查询的内存映射文件

Qdrant（可选-基于服务器）

要使用Qdrant而不是LanceDB，请使用 qdrant-backend 特点：

cargo build --release --no-default-features --features qdrant-backend

然后启动Qdrant实例：

使用Docker（推荐）：

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

使用Docker Compose：

version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_data:/qdrant/storage

或者单独下载： https://qdrant.tech/documentation/guides/installation/

安装

# Navigate to the project
cd project-rag

# Install protobuf compiler (Ubuntu/Debian)
sudo apt-get install protobuf-compiler

# Build the release binary (with default LanceDB backend - stable and embedded!)
cargo build --release

# Or build with Qdrant backend (requires external server)
cargo build --release --no-default-features --features qdrant-backend

# The binary will be at target/release/project-rag

用法

作为MCP服务器运行

服务器通过stdio按照MCP协议进行通信：

./target/release/project-rag

在Claude代码中配置

使用CLI将MCP服务器添加到Claude Code：

# Navigate to the project directory first
cd /path/to/project-rag

# Add the MCP server to Claude Code
claude mcp add project --command "$(pwd)/target/release/project-rag"

# Or with logging enabled
claude mcp add project --command "$(pwd)/target/release/project-rag" --env RUST_LOG=info

添加后，重新启动Claude Code以加载服务器。斜线命令(/project:index, /project:query等等）将立即可用。

在Claude Desktop中配置

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "project-rag": {
      "command": "/absolute/path/to/project-rag/target/release/project-rag",
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

备注：Claude Code和Claude Desktop是不同的产品，具有不同的配置方法。

工具使用示例

索引代码库：

{
  "path": "/path/to/your/project",
  "include_patterns": ["**/*.rs", "**/*.toml"],
  "exclude_patterns": ["**/target/**", "**/node_modules/**"],
  "max_file_size": 1048576
}

查询代码库：

{
  "query": "How does authentication work?",
  "limit": 10,
  "min_score": 0.7
}

高级筛选搜索：

{
  "query": "database connection pool",
  "limit": 5,
  "min_score": 0.75,
  "file_extensions": ["rs"],
  "languages": ["Rust"],
  "path_patterns": ["src/db"]
}

索引（或重新索引）代码库：

{
  "path": "/path/to/your/project",
  "include_patterns": [],
  "exclude_patterns": []
}

*注意：这会自动为新代码库执行完整索引，或为以前索引的代码库执行增量更新。*

查找符号的定义：

{
  "file_path": "/path/to/your/project/src/main.rs",
  "line": 42,
  "column": 10
}

查找对符号的所有引用：

{
  "file_path": "/path/to/your/project/src/lib.rs",
  "line": 15,
  "column": 8,
  "include_definition": false
}

获取函数的调用图：

{
  "file_path": "/path/to/your/project/src/api.rs",
  "line": 100,
  "column": 4,
  "depth": 2
}

建筑

project-rag/
├── src/
│   ├── bm25_search.rs      # Tantivy BM25 keyword search with RRF fusion
│   ├── client/             # High-level client API
│   │   ├── mod.rs          # RagClient - unified interface for all operations
│   │   └── indexing/       # Indexing pipeline with progress reporting
│   ├── embedding/          # FastEmbed integration for local embeddings
│   │   ├── mod.rs          # EmbeddingProvider trait
│   │   └── fastembed_manager.rs  # all-MiniLM-L6-v2 implementation
│   ├── vector_db/          # Vector database implementations
│   │   ├── mod.rs          # VectorDatabase trait
│   │   ├── lance_client.rs # LanceDB + Tantivy hybrid search (default)
│   │   └── qdrant_client.rs  # Qdrant implementation (optional)
│   ├── indexer/            # File walking and code chunking
│   │   ├── mod.rs          # Module exports
│   │   ├── file_walker.rs  # Directory traversal with .gitignore + 40+ file types
│   │   ├── chunker.rs      # Chunking strategies (AST-based, fixed-lines, sliding window)
│   │   ├── ast_parser.rs   # Tree-sitter AST parsing for 12 languages
│   │   └── pdf_extractor.rs # PDF to Markdown converter with table support
│   ├── relations/          # Code relationship analysis (LSP-like features)
│   │   ├── mod.rs          # RelationsProvider trait, HybridRelationsProvider
│   │   ├── types.rs        # SymbolId, Definition, Reference, CallEdge types
│   │   ├── repomap/        # AST-based symbol extraction (fallback provider)
│   │   │   ├── mod.rs      # RepoMapProvider
│   │   │   ├── symbol_extractor.rs  # Extract definitions from AST
│   │   │   └── reference_finder.rs  # Find references via identifier matching
│   │   ├── storage/        # Relations storage layer
│   │   │   ├── mod.rs      # RelationsStore trait
│   │   │   └── lance_store.rs  # LanceDB storage (placeholder)
│   │   └── stack_graphs/   # Optional: High-precision name resolution
│   │       └── mod.rs      # StackGraphsProvider (feature-gated)
│   ├── mcp_server.rs       # MCP server with 9 tools
│   ├── types/              # Request/Response types with JSON schema
│   │   └── mod.rs          # All MCP request/response types
│   ├── main.rs             # Binary entry point with stdio transport
│   └── lib.rs              # Library root
├── Cargo.toml              # Rust 2024 edition with dependencies
├── README.md               # This file
├── CONTRIBUTING.md         # Contributor guidelines
├── TESTING.md              # Testing guide
└── CLAUDE.md               # AI assistant instructions

配置

环境变量

RUST_LOG -设置日志记录级别（选项： error, warn, info, debug, trace)

- 例子： RUST_LOG=debug cargo run

Qdrant配置

目前硬编码为 http://localhost:6334
未来：添加配置文件支持

嵌入模型

违约： all-MiniLM-L6-v2 （384个维度）
首次运行下载模型（~50MB）到缓存

分块策略

默认：基于混合AST，可回退到固定线路
AST解析：提取Rust、Python、JavaScript、TypeScript、Go、Java、Swift、C、C++、C#、Ruby、PHP的语义单元（函数、类、方法）
后备方案：对于不支持的语言，每个块50行
替代：可配置重叠的滑动窗口

技术细节

嵌入

模型：全MiniLM-L6-v2（句子转换）
维度: 384
图书馆：带ONNX运行时的fastembed rs
演出：约500次嵌入/秒

向量数据库

发动机：Qdrant
距离度量：余弦相似性
索引：HNSW用于快速近似最近邻搜索
有效载荷：存储文件路径、项目、行号、语言、哈希、时间戳、内容

混合搜索

向量相似性：通过嵌入进行语义理解（LanceDB或Qdrant）
关键词匹配：通过Tantivy倒排索引进行全文BM25搜索
融合算法：k=60常数的互易秩融合（RRF）
BM25参数：使用Tantivy优化的BM25实现
排名：RRF使用1/（k+排名）公式组合两个排名
演出：并行查询两个索引以获得快速结果

自适应阈值逻辑

两者 query_codebase 和 search_by_filters 工具实现了智能自适应阈值降低：

它是如何工作的：

初始搜索使用所请求的 min_score 阈值（默认值：0.7）
如果未找到结果且阈值>0.3，则自动以较低的阈值重试
按顺序尝试的回退阈值：0.6→ 0.5 → 0.4 → 0.3
响应包括 threshold_used 和 threshold_lowered 透明度字段

优点：

防止语义相似度低于预期时出现空结果
尽可能选择更高的阈值来保持搜索质量
透明：您始终知道实际使用的阈值

示例响应：

{
  "results": [...],
  "duration_ms": 45,
  "threshold_used": 0.4,
  "threshold_lowered": true
}

轻量级LSP功能

Project RAG提供了类似于语言服务器协议（LSP）实现的代码导航功能，但针对语义搜索用例进行了优化：

查找定义 (find_definition):

定位定义符号（函数、类、变量）的位置
使用混合方法：Python、TypeScript、Java、Ruby的高精度堆栈图
对所有其他语言回归到基于AST的RepoMap分析
报告结果中的精度级别（高、中、低）

查找引用 (find_references):

查找整个代码库中使用符号的所有位置
对引用类型进行分类：调用、读取、写入、导入、类型引用、继承、实例化
有助于理解代码是如何连接的
包含/排除定义站点的选项

获取调用图 (get_call_graph):

分析函数调用关系
显示调用者（调用此函数的内容）和被调用者（此函数调用的内容）
多级分析的可配置遍历深度
非常适合影响分析和理解代码流

架构：

RelationsProvider (trait)
├── StackGraphsProvider (high precision: ~95%)
│   └── Supports: Python, TypeScript, Java, Ruby
└── RepoMapProvider (fallback: ~70% precision)
    └── Supports: All tree-sitter languages (12+)

何时使用：

查找定义“这个功能在哪里定义？”
查找引用：“从哪里调用此函数？”
获取调用图：“此代码依赖于哪些功能？”

跨进程锁定

RAG项目使用 双层锁闭系统 为了防止多个进程同时对同一代码库进行索引：

第1层：文件系统锁（跨进程）

用途 flock() 操作系统级独占锁的系统调用
锁定存储在中的文件 ~/.local/share/project-rag/locks/ （或 brainwires/locks/)
进程退出时自动释放（即使在崩溃时）
防止多个克劳德代码会话用重复索引攻击CPU

第2层：内存锁（进程中）

广播通道允许等待任务接收结果
防止同一流程中的重复工作

工作原理：

Process A (Claude Session 1)          Process B (Claude Session 2)
─────────────────────────────          ─────────────────────────────
index_codebase("/project")             index_codebase("/project")
        │                                       │
        ▼                                       ▼
Acquire filesystem lock                Try filesystem lock
        │                                       │
        ▼                                       ▼
     ACQUIRED                              BLOCKED (waits)
        │                                       │
        ▼                                       │
Do full indexing...                             │
        │                                       │
        ▼                                       │
Release lock ──────────────────────────────────►│
                                                ▼
                                         Lock acquired
                                                │
                                                ▼
                                         Return (index is current)

优点：

在多个Claude Code会话中没有重复的CPU工作
并发写入不会导致数据库损坏
进程崩溃时自动清理（操作系统发布羊群）
索引完成后，等待过程立即得到响应

BM25索引锁安全

BM25（Tantivy）索引使用额外的基于文件的锁来防止并发写入：

死锁检测：

检查锁文件是否过期（超过5分钟）
使用文件修改时间戳来检测崩溃的进程
新鲜锁（\>

异步特性警告

- 9个无害的警告 async fn 公共特征 - 外观问题，不影响功能

局限性

当前限制

Qdrant后端：使用Qdrant后端功能时需要外部Qdrant服务器

- 默认LanceDB后端完全嵌入，没有外部依赖关系

型号下载：首次运行下载~50MB型号

- 未来：在二进制文件中包含模型或提供离线安装程序

路径筛选：当前查询后过滤（未优化）

- 未来：为路径模式添加Qdrant有效载荷索引

无配置文件：所有设置都硬编码

- 未来：添加TOML/YAML配置支持

规模限制

大型代码库：包含100000多个文件的项目可能需要花费大量时间进行索引

- 缓解措施：使用增量更新

记忆：非常大的索引（1M以上的块）可能需要大量的RAM

- 典型项目（5k文件）总共使用\5分钟）。你应该很少需要人工干预。

Qdrant连接失败

# Check if Qdrant is running
curl http://localhost:6334/health

# View Qdrant logs
docker logs

模型下载失败

# Pre-download model
python -c "from fastembed import TextEmbedding; TextEmbedding()"

# Or set HuggingFace mirror
export HF_ENDPOINT=https://hf-mirror.com

内存不足

# Reduce batch size (edit source)
# Or index in smaller chunks
# Or use smaller embedding model

索引速度慢

# Check disk I/O
# Reduce max_file_size
# Use exclude_patterns to skip unnecessary files

未来的增强功能

高优先级

\[\]添加全面的集成测试
\[\]配置文件支持（TOML）
\[\]将IDF统计数据缓存到磁盘，以加快启动速度

中优先级

\[\]嵌入式矢量数据库选项（无外部依赖）
\[\]支持更多嵌入模型
\[\]性能基准和分析
\[\]AST支持更多语言（Kotlin、Perl、Scala等）

低优先级

\[\]用于测试/调试的Web UI
\[\]指标和监控端点
\[\]多语言文档
\[\]替代传输机制（HTTP、WebSocket）

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请确保：

代码质量:

- 源文件保持在600行以下（强制） - 代码格式为 cargo fmt - 夹棉绒通行证(cargo clippy)

测试:

- 添加新功能的测试 - 现有测试通过(cargo test) - 更新文档

提交:

- 清晰、描述性的提交消息 - 每次提交一个逻辑更改 - 参考问题（如适用）

支持

问题: https://github.com/Brainwires/project-rag/issues
文档：参见 docs/ 用于部署、故障排除和斜线命令
建筑：参见 docs/adr/ 用于架构决策记录

致谢

rmcp：官方Rust模型上下文协议SDK
Qdrant：高性能矢量数据库
快速嵌入：快速生成本地嵌入
克劳德：用于MCP协议和测试

______________________________________________________________________

建于❤️ 使用Rust 2024版本

Project Rag

快速接入

详细介绍