diff --git a/docs/guides/mcp.md b/docs/guides/mcp.md new file mode 100644 index 000000000..2b51437c1 --- /dev/null +++ b/docs/guides/mcp.md @@ -0,0 +1,162 @@ +--- +sidebar_position: 7 +slug: /MCP server +--- + +# Overview of RAGFlow Model Context Protocol (MCP) Server + +The RAGFlow MCP server operates as an independent component that complements the RAGFlow server. However, it requires a RAGFlow server to work functionally well, meaning, the MCP client and server communicate with each other in MCP HTTP+SSE mode (once the connection is established, server pushes messages to client only), and responses are expected from RAGFlow server. + +The MCP server currently offers a specific tool to assist users in searching for relevant information powered by RAGFlow DeepDoc technology: + +• **retrieve**: Fetches relevant chunks from specified `dataset_ids` and optional `document_ids` using the RAGFlow retrieve interface, based on a given question. Details of all available datasets, namely, `id` and `description`, are provided within the tool description for each individual dataset. + +## Launching the MCP Server + +Similar to launching the RAGFlow server, the MCP server can be started either from source code or via Docker. + +### Launching from Source Code + +All you need to do is stand on the right place and strike out command, assuming you are on the project working directory. + +```bash +uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base_url=http://127.0.0.1:9380 +``` + +For testing purposes, there is an [MCP client example](#example_mcp_client) provided, free to take! + +#### Required Arguments + +• **`host`**: Specifies the server's host address. +• **`port`**: Defines the server's listening port. +• **`base_url`**: The address of the RAGFlow server that is already running and ready to handle tasks. + +Here are three augments required, the first two,`host` and `port`, are self-explained. The`base_url` is the address of the ready-to-serve RAGFlow server to actually perform the task. + +### Launching from Docker + +Building a standalone MCP server image is straightforward and easy, so we just proposed a way to launch it with RAGFlow server here. + +#### Alongside RAGFlow + +As MCP server is an extra and optional component of RAGFlow server, we consume that not everybody going to use it. Thus, it is disable by default. +To enable it, simply find `docker/docker-compose.yml` to uncomment `services.ragflow.command` section. + +```yaml +services: + ragflow: + ... + image: ${RAGFLOW_IMAGE} + # example to setup MCP server + command: + - --enable-mcpserver + - --mcp-host=0.0.0.0 + - --mcp-port=9382 + - --mcp-base-url=http://127.0.0.1:9380 + - --mcp-script-path=/ragflow/mcp/server/server.py +``` + +Then launch it normally `docker compose -f docker-compose.yml`. + +```bash +ragflow-server | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380... +ragflow-server | Starting 1 task executor(s) on host 'dd0b5e07e76f'... +ragflow-server | 2025-04-18 15:41:18,816 INFO 27 ragflow_server log path: /ragflow/logs/ragflow_server.log, log levels: {'peewee': 'WARNING', 'pdfminer': 'WARNING', 'root': 'INFO'} +ragflow-server | +ragflow-server | __ __ ____ ____ ____ _____ ______ _______ ____ +ragflow-server | | \/ |/ ___| _ \ / ___|| ____| _ \ \ / / ____| _ \ +ragflow-server | | |\/| | | | |_) | \___ \| _| | |_) \ \ / /| _| | |_) | +ragflow-server | | | | | |___| __/ ___) | |___| _ < \ V / | |___| _ < +ragflow-server | |_| |_|\____|_| |____/|_____|_| \_\ \_/ |_____|_| \_\ +ragflow-server | +ragflow-server | MCP host: 0.0.0.0 +ragflow-server | MCP port: 9382 +ragflow-server | MCP base_url: http://127.0.0.1:9380 +ragflow-server | INFO: Started server process [26] +ragflow-server | INFO: Waiting for application startup. +ragflow-server | INFO: Application startup complete. +ragflow-server | INFO: Uvicorn running on http://0.0.0.0:9382 (Press CTRL+C to quit) +ragflow-server | 2025-04-18 15:41:20,469 INFO 27 found 0 gpus +ragflow-server | 2025-04-18 15:41:23,263 INFO 27 init database on cluster mode successfully +ragflow-server | 2025-04-18 15:41:25,318 INFO 27 load_model /ragflow/rag/res/deepdoc/det.onnx uses CPU +ragflow-server | 2025-04-18 15:41:25,367 INFO 27 load_model /ragflow/rag/res/deepdoc/rec.onnx uses CPU +ragflow-server | ____ ___ ______ ______ __ +ragflow-server | / __ \ / | / ____// ____// /____ _ __ +ragflow-server | / /_/ // /| | / / __ / /_ / // __ \| | /| / / +ragflow-server | / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / +ragflow-server | /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ +ragflow-server | +ragflow-server | +ragflow-server | 2025-04-18 15:41:29,088 INFO 27 RAGFlow version: v0.17.2-285-gb2c299fa full +ragflow-server | 2025-04-18 15:41:29,088 INFO 27 project base: /ragflow +ragflow-server | 2025-04-18 15:41:29,088 INFO 27 Current configs, from /ragflow/conf/service_conf.yaml: +ragflow-server | ragflow: {'host': '0.0.0.0', 'http_port': 9380} +... +ragflow-server | * Running on all addresses (0.0.0.0) +ragflow-server | * Running on http://127.0.0.1:9380 +ragflow-server | * Running on http://172.19.0.6:9380 +ragflow-server | ______ __ ______ __ +ragflow-server | /_ __/___ ______/ /__ / ____/ _____ _______ __/ /_____ _____ +ragflow-server | / / / __ `/ ___/ //_/ / __/ | |/_/ _ \/ ___/ / / / __/ __ \/ ___/ +ragflow-server | / / / /_/ (__ ) ,< / /____>