ragflow-knowledge-mcp-server by lumerix7 - MCP Server

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

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

Docker
- Export the EXTRA_INDEX_URL environment variable, then run to build the image, modifying the build script as needed or building manually.
- Then refer to to run the container.
Docker Compose
- Modify the .env file.
- Modify the config.yaml file.
- Run 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 :

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:

Yaml	Environment variable name	Default value	Description
	`RAGFLOW_KNOWLEDGE_MCP_SERVER_CONFIG`	`config.yaml`	The config file path, also available in CLI option `--config=/path/to/config.yaml`.
`default-base-url`	`DEFAULT_RAGFLOW_KNOWLEDGE_BASE_URL`	-	The default base URL for the knowledge base.
`default-api-key`	`DEFAULT_RAGFLOW_KNOWLEDGE_API_KEY`	-	The default API key for the knowledge base.
`server-name`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_NAME`	RAGFlow Knowledge Base	The name of the MCP server.
`transport`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_TRANSPORT`	stdio	The transport type. Can be `stdio` or `sse`.
`sse-transport-endpoint`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_TRANSPORT_ENDPOINT`	`/messages/`	The SSE transport endpoint.
`sse-bind-host`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_BIND_HOST`	0.0.0.0	The host to bind the SSE transport.
`sse-port`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_PORT`	41106	The port for the SSE transport.
`sse-debug-enabled`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_SSE_DEBUG_ENABLED`	False	Whether to enable debug mode for SSE.
`timeout`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT`	60	The timeout for the server.
`timeout-param-enabled`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_ENABLED`	False	Whether to enable the timeout parameter.
`timeout-param-description`	`RAGFLOW_KNOWLEDGE_MCP_SERVER_TIMEOUT_PARAM_DESCRIPTION`	`The total timeout for one calling, in seconds, optional, defaults to {self.timeout} seconds.`	The description of the timeout parameter.

Available environment variables of simp-logger:

Variable name	Default value	Description
`SIMP_LOGGER_LOG_FILE_ENABLED`	True	Whether to enable logging to file.
`SIMP_LOGGER_LOG_CONSOLE_ENABLED`	True	Whether to enable logging to console.
`SIMP_LOGGER_LOG_LEVEL`	INFO	The log level.
`SIMP_LOGGER_LOG_FILE`	`~/logs/simp-logger.log`	The log file path.
`SIMP_LOGGER_LOG_PATTERN`	`%(asctime)s %(levelname)s [%(threadName)s]: %(message)s`	The log pattern.
`SIMP_LOGGER_LOG_MAX_BYTES`	10485760 (10MB)	The maximum size of the log file.
`SIMP_LOGGER_LOG_BACKUP_COUNT`	5	The number of backup files to keep.
`SIMP_LOGGER_LOG_ROTATION_TYPE`	size	The type of log rotation. Can be `size` or `time`.
`SIMP_LOGGER_LOG_ROTATION_WHEN`	midnight	The time of day to rotate the log file.
`SIMP_LOGGER_LOG_ROTATION_INTERVAL`	1	The interval for log rotation.
`SIMP_LOGGER_LOG_CLEANUP_DISABLED`	False	Whether to disable logger cleanup.

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 for logging, which can be configured through environment variables.

lumerix7/ragflow-knowledge-mcp-server