mcp-rag-server (本地RAG MCP服务器，适用于任何仓库)

mcp-rag-server 是一个轻量级、零网络（模型下载后）的检索增强生成助手，可以集成到任何支持[模型上下文协议（MCP）]的客户端中。GitHub Copilot Agent模式在Visual Studio / VS Code中只是其中一个选项——您也可以使用官方的MCP Inspector、未来的MCP感知IDE或自定义工具。

它会对目标仓库目录进行索引，对内容进行分块（默认分块大小为800字符，重叠120字符——这两个参数可以通过CHUNK_SIZE / CHUNK_OVERLAP进行配置），使用@xenova/transformers构建本地嵌入，并提供MCP工具：

• rag_query – 返回评分片段的语义搜索（路径、分数、片段）
• read_file – 安全读取文件（可选行范围），限制在REPO_ROOT
• list_files – 列出目录内容（文件及子目录），可选递归、深度和扩展名过滤

支持两种传输方式（通过MCP_TRANSPORT=stdio|http选择）：

• stdio – 对于启动进程的IDE来说是最简单的集成方式（向后兼容的默认值）
• http（流式HTTP）– 推荐用于大型仓库/首次运行，这样可以在连接客户端之前查看日志并检查是否准备好。通过MCP_TRANSPORT=http启用，默认包括DNS重新绑定保护。

功能

• 通过@xenova/transformers实现纯本地嵌入推理（无需外部API调用）
• 多语言源码+文档支持（可通过ALLOWED_EXT进行配置）
• 支持排除文件夹模式（可通过EXCLUDED_FOLDERS进行配置）
• 快速通配符文件发现和重叠分块以提高召回率
• 简单的余弦相似度排名（可选后期替换为ANN）
• 通过MODEL_NAME插件式模型选择（参见下方指导）
• 可选持久化JSON索引+热启动及增量重新索引（通过INDEX_STORE_PATH）
• 增量变更检测（添加/删除/文件大小变化）以避免完全重建
• Stdio或流式HTTP传输（可选主机白名单/DNS重新绑定保护）
• 安全路径处理（拒绝尝试逃逸REPO_ROOT的操作）
• 最小依赖；首次加载模型后快速启动
• 准备扩展：添加新的MCP工具或ANN/混合检索后端

计划/理想特性：混合BM25+嵌入搜索，ANN加速（HNSW/IVF），按语言分词启发式，批量/并行嵌入，语义边界感知分块。

要求

• Node.js 18+
• Visual Studio 2022 17.14+，带有GitHub Copilot（启用Agent模式）
• 您的仓库路径（REPO_ROOT）

安装

npm install npm run build

运行（本地测试）

构建然后启动（默认为stdio传输）。使用npm start或直接调用已构建的文件。

Windows PowerShell

npm run build
$env:REPO_ROOT="C:\path\to\your-repo"; node dist/index.js

或者：

$env:REPO_ROOT="C:\path\to\your-repo"; npm start

macOS / Linux (bash/zsh)

npm run build
export REPO_ROOT="/path/to/your-repo"; node dist/index.js

或者：

export REPO_ROOT="/path/to/your-repo"; npm start

可选设置模型缓存以加快后续运行速度（首次启动时会下载模型一次）：

export TRANSFORMERS_CACHE="/path/to/cache"   # macOS/Linux
$env:TRANSFORMERS_CACHE="C:\path\to\cache" # Windows PowerShell

流式HTTP模式（推荐用于大型初始索引）

作为HTTP端点运行MCP服务器，并且只有在Embeddings ready.显示后才打开IDE（避免冷启动时客户端超时）：

npm run build
$env:REPO_ROOT="C:\path\to\your-repo"; $env:MCP_TRANSPORT="http"; npm start

export REPO_ROOT="/path/to/your-repo"; MCP_TRANSPORT=http npm start

默认HTTP绑定：http://127.0.0.1:3000/mcp。通过`HOST`和`MCP_PORT`环境变量覆盖。在`http://127.0.0.1:3000/health`可用的就绪端点返回类似以下的JSON：

{
	"version": "0.x.y",
	"repoRoot": "C:/abs/path",
	"modelName": "<embedding model>",
	"transport": "stdio" | "http",
	"ready": true | false,
	"startedAt": "2025-01-01T00:00:00.000Z",
	"indexing": {
		"filesDiscovered": 123,
		"chunksTotal": 456,
		"chunksEmbedded": 123
	}
}

ready仅在所有发现的分块都有嵌入后变为true（冷构建或增量更新完成后）。

指令端点

服务器还暴露了GET /instructions，该端点提供Markdown文件docs/copilot-instructions.md，其中所有出现的<FOLDER_INFO_NAME>都被环境中的FOLDER_INFO_NAME值替换（默认REPO_ROOT）。

注意：

• 从仓库根目录启动服务器，以便docs/copilot-instructions.md通过当前工作目录解析。
• 响应内容类型是text/markdown; charset=utf-8。

代码检查与格式化

• 运行ESLint（检查）：npm run lint
• 自动修复ESLint问题：npm run lint:fix
• 使用Prettier格式化：npm run format
• 检查格式：npm run format:check

使用MCP Inspector测试（无需VS）

使用MCP Inspector在本地测试服务器，并尝试工具而无需Visual Studio。

Windows PowerShell：

npm run build
$env:REPO_ROOT="C:\path\to\your-repo"; npx @modelcontextprotocol/inspector node .\\dist\\index.js

通过Inspector的流式HTTP（Windows）：

npm run build
$env:REPO_ROOT="C:\path\to\your-repo"; $env:MCP_TRANSPORT="http"; npx @modelcontextprotocol/inspector http://localhost:3000/mcp --transport http

macOS/Linux (bash/zsh)：

export REPO_ROOT="/path/to/your-repo"
npx @modelcontextprotocol/inspector node dist/index.js

流式HTTP（macOS/Linux）：

export REPO_ROOT="/path/to/your-repo"; MCP_TRANSPORT=http npx @modelcontextprotocol/inspector http://localhost:3000/mcp --transport http

注意：

• 首次运行会下载嵌入模型并构建嵌入；Inspector会在启动完成后再连接。请关注终端中打印到stderr的进度日志。
• 您还可以在项目根目录下的.env文件中放置设置（例如，REPO_ROOT，TRANSFORMERS_CACHE）。

在Inspector UI中：

• 点击“列出工具”以验证这些工具是否可用：rag_query，read_file，list_files。
• 选择一个工具并点击“调用工具”。提供如下的JSON输入。

示例

1. 在仓库上进行语义搜索

工具：rag_query
输入JSON：
{
	"query": "protobuf消息X模式",
	"top_k": 5
}

响应包括具有path，score和snippet的匹配数组。

2. 列出目录中的文件（默认非递归）

工具：list_files
输入JSON：
{
	"dir": "src",
	"recursive": false
}

递归，带过滤器和限制：

工具：list_files
输入JSON：
{
	"dir": "src",
	"recursive": true,
	"maxDepth": 3,
	"includeExtensions": ["ts", "md"],
	"limit": 200
}

响应形状：

{
	"entries": [
		{ "path": "src/", "type": "dir" },
		{ "path": "src/index.ts", "type": "file", "size": 1234 },
		{ "path": "src/lib/", "type": "dir" }
	]
}

3. 读取文件（可选行范围）

工具：read_file
输入JSON：
{
	"path": "src/path/to/file.txt",  // 相对于REPO_ROOT
	"startLine": 1,
	"endLine": 120
}

故障排除

• 启动慢：将TRANSFORMERS_CACHE设置为快速本地文件夹，并（可选）设置ALLOWED_EXT（例如，仅针对TypeScript/JS的ts,tsx,js，或任何您需要的列表）。
• 路径错误：path必须相对于REPO_ROOT。为了安全起见，绝对路径会被拒绝。
• Inspector中长时间无响应：服务器仍在初始化（模型下载+嵌入）。这是首次运行时的预期行为。
  • 慢速热重启：提供INDEX_STORE_PATH使嵌入持久化，并仅重新嵌入更改的文件。

环境配置（.env）

您可以通过本地.env文件配置环境变量。

步骤：

• 将.env.example复制为.env。
• 根据需要编辑值。

支持的变量：

• REPO_ROOT（必需）：要索引的仓库路径。
• FOLDER_INFO_NAME（可选）：用于MCP工具描述中仓库根目录的显示标签（默认REPO_ROOT）。这只是为了客户端用户体验的美观；它不会影响哪个目录被索引（这仅由REPO_ROOT控制）。如果您希望在工具元数据和返回给客户端的路径指南中显示更友好的名称（例如frontend-app或monorepo-root），则可以设置它。
• TRANSFORMERS_CACHE（可选）：模型文件的缓存文件夹。
• ALLOWED_EXT（可选）：逗号分隔的要索引的文件扩展名列表。
• EXCLUDED_FOLDERS（可选）：逗号分隔的要从索引中排除的文件夹模式列表。支持确切的文件夹名称（例如node_modules,dist,build,.git）和基本通配符模式（例如**/test/**,**/tests/**）。这些文件夹中的文件将在索引期间被跳过。默认包括常见的构建/依赖项文件夹：node_modules，dist，build，.git，target，bin，obj，.cache，coverage，.nyc_output。
• MCP_TRANSPORT（可选）：http或stdio。
• VERBOSE（可选）：在索引和嵌入期间提供更详细的进度日志（true/1/yes/on）。
• INDEX_STORE_PATH（可选）：持久化JSON嵌入索引的路径（例如C:\repo\.mcp-index.json或/repo/.mcp-index.json）。启用快速热启动+增量重新索引（仅新/删除/大小变化的文件）。
• MODEL_NAME（可选）：覆盖默认嵌入模型（jinaai/jina-embeddings-v2-base-code）。示例：
  • MODEL_NAME=jinaai/jina-embeddings-v2-base-code（默认）——平衡多语言/代码嵌入模型；适合混合自然语言+源代码语义搜索。
  • MODEL_NAME=Xenova/bge-base-en-v1.5——高质量的英语通用文本嵌入（适用于文档/wiki风格的语料库）。
  • MODEL_NAME=Xenova/bge-small-en-v1.5——当延迟或内存比几个召回点更重要时，更快/更轻的英语模型。 任何与@xenova/transformers兼容的句子/特征提取模型都应该能工作。
• HOST（可选，HTTP模式）：绑定主机（默认127.0.0.1）。
• MCP_PORT（可选，HTTP模式）：TCP端口（默认3000）。
• ENABLE_DNS_REBINDING_PROTECTION（可选，HTTP模式）：默认为true；设置为false以禁用主机白名单检查。
• ALLOWED_HOSTS（可选，HTTP模式）：当启用DNS重新绑定保护时允许的主机列表。默认包括localhost和127.0.0.1，无论是否有端口。
• CHUNK_SIZE（可选）：嵌入前的最大字符数（默认800）。较大的值减少总嵌入（更快构建，更少内存）但可能模糊细粒度匹配。典型范围：
  • 700-900（平衡默认值）
  • 1000-1400（大散文/长函数；较少向量）
  • 400-600（细粒度代码导航；更多向量/内存）
• CHUNK_OVERLAP（可选）：传递到下一个分块的尾部字符数（默认120≈15%）。建议为CHUNK_SIZE的10-20%（例如，800大小的80-160）。如果观察到答案缺少跨边界上下文，请稍微增加（最多~20-25%）；为了加快构建速度，可以减少。

安全上限：CHUNK_SIZE限制为8000，CHUNK_OVERLAP限制为4000；如果重叠≥大小，则自动减少（记录）以保持向前进展。

持久性和增量重新索引

设置INDEX_STORE_PATH以启用持久化的JSON索引，存储分块+嵌入。启动时：

1. 如果文件存在且其元数据（模型名称、分块大小、重叠）匹配，则加载到内存中。
2. 重新扫描仓库；移除文件的分块被丢弃，新增或大小变化的文件被重新分块和重新嵌入。
3. 合并的索引被保存回（冷构建路径在配置时也持久化）。

优点：

• 大型仓库的热启动显著加快。
• 避免重新嵌入未更改的内容。

当前限制：

• 变更检测仅使用文件大小（保持相同大小的内容编辑尚未重新嵌入）。
• 嵌入生成是顺序的（尚无并行批处理）。
• 存储模式最小（版本1）；未来版本可能会添加哈希或mtime启发式。

通过删除存储文件或更改分块/模型参数来强制完全重建。

Visual Studio集成（MCP）

将example.mcp.json复制到：

• %USERPROFILE%.mcp.json（Windows），或
• 解决方案根目录作为.mcp.json（团队推荐）

调整“command”/“args”中的路径以及REPO_ROOT环境变量。

对于流式HTTP，使用如下配置条目：

{
	"servers": {
		"mcp-rag-server": {
			"type": "streamable-http",
			"url": "http://127.0.0.1:3000/mcp"
		}
	}
}

打开VS -> Copilot Chat -> 切换到Agent模式 -> 启用“mcp-rag-server”及其工具（首次使用时会被要求授权）。如果使用HTTP传输，请确保配置条目使用"type": "streamable-http"并且服务器已完成索引（检查/health）。

Agent模式使用

示例提示： "修改处理消息X的C#处理器。开始之前，请使用工具rag_query查询'message X schema'并考虑找到的合同。如果返回文件路径，请通过read_file读取它们。"

注意事项

• 首次运行将下载并缓存模型（数十到约100MB），并构建嵌入——这可能需要几分钟，具体取决于仓库大小。
• 日志写入stderr（console.error）以保持MCP stdout干净。
• 对于非常大的仓库，考虑添加一个ANN索引（hnswlib-node）或混合BM25+嵌入设置。

模型选择指导

根据您的仓库特性选择嵌入模型：

• jinaai/jina-embeddings-v2-base-code（默认）：当您的语料库包含有意义数量的源代码（多语言）与README/设计文档混合时使用。为代码符号+自然语言查询提供强大的跨域对齐。
• Xenova/bge-base-en-v1.5：当内容主要是英文自然语言（文档、知识库）且您想要稍强的纯文本语义质量时使用。
• Xenova/bge-small-en-v1.5：在受限机器上或当索引非常大的仓库且吞吐量重要时使用，以获得更快的启动/更低的内存。

随意实验——通过MODEL_NAME切换并重建嵌入缓存（如果外部持久化了现有缓存向量，请删除它们）。

分块大小指导

为什么是800/120？经验表明，这可以保持大多数自包含代码构造（函数/类）和短文档部分在一个分块中，同时提供足够的跨块语义匹配连续性。根据语料库调整：

• 主要是短函数或配置文件：较小的分块（500-700）有助于精确检索。
• 大叙事文档/设计规范：较大的分块（1000-1400）减少向量计数而不损失太多召回。
• 高度相互依赖的代码