Name: 文档检索服务
Author: trafflux

使用说明

RAGFlow MCP 服务器

作者：Philip Van de Walker | @trafflux | https://github.com/trafflux

一个模型上下文协议（MCP）服务器，为GitHub Copilot和其他MCP客户端提供访问RAGFlow文档检索功能的能力。

使用Docker Desktop进行本地测试

步骤1：本地构建

docker build -t ragflow-mcp-server:local .

生产部署（注册发布后）

# Add from Docker MCP Registry
docker mcp server add ragflow-mcp-server

通过Docker Desktop用户界面进行配置（设置 → MCP工具包 → RAGFlow MCP服务器）。

概述

这个MCP服务器使像GitHub Copilot这样的AI助手能够使用自然语言查询，在RAGFlow数据集中搜索并检索相关文档。它实现了MCP协议，以便与支持的客户端实现无缝集成。

特点/功能

文档检索使用自然语言查询跨RAGFlow数据集进行搜索
结构化结果返回包含文档块、元数据和分页信息的格式化JSON
符合MCP协议与MCP 2024-11-05规范完全兼容
生产就绪强大的错误处理、日志记录和异步操作
跨平台在Windows、Linux、macOS以及Docker环境中均可运行

快速入门

先决条件

Python 3.12+
访问一个正在运行的RAGFlow实例
RAGFlow API密钥

安装

安装依赖项：
```
uv sync
```

配置环境变量：

cp .env .env.local
# Edit .env.local with your RAGFlow API key and base URL

配置

设置以下环境变量：

RAGFLOW_API_KEY=your-api-key-here
RAGFLOW_BASE_URL=http://localhost:9380

运行服务器

服务器使用stdio传输方式以符合MCP规范：

# Using environment variables
python3 -m mcp_app

# Or with explicit CLI options
python3 -m mcp_app --ragflow-api-key your-key --ragflow-base-url http://localhost:9380

MCP客户端配置

GitHub Copilot（VS Code）- 基于Docker的设置

对于不需要单独运行服务器的容器化部署，请在您的VS Code MCP配置中添加以下内容。这种方法将MCP服务器作为每个请求的临时Docker容器来运行：

{
  "mcpServers": {
    "ragflow-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "RAGFLOW_API_KEY=ragflow-xxxxxxxxx",
        "-e",
        "RAGFLOW_BASE_URL=http://host.docker.internal:9380",
        "--add-host=host.docker.internal:host-gateway",
        "--network",
        "devnet",
        "ragflow-mcp-server:local"
      ]
    }
  }
}

环境变量

RAGFLOW_API_KEY您的RAGFlow API密钥（请替换 ragflow-xxxxxxxxx （使用你的实际密钥）
RAGFLOW_BASE_URL您的RAGFlow实例的URL（默认： http://host.docker.internal:9380 （用于本地Docker设置）

Docker 参数详解

--rm当容器退出时自动移除它
-i保持STDIN打开以进行交互式通信
--add-host=host.docker.internal:host-gateway将 `host.docker.internal` 映射到 Docker 主机（用于访问主机上的服务）
--network devnet连接到运行RAGFlow的指定Docker网络

先决条件

构建Docker镜像：

docker build -t ragflow-mcp-server:local .

确保RAGFlow可访问该容器需要通过配置的方式连接到您的RAGFlow实例 RAGFLOW_BASE_URL
网络配置确保 --network 参数与运行RAGFlow实例的Docker网络相匹配

GitHub Copilot（VS Code）- 直接Python设置

对于开发或者当不倾向于使用Docker时，可使用直接执行Python的方式：

{
  "mcpServers": {
    "ragflow": {
      "command": "python3",
      "args": ["-m", "mcp_app"],
      "cwd": "/path/to/ragflow-mcp-server",
      "env": {
        "RAGFLOW_API_KEY": "your-api-key",
        "RAGFLOW_BASE_URL": "http://localhost:9380"
      }
    }
  }
}

其他MCP客户端

该服务器支持标准的MCP stdio传输协议，并且可以与任何兼容MCP的客户端进行配置。

API 参考

ragflow_retrieval 工具

搜索RAGFlow数据集并检索相关文档。

参数：

question （字符串，必填）：搜索查询
dataset_ids （字符串数组，可选）：要搜索的特定数据集ID
document_ids （字符串数组，可选）：用于过滤的特定文档ID
page (整数，可选)：用于分页的页码（默认：1）
page_size （整数，可选）：每页结果数（默认：10）
similarity_threshold （浮点数，可选）：最小相似度分数（默认值：0.2）
vector_similarity_weight (float, 可选): 向量搜索与关键词搜索的权重（默认值：0.3）
keyword （布尔值，可选）：启用基于关键字的搜索（默认：false）
top_k （整数，可选）：考虑的最大候选数量（默认：1024）
rerank_id （字符串，可选）：重排序模型标识符
force_refresh (布尔值，可选)：强制刷新缓存的元数据（默认：false）

响应格式：

{
  "chunks": [
    {
      "id": "chunk-id",
      "content": "Document content...",
      "content_ltks": "processed content...",
      "dataset_id": "dataset-id",
      "document_id": "document-id",
      "document_keyword": "filename.md",
      "highlight": "highlighted <em>content</em>...",
      "important_keywords": ["keyword1", "keyword2"],
      "positions": [[1, 2, 3]],
      "similarity": 0.85,
      "term_similarity": 0.8,
      "vector_similarity": 0.9
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_chunks": 25,
    "total_pages": 3
  },
  "query_info": {
    "question": "your search query",
    "similarity_threshold": 0.2,
    "vector_weight": 0.3,
    "keyword_search": false,
    "dataset_count": 1
  }
}

建筑

MCP服务器由以下部分组成：

`mcp_app.py` 翻译成中文可以是“mcp 应用程序文件”或“mcp 应用脚本”。这里，“mcp”可能代表某个特定的模块、项目或系统名称，而“.py”表示这是一个Python脚本文件主要MCP服务器实现，包含工具定义和请求处理
RAGFlow连接器用于与RAGFlow API通信的异步HTTP客户端
MCP协议层处理MCP协议消息和工具执行

技术实施

异步事件循环管理

重要的这个服务器在FastMCP管理的事件循环中使用了aiohttp会话的惰性初始化。这对于兼容性至关重要：

❌ 别在之前预初始化 aiohttp 会话 FastMCP.run() （创建了错误的事件循环）
✅ 做使用 _ensure_connector_initialized() 在首次调用工具时进行初始化（使用正确的事件循环）

为什么这很重要aiohttp 的超时上下文管理器必须在工具执行的同一个事件循环中创建。在不同的循环中初始化会导致：

RuntimeError: Timeout context manager should be used inside a task

看 `TIMEOUT_FIX_FINAL.md` 翻译成中文为：“最终超时修复方案.md” 以获取详细的技术说明。

连接池

最大连接数总共100个，每个主机10个
**DNS TTL（Time To Live，生存时间）**300秒
会话重用在工具调用之间连接被池化并重复使用
清理服务器关闭时自动（执行/触发）

缓存策略

数据集缓存LRU（最近最少使用）缓存，最大条目数32，TTL（生存时间）300秒
缓存文件最大128项的LRU缓存，TTL（生存时间）为300秒
缓存键数据集/文档ID + 参数

发展

项目结构

ragflow-mcp-server/
├── mcp_app.py              # Main MCP server (FastMCP)
├── pyproject.toml          # Python project configuration
├── uv.lock                 # Dependency lock file
├── Dockerfile              # Docker container configuration
├── docker-entrypoint.sh    # Docker entrypoint script
├── tools.json              # MCP tool definitions
├── .env                    # Environment variables (example)
├── README.md               # This documentation
└── IMPLEMENTATION.md       # Technical implementation details

测试

运行MCP服务器，并使用MCP客户端工具进行测试：

# Test with MCP inspector
npx @modelcontextprotocol/inspector python3 -m mcp_app

# Or test directly with environment variables set
RAGFLOW_API_KEY=your-key RAGFLOW_BASE_URL=http://localhost:9380 \
npx @modelcontextprotocol/inspector python3 -m mcp_app

Docker 部署

构建形象

构建Docker镜像以供本地使用或部署：

# Build with local tag
docker build -t ragflow-mcp-server:local .

# Or build with a specific version tag
docker build -t ragflow-mcp-server:v1.0.0 .

Docker 的环境变量

在运行容器时，配置这些环境变量：

# Required: RAGFlow API credentials
RAGFLOW_API_KEY=your-ragflow-api-key-here
RAGFLOW_BASE_URL=http://host.docker.internal:9380

# Optional: Logging and debugging
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

作为独立容器运行

用于测试或开发：

docker run -i --rm \
  -e RAGFLOW_API_KEY=ragflow-xxxxxxxxx \
  -e RAGFLOW_BASE_URL=http://host.docker.internal:9380 \
  --add-host=host.docker.internal:host-gateway \
  --network devnet \
  ragflow-mcp-server:local

生产部署

对于生产使用，请考虑：

# Run with resource limits
docker run -d \
  --name ragflow-mcp-server \
  --restart unless-stopped \
  --memory 512m \
  --cpus 0.5 \
  -e RAGFLOW_API_KEY=ragflow-xxxxxxxxx \
  -e RAGFLOW_BASE_URL=http://your-ragflow-host:9380 \
  ragflow-mcp-server:local

Docker Compose 集成

添加到您的 docker-compose.yml：

services:
  ragflow-mcp:
    build: .
    environment:
      - RAGFLOW_API_KEY=ragflow-xxxxxxxxx
      - RAGFLOW_BASE_URL=http://ragflow:9380
    networks:
      - ragflow-network
    depends_on:
      - ragflow

故障排除

常见问题

**“未找到工具”**确保MCP服务器正在运行，并且在您的客户端中已正确配置
**“连接失败”**在环境变量中检查RAGFlow API密钥和基础URL
**“无结果”**验证数据集存在且包含可搜索内容
**“超时”**增加超时值或检查RAGFlow服务器性能

日志

服务器提供了详细的日志记录。请检查您的MCP客户端日志中的错误信息并进行设置 LOG_LEVEL=DEBUG 用于详细输出。

做出贡献

为RAGFlow MCP服务器做出贡献

为仓库创建分支（或：克隆仓库）
创建一个特性分支
进行你的更改
如适用，请添加测试
提交拉取请求

为Docker MCP Registry做贡献

这台服务器设计为可列入官方Docker MCP注册表将此服务器添加到注册表中：

审查/回顾 Docker MCP Registry 贡献指南
这个存储库包含一个符合规范的（内容/文件/程序等，具体根据上下文确定） server.yaml 可提交的文件
这个（或“该”） tools.json 该文件为注册表提供工具元数据
向 Docker MCP 注册表提交一个包含服务器元数据的拉取请求

如需更多详情，请参阅 Docker MCP 工具包文档.

许可证

这个项目是RAGFlow生态系统的一部分，采用Apache License 2.0许可证。 │ RAGFlow 后端服务 │ │ 端口 9380 │ (REST API) └────────────────────────────┘


## Installation

### Option 1: Docker Container (Recommended)

Build and run the MCP server in a Docker container:

```bash
# Build the image
docker build -t ragflow-mcp-server:local .

# Run with environment variables
docker run -i --rm \
  -e RAGFLOW_API_KEY=your-api-key \
  -e RAGFLOW_BASE_URL=http://host.docker.internal:9380 \
  --add-host=host.docker.internal:host-gateway \
  --network devnet \
  ragflow-mcp-server:local

选项2：直接安装Python

使用Python直接安装并运行：

# Install dependencies
uv sync

# Set environment variables
export RAGFLOW_API_KEY=your-api-key
export RAGFLOW_BASE_URL=http://localhost:9380

# Run the server
python3 -m mcp_app

配置

环境变量

# Required: RAGFlow API credentials
RAGFLOW_API_KEY=your-ragflow-api-key-here
RAGFLOW_BASE_URL=http://localhost:9380

# Optional: Logging level
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

Docker Compose

对于容器化部署，请在您的（项目/配置中）添加 docker-compose.yml：

services:
  ragflow-mcp:
    build: .
    environment:
      - RAGFLOW_API_KEY=your-api-key
      - RAGFLOW_BASE_URL=http://ragflow:9380
    networks:
      - ragflow-network
    depends_on:
      - ragflow

VS Code Copilot 配置

更新您的VS Code MCP设置以包含RAGFlow服务器：

对于基于Docker的设置：

{
  "mcpServers": {
    "ragflow-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "RAGFLOW_API_KEY=your-api-key",
        "-e",
        "RAGFLOW_BASE_URL=http://host.docker.internal:9380",
        "--add-host=host.docker.internal:host-gateway",
        "--network",
        "devnet",
        "ragflow-mcp-server:local"
      ]
    }
  }
}

对于直接安装Python：

{
  "mcpServers": {
    "ragflow": {
      "command": "python3",
      "args": ["-m", "mcp_app"],
      "cwd": "/path/to/ragflow-mcp-server",
      "env": {
        "RAGFLOW_API_KEY": "your-api-key",
        "RAGFLOW_BASE_URL": "http://localhost:9380"
      }
    }
  }
}

重要提示： 更新配置后：

保存文件
完全关闭 VS Code
重新打开 VS Code
现在，Copilot 应该会显示可用的 RAGFlow 工具

测试

使用MCP检查器

使用官方的MCP检查器测试服务器：

# Install MCP inspector if not already installed
npm install -g @modelcontextprotocol/inspector

# Test with environment variables
RAGFLOW_API_KEY=your-key RAGFLOW_BASE_URL=http://localhost:9380 \
mcp-inspector python3 -m mcp_app

手动测试

你也可以通过管道传递JSON-RPC消息来手动测试服务器：

# Initialize the server
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | \
RAGFLOW_API_KEY=your-key RAGFLOW_BASE_URL=http://localhost:9380 \
python3 -m mcp_app

# List available tools
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | \
RAGFLOW_API_KEY=your-key RAGFLOW_BASE_URL=http://localhost:9380 \
python3 -m mcp_app

集成测试

对于使用实际RAGFlow数据进行集成测试：

# Set your actual environment variables
export RAGFLOW_API_KEY="your-actual-api-key"
export RAGFLOW_BASE_URL="http://your-ragflow-host:9380"

# Test a retrieval query
echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "ragflow_retrieval",
    "arguments": {
      "question": "What is RAGFlow?",
      "page_size": 5
    }
  }
}' | python3 -m mcp_app

response = requests.post( "http://localhost:9382/mcp/" 翻译成中文可以是：“http://本地主机:9382/mcp/”。不过，通常在中文语境下，我们不会直接翻译URL中的“localhost”为具体的中文（因为“localhost”在技术上就是指本地计算机），所以更自然的表述可能是直接保留原样，或者稍作解释说明，如“http://本机:9382/mcp/（指向本地计算机的9382端口）”。但根据简洁性原则，直接翻译为“http://本地主机:9382/mcp/”也是可以接受的， headers=headers,， json = request，（这句在中文中可以理解为“将json变量赋值为request”，但具体含义需结合上下文，因为“request”在编程中通常表示请求对象）， )

打印响应状态码：`print(response.status_code)` # 输出 202 打印(response.text) # 包含工具列表的SSE流


## Available Tools

### ragflow_retrieval

Search RAGFlow datasets and retrieve relevant documents.

**Parameters:**

- `question` (string, required): The search query
- `dataset_ids` (array, optional): Specific datasets to search
- `document_ids` (array, optional): Specific documents to search within
- `page` (integer, default: 1): Results page number
- `page_size` (integer, default: 10, max: 100): Results per page
- `similarity_threshold` (number, default: 0.2): Minimum match similarity
- `vector_similarity_weight` (number, default: 0.3): Vector vs keyword weight
- `keyword` (boolean, default: false): Enable keyword search
- `top_k` (integer, default: 1024): Candidate pool size
- `rerank_id` (string, optional): Reranking model
- `force_refresh` (boolean, default: false): Skip cache

**Example Response:**

搜索结果：

RAGFlow是一个先进的文档分析平台。。。来源：文档/概述.md 相关性：0.95
它支持包括PDF在内的多种文档格式。。。来源：文档/features.md 相关性：0.87


## Troubleshooting

### Copilot can't find the server

1. **Verify server is running:**
   ```bash
   curl http://localhost:9382/health

检查防火墙： Windows 防火墙可能会阻止端口 9382。请在 Windows Defender 中允许该端口。
检查配置：
- 验证 mcp.json 具有带尾斜杠的正确URL： /mcp/
- 验证Bearer令牌是否完全匹配
- 修改后关闭并重新打开 VS Code

检查日志：

docker logs ragflow-server | grep -i mcp

连接超时

确保RAGFlow后端正在运行且可访问
检查 MCP_BASE_URL 设置
验证API密钥是否有效

错误的响应格式

如果直接获取JSON而不是SSE流：

确保 json_response=False 在服务器代码中
容器可能正在使用旧镜像；请重新构建： docker-compose build --no-cache ragflow

性能调优

适用于高负载

environment:
  - MCP_MODE=http
  - MCP_HOST=0.0.0.0  # Don't restrict to localhost
  - MCP_PORT=9382

用于生产

运行在反向代理（nginx）之后
使用适当的SSL/TLS证书
建立监控和警报系统
在Docker中配置资源限制

发展

添加新工具

编辑 mcp_app.py 并添加到 list_tools() 处理程序：

@self.mcp_server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        # ... existing tools
        Tool(
            name="my_tool",
            description="Tool description",
            inputSchema={ ... }
        )
    ]

然后进行处理 call_tool()：

@self.mcp_server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "my_tool":
        # Implement tool logic
        pass

从源代码构建

# Install in development mode
uv sync

# Run tests (if available)
python -m pytest

# Run the server
python3 -m mcp_app

从旧服务器迁移

新服务器是 完全向后兼容 但要求：

更新 docker-compose.yml （命令部分已删除）
确保环境变量已设置
重启容器： docker-compose restart
重新加载 VS Code

支持与问题

MCP规范：https://spec.modelcontextprotocol.io/
RAGFlow: https://github.com/infiniflow/ragflow（可译为：“RAGFlow项目地址：https://github.com/infiniflow/ragflow”）
GitHub 问题：[在此报告问题]

许可证

与RAGFlow（Apache 2.0）相同

版本： 2.0.0
协议： MCP 2024年11月5日
最后更新时间： 2025年10月

使用说明

RAGFlow MCP 服务器

使用Docker Desktop进行本地测试

生产部署（注册发布后）

概述

特点/功能

快速入门

先决条件

安装

配置

运行服务器

MCP客户端配置

GitHub Copilot（VS Code）- 基于Docker的设置

环境变量

Docker 参数详解

先决条件

GitHub Copilot（VS Code）- 直接Python设置

其他MCP客户端

API 参考

ragflow_retrieval 工具

建筑

技术实施

异步事件循环管理

连接池

缓存策略

发展

项目结构

测试

Docker 部署

构建形象

Docker 的环境变量

作为独立容器运行

生产部署

Docker Compose 集成

故障排除

常见问题

日志

做出贡献

为RAGFlow MCP服务器做出贡献

为Docker MCP Registry做贡献

许可证

选项2：直接安装Python

配置

环境变量

Docker Compose

VS Code Copilot 配置

测试

使用MCP检查器

手动测试

集成测试

连接超时

错误的响应格式

性能调优

适用于高负载

用于生产

发展

添加新工具

从源代码构建

从旧服务器迁移

支持与问题

许可证

相关 MCP

实时文档检索服务

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

Flomo笔记服务

AI开发助手

必应中文搜索MCP服务器