ragflow-knowledge-mcp-server

Project Overview:

A simple MCP server of knowledge base for RAGFlow.

This project is a Python-based MCP (Model Context Protocol) server for RAGFlow knowledge bases. It provides a set of tools to interact with RAGFlow, allowing users to search for knowledge, list available knowledge bases, and retrieve information about specific knowledge bases. The server is built using the mcp library and can be configured to use either stdio or sse for transport. The server is configured through a YAML file (config.yaml) and environment variables.

Supported RAGFlow versions: 0.17.2 ~ 0.19.0

See also infiniflow/ragflow/blob/main/mcp/server/server.py

1. Available tools

1. Dynamic knowledge base searching tools

Enable dynamic knowledge base searching tools in config.yaml, see also Server configurations:

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 (default disabled)

Enable list_knowledge_bases tool in config.yaml:

list-bases-enabled: true

• Default description: List knowledge bases.

• Input properties:

  • page, str: The page number to list the bases for, optional, defaults to 1.
  • limit, str: The maximum number of knowledge bases to list, optional, defaults to 20.
  • timeout, int: Dynamic timeout parameter, enabled by timeout-param-enabled, optional, defaults to 60 seconds.

3. get_knowledge_base_info (default disabled)

Enable get_knowledge_base_info tool in config.yaml:

get-base-enabled: true

• Default description: Get information of the specified knowledge base ID, results including the knowledge base name, description, and other information.

• Input properties:

  • knowledge_base_id, str: The ID of the knowledge base to query.
  • timeout, int: Dynamic timeout parameter, enabled by timeout-param-enabled, optional, defaults to 60 seconds.

2. Install and run

2.1. Install using 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. Install from source

cd /path/to/project

pip install .

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

2.3. Run

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. Run with Docker or Docker Compose

1. Docker

   • Export the EXTRA_INDEX_URL environment variable, then run docker/0.1.0/build.sh to build the image, modifying the build script as needed or building manually.
   • Then refer to docker/0.1.0/run-in-docker.sh to run the container.

2. Docker Compose

   • Modify the .env file.
   • Modify the config.yaml file.
   • Run docker/0.1.0/docker-compose-up-d.sh to start the container, modifying the startup script as needed or running manually.

2.4. Testing

# 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. Server configurations

• YAML:

Example configurations yaml, for full configuration, see 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')."

Or configures the base URL and API key for each dataset and tools:

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...

• Available environment variables:

• Available environment variables of simp-logger:

4. MCP configurations

4.1. SSE

Example endpoint: http://127.0.0.1:41106/sse

4.2. stdio

Simple command line:

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. Development Conventions

• The project follows the standard Python packaging conventions.
• The code is organized into modules within the src/ragflow_knowledge_mcp_server directory.
• The server logic is in server.py, configuration properties are defined in properties/MCPServerProperties.py, and the services for interacting with the RAGFlow API are in the service directory.
• The project uses setuptools for building and setuptools_scm for versioning.
• The project uses simp-logger for logging, which can be configured through environment variables.