diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index f73d7c031..7378ab4be 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -8,7 +8,7 @@ services: mysql: condition: service_healthy image: ${RAGFLOW_IMAGE} - # example to setup MCP server + # Example configuration to set up an MCP server: # command: # - --enable-mcpserver # - --mcp-host=0.0.0.0 @@ -16,7 +16,7 @@ services: # - --mcp-base-url=http://127.0.0.1:9380 # - --mcp-script-path=/ragflow/mcp/server/server.py # - --mcp-mode=self-host - # - --mcp-host-api-key="ragflow-xxxxxxx" + # - --mcp-host-api-key=ragflow-xxxxxxx container_name: ragflow-server ports: - ${SVR_HTTP_PORT}:9380 @@ -24,7 +24,7 @@ services: - 443:443 - 5678:5678 - 5679:5679 - - 9382:9382 # entry for MCP (host_port:docker_port). The docker_port should match with the value you set for `mcp-port` above + - 9382:9382 # entry for MCP (host_port:docker_port). The docker_port must match the value you set for `mcp-port` above. volumes: - ./ragflow-logs:/ragflow/logs - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf @@ -43,7 +43,7 @@ services: - ragflow restart: on-failure # https://docs.docker.com/engine/daemon/prometheus/#create-a-prometheus-configuration - # If you're using Docker Desktop, the --add-host flag is optional. This flag makes sure that the host's internal IP gets exposed to the Prometheus container. + # If you use Docker Desktop, the --add-host flag is optional. This flag ensures that the host's internal IP is exposed to the Prometheus container. extra_hosts: - "host.docker.internal:host-gateway" # executor: diff --git a/docs/configurations.md b/docs/configurations.md index b930ceca3..e70944a21 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -180,7 +180,7 @@ The callback URL should be configured in your OAuth provider as: https://your-app.com/oauth/callback/ ``` -For detailed instructions on configuring **service_conf.yaml.template**, please refer to [Usage](../api/apps/auth/README.md#usage). +For detailed instructions on configuring **service_conf.yaml.template**, please refer to [Usage](https://github.com/infiniflow/ragflow/blob/main/api/apps/auth/README.md#usage). ### `user_default_llm` diff --git a/docs/develop/acquire_ragflow_api_key.md b/docs/develop/acquire_ragflow_api_key.md index 2623684d1..fe1220798 100644 --- a/docs/develop/acquire_ragflow_api_key.md +++ b/docs/develop/acquire_ragflow_api_key.md @@ -5,7 +5,7 @@ slug: /acquire_ragflow_api_key # Acquire RAGFlow API key -A key is required for the RAGFlow server to authenticate your requests via HTTP or a Python API. This documents provides instructions on obtaining a RAGFlow API key. +An API key is required for the RAGFlow server to authenticate your HTTP/Python or MCP requests. This documents provides instructions on obtaining a RAGFlow API key. 1. Click your avatar in the top right corner of the RAGFlow UI to access the configuration page. 2. Click **API** to switch to the **API** page. diff --git a/docs/develop/launch_mcp_server.md b/docs/develop/launch_mcp_server.md new file mode 100644 index 000000000..e9acdf9b4 --- /dev/null +++ b/docs/develop/launch_mcp_server.md @@ -0,0 +1,202 @@ +--- +sidebar_position: 4 +slug: /launch_mcp_server +--- + +# Launch RAGFlow MCP server + +Launch an MCP server from source or via Docker. + +--- + +A RAGFlow Model Context Protocol (MCP) server is designed as an independent component to complement the RAGFlow server. Note that an MCP server must operate alongside a properly functioning RAGFlow server. + +An MCP server can start up in either self-host mode (default) or host mode: + +- **Self-host mode**: + When launching an MCP server in self-host mode, you must provide an API key to authenticate the MCP server with the RAGFlow server. In this mode, the MCP server can access *only* the datasets (knowledge bases) of a specified tenant on the RAGFlow server. +- **Host mode**: + In host mode, each MCP client can access their own knowledge bases on the RAGFlow server. However, each client request must include a valid API key to authenticate the client with the RAGFlow server. + +Once a connection is established, an MCP server communicates with its client in MCP HTTP+SSE (Server-Sent Events) mode, unidirectionally pushing responses from the RAGFlow server to its client in real time. + +## Prerequisites + +1. Ensure RAGFlow is upgraded to v0.18.0 or later. +2. Have your RAGFlow API key ready. See [Acquire a RAGFlow API key](./acquire_ragflow_api_key.md). + +:::tip INFO +If you wish to try out our MCP server without upgrading RAGFlow, community contributor **yiminghub2024** 👏 shares their recommended steps [here](#launch-an-mcp-server-without-upgrading-ragflow). +:: + +## Launch an MCP server + +You can start an MCP server either from source code or via Docker. + +### Launch from source code + +1. Ensure that a RAGFlow server v0.18.0+ is properly running. +2. Launch the MCP server: + + +```bash +# Launch the MCP server to work in self-host mode, run either of the following +uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base_url=http://127.0.0.1:9380 --api_key=ragflow-xxxxx +# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base_url=http://127.0.0.1:9380 mode=self-host --api_key=ragflow-xxxxx + +# To launch the MCP server to work in host mode, run the following instead: +# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base_url=http://127.0.0.1:9380 mode=host +``` + +Where: + +- `host`: The MCP server's host address. +- `port`: The MCP server's listening port. +- `base_url`**: The address of the running RAGFlow server. +- `mode`: The launch mode. + - `self-host`: (default) self-host mode. + - `host`: host mode. +- `api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. + +### Launch from Docker + +#### 1. Enable MCP server + +The MCP server is designed as an optional, component that complements the RAGFlow server and is disable by default. To enable MCP server: + +1. Navigate to `docker/docker-compose.yml`. +2. Uncomment the `services.ragflow.command` section as shown below: + +```yaml {6-13} + services: + ragflow: + ... + image: ${RAGFLOW_IMAGE} + # Example configuration to set up an 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 + - --mcp-mode=self-host + - --mcp-host-api-key=ragflow-xxxxxxx +``` + +Where: + +- `mcp-host`: The MCP server's host address. +- `mcp-port`: The MCP server's listening port. +- `mcp-base_url`: The address of the running RAGFlow server. +- `mcp-script-path`: The file path to the MCP server’s main script. +- `mcp-mode`: The launch mode. + - `self-host`: (default) self-host mode. + - `host`: host mode. +- `mcp-host-api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. + +#### 2. Launch a RAGFlow server alongside an MCP server + +Run `docker compose -f docker-compose.yml` to launch the RAGFlow server together with the MCP server. + +*The following ASCII art confirms a successful launch:* + +```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 launch mode: self-host + 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.18.0-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 | / / / /_/ (__ ) ,< / /____> `, useRaptor: 'Gunakan RAPTOR untuk meningkatkan pengambilan', useRaptorTip: - 'Pemrosesan Abstraktif Rekursif untuk Pengambilan Terorganisasi Pohon, silakan merujuk ke https://huggingface.co/papers/2401.18059', + 'Aktifkan RAPTOR untuk tugas tanya jawab multi-langkah. Lihat https://ragflow.io/docs/dev/enable_raptor untuk informasi lebih lanjut.', prompt: 'Prompt', promptTip: 'Gunakan prompt sistem untuk menjelaskan tugas untuk LLM, tentukan bagaimana harus merespons, dan menguraikan persyaratan lainnya. Prompt sistem sering digunakan bersama dengan kunci (variabel), yang berfungsi sebagai berbagai input data untuk LLM. Gunakan garis miring `/` atau tombol (x) untuk menampilkan kunci yang digunakan.', diff --git a/web/src/locales/ja.ts b/web/src/locales/ja.ts index 83fa3e407..fd1a57de0 100644 --- a/web/src/locales/ja.ts +++ b/web/src/locales/ja.ts @@ -285,7 +285,7 @@ export default {

エンティティタイプを設定することを忘れないでください。

`, useRaptor: 'RAPTORを使用して検索を強化', useRaptorTip: - 'ツリー構造化検索のための再帰的抽象処理(RAPTOR)については、詳細はhttps://huggingface.co/papers/2401.18059をご覧ください', + 'マルチホップ質問応答タスクでRAPTORを有効にしてください。詳細は https://ragflow.io/docs/dev/enable_raptor をご覧ください。', prompt: 'プロンプト', promptTip: 'LLMのタスクを説明し、どのように応答すべきかを指定し、他のさまざまな要件を概説するためにシステムプロンプトを使用します。システムプロンプトは、LLMのさまざまなデータ入力として機能するキー(変数)と共に使用されることがよくあります。使用するキーを表示するには、スラッシュ `/` または (x) ボタンを使用します。', diff --git a/web/src/locales/pt-br.ts b/web/src/locales/pt-br.ts index 068e83d2c..55bb1f933 100644 --- a/web/src/locales/pt-br.ts +++ b/web/src/locales/pt-br.ts @@ -262,7 +262,7 @@ export default {

Linhas de texto que não seguirem essas regras serão ignoradas, e cada par de Pergunta & Resposta será tratado como um fragmento distinto.

`, useRaptor: 'Usar RAPTOR para melhorar a recuperação', useRaptorTip: - 'Processamento Abstrativo Recursivo para Recuperação Organizada em Árvore. Veja mais em https://huggingface.co/papers/2401.18059.', + 'Ative o RAPTOR para tarefas de perguntas e respostas multi-hop. Veja https://ragflow.io/docs/dev/enable_raptor para mais detalhes.', prompt: 'Prompt', promptTip: 'Use o prompt do sistema para descrever a tarefa para o LLM, especificar como ele deve responder e esboçar outros requisitos diversos. O prompt do sistema é frequentemente usado em conjunto com chaves (variáveis), que servem como várias entradas de dados para o LLM. Use uma barra `/` ou o botão (x) para mostrar as chaves a serem usadas.', diff --git a/web/src/locales/vi.ts b/web/src/locales/vi.ts index c577b8a82..f2314dd23 100644 --- a/web/src/locales/vi.ts +++ b/web/src/locales/vi.ts @@ -295,7 +295,7 @@ export default {

Đảm bảo bạn đã đặt Loại thực thể.

`, useRaptor: 'Sử dụng RAPTOR để cải thiện truy xuất', useRaptorTip: - 'Recursive Abstractive Processing for Tree-Organized Retrieval, xem https://huggingface.co/papers/2401.18059 để biết thêm thông tin', + 'Kích hoạt RAPTOR cho các tác vụ hỏi đáp đa bước. Xem chi tiết tại https://ragflow.io/docs/dev/enable_raptor.', prompt: 'Nhắc nhở', promptTip: 'Sử dụng lời nhắc hệ thống để mô tả nhiệm vụ cho LLM, chỉ định cách nó nên phản hồi và phác thảo các yêu cầu khác nhau. Lời nhắc hệ thống thường được sử dụng kết hợp với các khóa (biến), đóng vai trò là các đầu vào dữ liệu khác nhau cho LLM. Sử dụng dấu gạch chéo `/` hoặc nút (x) để hiển thị các khóa cần sử dụng.', diff --git a/web/src/locales/zh-traditional.ts b/web/src/locales/zh-traditional.ts index 6ff4fcdc6..608551196 100644 --- a/web/src/locales/zh-traditional.ts +++ b/web/src/locales/zh-traditional.ts @@ -316,8 +316,8 @@ export default {

標籤欄中,標籤之間用英文逗號分隔。

不符合上述規則的文字行將被忽略。 `, - useRaptor: '使用RAPTOR文件增強策略', - useRaptorTip: '請參考 https://huggingface.co/papers/2401.18059', + useRaptor: '使用 RAPTOR 文件增強策略', + useRaptorTip: '啟用 RAPTOR 以用於多跳問答任務。詳情請參見:https://ragflow.io/docs/dev/enable_raptor', prompt: '提示詞', promptMessage: '提示詞是必填項', promptText: `请請總結以下段落。 小心數字,不要編造。 段落如下: diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts index 7bc367e04..842c681da 100644 --- a/web/src/locales/zh.ts +++ b/web/src/locales/zh.ts @@ -333,8 +333,8 @@ export default {

在标签列中,标签之间使用英文逗号分隔。

不符合上述规则的文本行将被忽略。 `, - useRaptor: '使用召回增强RAPTOR策略', - useRaptorTip: '请参考 https://huggingface.co/papers/2401.18059', + useRaptor: '使用召回增强 RAPTOR 策略', + useRaptorTip: '为多跳问答任务启用 RAPTOR,详情请见 : https://ragflow.io/docs/dev/enable_raptor。', prompt: '提示词', promptMessage: '提示词是必填项', promptText: `请总结以下段落。 小心数字,不要编造。 段落如下: