ragflow-knowledge-mcp-server

ragflow-knowledge-mcp-server

プロジェクト概要：

RAGFlow 向けのシンプルなナレッジベース MCP サーバーです。

このプロジェクトは、RAGFlow のナレッジベース向けに Python で構築された 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 を使用しており、環境変数で設定できます。