ragflow-knowledge-mcp-server

ragflow-knowledge-mcp-server

项目概述：

一个用于 RAGFlow 知识库的简单 MCP 服务。

本项目是一个基于 Python 的 RAGFlow 知识库 MCP（Model Context Protocol）服务。 它提供了一组与 RAGFlow 交互的工具，允许用户搜索知识、列出可用的知识库，并获取特定知识库的信息。 该服务使用 mcp 库构建，可配置使用 stdio 或 sse 作为传输方式。 该服务通过 YAML 文件（config.yaml）和环境变量进行配置。

支持的 RAGFlow 版本： 0.17.2 ~ 0.19.0

另请参阅 infiniflow/ragflow/blob/main/mcp/server/server.py

1. 可用工具

1. 动态知识库搜索工具

在 config.yaml 中启用动态知识库搜索工具，另请参阅服务配置：

datasets:
  - dataset-id: 00000000000000000000000000000000
    search-tool-name: search_xxx_knowledge
    #search-tool-description: "Search knowledge about XXX(中文说明)."
    #search-tool-result: simple
    search-tool-description: "Search knowledge about XXX(中文说明). Results in JSON format, knowledge in the 'content' property."
    search-tool-result: json

2. list_knowledge_bases（默认禁用）

在 config.yaml 中启用 list_knowledge_bases 工具：

list-bases-enabled: true

• 默认描述： 列出知识库。

• 输入属性：

  • page，str：要列出知识库的页码，可选，默认为 1。
  • limit，str：要列出的知识库数量上限，可选，默认为 20。
  • timeout，int：动态超时参数，由 timeout-param-enabled 启用，可选，默认为 60 秒。

3. get_knowledge_base_info（默认禁用）

在 config.yaml 中启用 get_knowledge_base_info 工具：

get-base-enabled: true

• 默认描述： 获取指定知识库 ID 的信息，结果包括知识库名称、描述及其他信息。

• 输入属性：

  • knowledge_base_id，str：要查询的知识库 ID。
  • timeout，int：动态超时参数，由 timeout-param-enabled 启用，可选，默认为 60 秒。

2. 安装和运行

2.1. 使用 pip 安装

# Uninstall the previous version
pip uninstall --yes ragflow-knowledge-mcp-server

pip install ragflow-knowledge-mcp-server --upgrade --force-reinstall --extra-index-url http://127.0.0.1:8081/repository/pypi-group/simple --trusted-host 127.0.0.1

2.2. 从源代码安装

cd /path/to/project

pip install .

# Or install using pytools.sh
./pytools.sh reinstall-system

2.3. 运行

export SIMP_LOGGER_LOG_FILE=/path/to/mcp.log
export SIMP_LOGGER_LOG_LEVEL=DEBUG

# This server can be run directly from the command line:
ragflow-knowledge-mcp-server --config=/path/to/config.yaml

# Alternatively, it can be run as a Python module:
python -m ragflow_knowledge_mcp_server --config=/path/to/config.yaml

# This server can also be run using `uv`:
uv run ragflow-knowledge-mcp-server --config=/path/to/config.yaml

2.4. 使用 Docker 或 Docker Compose 运行

1. Docker

   • 导出 EXTRA_INDEX_URL 环境变量，然后运行 docker/0.1.0/build.sh 构建镜像，可按需修改构建脚本或手动构建。
   • 然后参考 docker/0.1.0/run-in-docker.sh 运行容器。

2. Docker Compose

   • 修改 .env 文件。
   • 修改 config.yaml 文件。
   • 运行 docker/0.1.0/docker-compose-up-d.sh 启动容器，可按需修改启动脚本或手动运行。

2.4. 测试

# The project uses `pytest` for testing. To run the tests, first install the test dependencies:
python -m venv .venv
. .venv/bin/activate
uv sync --no-install-project --extra test

# Then run pytest:
pytest

3. 服务配置

• YAML：

配置示例 yaml，完整配置请参阅 MCPServerProperties.py：

server-name: ragflow-knowledge-base

default-base-url: http://127.0.0.1:9388/api/v1
default-api-key: ragflow-00000000000000000000000000000000

timeout: 60
timeout-param-enabled: false

# SSE
transport: sse # Defaults to stdio
sse-port: 41106

list-bases-enabled: false
get-base-enabled: false

datasets:
  - dataset-id: 00000000000000000000000000000000
    search-tool-name: search_xxx_knowledge
    search-tool-description: "Search knowledge about XXX(中文说明). Results in JSON format, knowledge in the 'content' property."

  - enabled: false
    id-param-enabled: true
    search-tool-name: search_knowledge
    search-tool-description: "Search knowledge from specified knowledge base('knowledge_base_id')."

也可以为每个数据集和工具配置基础 URL 和 API 密钥：

server-name: ragflow-knowledge-base

timeout: 60
timeout-param-enabled: false

# SSE
transport: sse # Defaults to stdio
sse-port: 41106

list-bases-enabled: false
list-bases-base-url: http://127.0.0.1:9388/api/v1
list-bases-api-key: ragflow-00000000000000000000000000000000

get-base-enabled: false

datasets:
  - dataset-id: 00000000000000000000000000000000
    base-url: http://127.0.0.1:9388/api/v1
    api-key: ragflow-00000000000000000000000000000000
    # Other properties...

• 可用环境变量： | Yaml | 环境变量名称 | 默认值 | 描述 | |-----------------------------|----------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| | | RAGFLOW_KNOWLEDGE_MCP_SERVER_CONFIG | config.yaml | 配置文件路径，也可通过 CLI 选项 --config=/path/to/config.yaml 指定。 | | default-base-url | DEFAULT_RAGFLOW_KNOWLEDGE_BASE_URL | - | 知识库的默认基础 URL。 | | default-api-key | DEFAULT_RAGFLOW_KNOWLEDGE_API_KEY | - | 知识库的默认 API 密钥。 | | server-name | RAGFLOW_KNOWLEDGE_MCP_SERVER_NAME | RAGFlow Knowledge Base | MCP 服务的名称。 | | transport | RAGFLOW_KNOWLEDGE_MCP_SERVER_TRANSPORT | stdio | 传输类型。可以是 stdio 或 sse。 | | sse-transport-endpoint | RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_TRANSPORT_ENDPOINT | /messages/ | SSE 传输端点。 | | sse-bind-host | RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_BIND_HOST | 0.0.0.0 | SSE 传输绑定的主机。 | | sse-port | RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_PORT | 41106 | SSE 传输使用的端口。 | | sse-debug-enabled | RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_DEBUG_ENABLED | False | 是否启用 SSE 调试模式。 | | timeout | RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT | 60 | 服务的超时时间。 | | timeout-param-enabled | RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_ENABLED | False | 是否启用超时参数。 | | timeout-param-description | RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_DESCRIPTION | The total timeout for one calling, in seconds, optional, defaults to {self.timeout} seconds. | 超时参数的描述。 |

• simp-logger 的可用环境变量： | 变量名 | 默认值 | 描述 | |-------------------------------------|-----------------------------------------------------------|----------------------------------------------------| | SIMP_LOGGER_LOG_FILE_ENABLED | True | 是否启用写入文件的日志记录。 | | SIMP_LOGGER_LOG_CONSOLE_ENABLED | True | 是否启用写入控制台的日志记录。 | | SIMP_LOGGER_LOG_LEVEL | INFO | 日志级别。 | | SIMP_LOGGER_LOG_FILE | ~/logs/simp-logger.log | 日志文件路径。 | | SIMP_LOGGER_LOG_PATTERN | %(asctime)s %(levelname)s [%(threadName)s]: %(message)s | 日志格式。 | | SIMP_LOGGER_LOG_MAX_BYTES | 10485760 (10MB) | 日志文件的最大大小。 | | SIMP_LOGGER_LOG_BACKUP_COUNT | 5 | 要保留的备份文件数量。 | | SIMP_LOGGER_LOG_ROTATION_TYPE | size | 日志轮转类型。可以是 size 或 time。 | | SIMP_LOGGER_LOG_ROTATION_WHEN | midnight | 日志文件轮转的时间。 | | SIMP_LOGGER_LOG_ROTATION_INTERVAL | 1 | 日志轮转间隔。 | | SIMP_LOGGER_LOG_CLEANUP_DISABLED | False | 是否禁用日志清理。 |

4. MCP 配置

4.1. SSE

示例端点：http://127.0.0.1:41106/sse

4.2. stdio

简单命令行：

uv run ragflow-knowledge-mcp-server --config=/path/to/config.yaml

JSON：

{
  "ragflow-knowledge-base": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "ragflow-knowledge-mcp-server",
      "--config=/path/to/config.yaml"
    ],
    "env": {
      "SIMP_LOGGER_LOG_CONSOLE_ENABLED": false,
      "SIMP_LOGGER_LOG_FILE": "/path/to/mcp.log",
      "SIMP_LOGGER_LOG_LEVEL": "DEBUG"
    }
  }
}

YAML：

ragflow-knowledge-base:
  type: stdio
  command: uv
  args:
    - run
    - ragflow-knowledge-mcp-server
    - "--config=/path/to/config.yaml"
  env:
    SIMP_LOGGER_LOG_CONSOLE_ENABLED: false
    SIMP_LOGGER_LOG_FILE: /path/to/mcp.log
    SIMP_LOGGER_LOG_LEVEL: DEBUG

5. 开发规范

• 项目遵循标准的 Python 打包规范。
• 代码按模块组织在 src/ragflow_knowledge_mcp_server 目录中。
• 服务端逻辑位于 server.py，配置属性定义在 properties/MCPServerProperties.py 中，与 RAGFlow API 交互的服务位于 service 目录中。
• 项目使用 setuptools 进行构建，并使用 setuptools_scm 进行版本管理。
• 项目使用 simp-logger 进行日志记录，可通过环境变量进行配置。