SuperNova MCP RAG Monorepo
一个展示模型上下文协议（MCP）服务器和检索增强生成（RAG）的monorepo，用于回答有关虚构SuperNova文档的问题。
- 文档是虚构的产品文档。它是一组包含AI生成内容的HTML文件。
- 文档被处理成块并存储在矢量数据库中。
- 该服务器使用Node.js构建，并使用免费的HuggingFace嵌入进行语义搜索。
随附博客文章： 构建MCP RAG服务器：通过上下文文档搜索增强开发人员工具
架构概述
flowchart TD
User[User Question in Cursor] -->|MCP Protocol| MCPServer[MCP RAG Server]
MCPServer -->|Triggers| RAG[RAG Pipeline]
RAG -->|Loads & Chunks| Docs[SuperNova HTML Docs]
RAG -->|Embeds| Embeddings[HuggingFace Embeddings]
Embeddings -->|Stores| VectorStore[In-Memory Vector Store]
MCPServer -->|Semantic Search| VectorStore
VectorStore -->|Relevant Chunks| MCPServer
MCPServer -->|Answer| UserMonorepo结构
mcp-rag-server/--带RAG管道的MCP服务器（Node.js、TypeScript）monorepo-sample-package/--示例包（用于monorepo演示）docs/--SuperNovaStorybook Mobile Swift的虚拟HTML文档
快速开始
先决条件
- Node.js 18+
- Yarn（用于工作空间支持）
再进行
yarn install环境设置
创建一个 .env 文件在 mcp-rag-server/:
HUGGINGFACE_API_KEY=your_huggingface_token_here构建并运行MCP RAG服务器
#install
yarn install
#list workspace
yarn workspaces info
# Build
yarn workspace mcp-rag-server build
# Start
yarn workspace mcp-rag-server start- 对于开发（热重新加载）：
yarn dev注意：服务器可能需要一段时间来准备向量存储。您可以在日志中看到进度。
运作原理
- MCP协议： 暴露工具(
search_docs)用于文档的语义搜索。 - RAG管道：
- 加载并解析 docs/SuperNovaStorybook-Mobile-Swift/*.html，即该目录中的所有HTML文件。 - 将文本分割成块 - 使用HuggingFace推理API嵌入块 - 存储在内存向量存储（LangChain）中 - 通过语义相似度搜索回答查询
使用游标
- 打开的游标
- 在设置中添加新的MCP服务器→ MCP:
- 类型：MCP（标准） - 命令： node （从 mcp-rag-server) - 论据： /absolute-path-to/supernova-mcp-rag/mcp-rag-server/dist/index.js - 确保 .env 是用您的HuggingFace API密钥设置的
- 在Cursor聊天中询问有关SuperNova文档的问题
mcp.json示例
{
"mcpServers": {
"mcp-rag-server": {
"command": "node",
"args": [
"/absolute-path-to/supernova-mcp-rag/mcp-rag-server/dist/index.js"
],
"disabled": false,
"autoApprove": []
}
}
}
使用MCP检查器和简单浏览器进行调试
这 MCP检查员 是一个交互式开发工具，旨在帮助您实时测试和调试MCP服务器。
如何使用MCP检查器
- 在本地启动MCP服务器。
- 从monorepo的根目录使用服务器运行Inspector：
npx @modelcontextprotocol/inspector node mcp-rag-server/dist/index.js- 打开检查器Web UI：
检查器将打印一个URL，例如： http://127.0.0.1:6274/
- 在VS Code Simple Browser或任何web浏览器中打开此URL：
- 在光标/VS代码中，打开命令面板(
Ctrl+Shift+P或Cmd+Shift+P)，类型Simple Browser: Show，并输入URL。 - 或者，在Chrome、Firefox或任何浏览器中打开URL。
- 与您的MCP服务器交互：
- 发送测试查询。
- 检查工具调用和响应。
- 实时调试和验证MCP服务器的行为。
为什么要使用简单浏览器？
- 某些浏览器（如Safari）可能会因仅HTTPS模式而阻止HTTP请求。
- VS Code的简单浏览器避免了这些限制，便于本地开发。
在将MCP检查器与Cursor等客户端完全集成之前，将其与Simple Browser一起使用是调试和验证MCP服务器的一种强大方法。
______________________________________________________________________
故障排除
- 确保您的HuggingFace API密钥有效且不受费率限制
- 如果服务器无法启动，请检查
.env和日志 - 对于依赖性问题，请使用
yarn install从根开始
性能考虑因素和限制
当前的实施方式是如何运作的
- 文档文件夹（和子文件夹）中的所有HTML文件都是递归发现和处理的。
- 解析每个HTML文件，提取其文本，然后将其拆分为重叠的块进行语义搜索。
- 每个区块的嵌入都是使用拥抱面部推断API生成的。
- 所有嵌入都存储在内存中的向量存储中，以便在查询过程中快速检索。
性能选择
- 内存矢量存储：
适用于中小型文档集，无外部依赖，但由于内存限制，不适合非常大的语料库。
- 动态嵌入：
在服务器启动时为所有块生成嵌入。这使得初始启动速度变慢，但确保了所有内容都是可搜索的。
- 顺序处理：
为了简单和可靠，文件和嵌入被一个接一个地处理。
局限性
- 启动时间：
随着文档集的增长，服务器将需要更长的时间来启动，因为在提供查询之前，必须处理和嵌入所有文件。
- 拥抱面API速率限制：
嵌入许多区块可以快速达到自由层API费率限制（请参阅拥抱面API定价和限制）。如果超出配额，您可能会遇到延迟或错误。
- 内存使用情况：
内存中的向量存储不适合大型文档集或生产规模的部署。
- 无持久索引：
每次服务器重启时，矢量存储都会从头开始重建；没有缓存或持久索引。
- 单线程处理：
当前所有处理都是按顺序进行的。对于大量文件，并行或批处理可以提高性能，但需要小心处理API限制和错误情况。
拥抱脸API使用和限制
- 拥抱面部推理API有一个有请求限制的免费层（例如，注册用户每小时300个请求）。
- 看 API定价和费率限制 和 支持的型号 了解详情。
- 如果超出配额，您可能会收到429个错误，或者必须等待配额重置。
可能的改进
- 批量或并行嵌入：
在支持的情况下，批处理嵌入请求或并行处理文件可以加快初始化速度。
- 持久或外部矢量数据库：
对于大规模或生产使用，考虑使用langchain的向量存储接口将嵌入存储在持久向量数据库中，如Pinecone、Weaviate或Qdrant。
- 预处理步骤：
将嵌入和索引过程移至单独的构建步骤，以避免服务器启动时间过长。
- 流初始化：
在向量存储的部分准备就绪后立即提供查询，而不是等待所有文件都被处理。
- 您还可以利用langchain的api来拥有自己的llm管道。这样，您就可以使用任何您想要的llm，并可以控制响应温度、最大令牌等。
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。