@sylphlab/tools-rag-mcp

通过模型上下文协议（MCP）远程构建和查询检索增强生成（RAG）索引。

此包提供了一个可运行的MCP服务器，该服务器基于@sylphlab/tools-rag中定义的工具，提供了RAG功能（内容索引、查询索引、检查状态）。

目的

此服务器允许MCP客户端（如AI代理、研究工具或知识管理系统）远程管理和查询用于RAG工作流程的向量索引。它充当一个安全接口，从@sylphlab/tools-rag获取核心RAG逻辑，使用@sylphlab/tools-adaptor-mcp进行适配，并通过MCP标准（stdio）提供服务。这使得客户端可以利用强大的RAG能力，而无需直接访问向量数据库、嵌入模型或复杂的解析逻辑。

功能

• MCP服务器： 实现了工具执行的模型上下文协议。
• 暴露RAG工具： 提供以下工具：
  • 内容索引（indexContentTool）：加载、解析、分块、嵌入并存储文档到向量索引中。
  • 查询索引（queryIndexTool）：根据查询检索相关文档片段。
  • 检查索引状态（indexStatusTool）：获取关于索引的元数据。
• 配置： 可能使用环境变量（通过dotenv）来配置向量数据库连接（ChromaDB、Pinecone）、嵌入模型端点/ API密钥等。
• 可执行文件： 提供一个二进制文件（mcp-rag-server），便于执行。
• 安全性： 在定义的工作目录内操作，并依赖于配置的凭据来访问外部服务。

安装与配置

此包旨在作为独立服务器使用，并需要通过环境变量进行配置。

1. 配置：

在您将要运行服务器的目录中创建一个.env文件（或通过部署方法配置环境变量）。关键变量可能包括：

# 示例 .env 配置

# 选择向量数据库：'chromadb' 或 'pinecone'
VECTOR_DB_PROVIDER=chromadb
# 如果使用 ChromaDB
CHROMA_DB_URL=http://localhost:8000

# 如果使用 Pinecone
# PINECONE_API_KEY=your_pinecone_api_key
# PINECONE_ENVIRONMENT=your_pinecone_environment

# 嵌入模型配置
# 使用 Ollama 的示例（通过核心中的 ollama-ai-provider）
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434 # 可选，默认本地

# 使用 OpenAI 的示例（通过核心中的 'ai' 包）
# EMBEDDING_PROVIDER=openai
# OPENAI_API_KEY=your_openai_api_key
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small

(参考@sylphlab/tools-rag文档以获取特定于所选向量数据库和嵌入提供商的具体所需环境变量。)

2. 安装：

使用 npm/pnpm/yarn（推荐）

全局安装或在项目中安装：

# 全局安装
npm install -g @sylphlab/tools-rag-mcp
# 或在项目中安装
pnpm add @sylphlab/tools-rag-mcp

配置您的MCP主机（例如mcp_settings.json），确保它可以访问.env文件（通常通过设置cwd）：

// 使用 npx
{
  "mcpServers": {
    "rag-mcp": {
      "command": "npx",
      "args": ["@sylphlab/tools-rag-mcp"],
      "name": "RAG 工具 (npx)",
      "cwd": "/包含/.env/和数据的路径" // 设置 CWD
    }
  }
}

// 或使用全局安装路径
{
  "mcpServers": {
    "rag-mcp": {
      "command": "mcp-rag-server", // 如果在 PATH 中
      "name": "RAG 工具 (全局)",
      12 "cwd": "/包含/.env/和数据的路径" // 设置 CWD
    }
  }
}

使用 Docker（如果可用）

(需要发布 Docker 镜像 sylphlab/tools-rag-mcp:latest)

docker pull sylphlab/tools-rag-mcp:latest

配置您的MCP主机，挂载项目目录并传递环境文件：

{
  "mcpServers": {
    "rag-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i", "--rm",
        "--env-file", "/你的/.env/路径", // 传递环境变量
        "-v", "/你的/项目路径:/app", // 挂载项目数据
        "-w", "/app", // 设置工作目录
        "sylphlab/tools-rag-mcp:latest"
      ],
      "name": "RAG 工具 (Docker)"
    }
  }
}

本地构建（用于开发）

1. 配置： 在packages/tools-rag-mcp中创建.env文件。
2. 构建： 从单体仓库根目录：pnpm build --filter @sylphlab/tools-rag-mcp
3. 配置 MCP 主机：

   {
     "mcpServers": {
       "rag-mcp": {
         "command": "node",
         "args": ["./packages/tools-rag-mcp/dist/index.js"],
         "name": "RAG 工具 (本地构建)",
         "cwd": "./packages/tools-rag-mcp" // 包含 .env 的目录
       }
     }
   }
   

使用

一旦服务器正确配置并通过MCP连接，客户端就可以索引内容并执行查询。

MCP 请求示例（索引内容）：

{
  "tool_name": "indexContentTool",
  "arguments": {
    "indexName": "项目文档索引",
    "contentPaths": ["./docs/**/*.md"], // 索引 Markdown 文件
    // 配置参数可能可选，如果完全从 .env 读取
    // "vectorDbConfig": { "provider": "chromadb", "url": "http://localhost:8000" },
    // "embeddingModelConfig": { "provider": "ollama", "model": "nomic-embed-text" }
  }
}

MCP 请求示例（查询索引）：

{
  "tool_name": "queryIndexTool",
  "arguments": {
    "indexName": "项目文档索引",
    "query": "如何配置 RAG 服务器？",
    "topK": 3
    // 配置参数可能可选
  }
}

预期响应片段（查询）：

{
  "result": {
    "success": true,
    "results": [
      { "id": "...", "score": 0.85, "text": "..." },
      { "id": "...", "score":  0.82, "text": "..." },
      { "id": "...", "score": 0.79, "text": "..." }
    ]
  }
}

依赖项

• @modelcontextprotocol/sdk：用于创建MCP服务器实例。
• @sylphlab/tools-adaptor-mcp：用于适配核心工具定义。
• @sylphlab/tools-rag：包含核心RAG逻辑（解析、分块、嵌入、向量存储交互）。
• @sylphlab/tools-core：提供基本工具定义结构。
• dotenv：用于从.env文件加载环境变量。

---

由Sylph Lab开发。