From 1aa97600df147231e73328e905f82cd934720086 Mon Sep 17 00:00:00 2001
From: yiminghub2024 <482890@qq.com>
Date: Sun, 27 Apr 2025 18:47:12 +0800
Subject: [PATCH] Fix mcp server startup failure (#7329)

### What problem does this PR solve?
0.18.0 mcp server can not start with upgrade from 0.17.2 or new install
except rebuild all docker

Close #7321

mcp server can not start auto from docker :
2025-04-25 17:30:44,512 INFO 25 task_executor_2a9f3e2de99a_0 reported
heartbeat: {"name": "task_executor_2a9f3e2de99a_0", "now":
"2025-04-25T17:30:44.509+08:00", "boot_at":
"2025-04-25T16:43:33.038+08:00", "pending": 0, "lag": 0, "done": 0,
"failed": 0, "current": {}}
usage: server.py [-h] [--base_url BASE_URL] [--host HOST] [--port PORT]
                 [--mode MODE] [--api_key API_KEY]
server.py: error: unrecognized arguments:

problem:
server.py in docker start arguments not correct , so mcp server start
fail
reason:
```
1. docker-copose.yaml
     example  - --mcp-host-api-key="ragflow-12345678" is wrong.  do not add "" to key or it says:"api-key wrong"
2.docker file  entrypoint.sh  can not translate config to exec command , we need mapping file from host to docker
     - ./entrypoint.sh:/ragflow/entrypoint.sh
3.just add one code raw fix all probelm
```
### Type of change

- [x] Bug Fix (non-breaking change which fixes an issue)
- [x] Documentation Update
- [x] Performance Improvement

---------

Co-authored-by: Yongteng Lei <yongtengrey@outlook.com>
Co-authored-by: Kevin Hu <kevinhu.sh@gmail.com>
---
 .gitattributes            |  3 ++-
 docker/docker-compose.yml |  1 +
 docker/entrypoint.sh      |  0
 docs/develop/mcp.md       | 22 +++++++++++++++++++---
 4 files changed, 22 insertions(+), 4 deletions(-)
 mode change 100644 => 100755 docker/entrypoint.sh

diff --git a/.gitattributes b/.gitattributes
index 526c8a38d..199ea9a55 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1 +1,2 @@
-*.sh text eol=lf
\ No newline at end of file
+*.sh text eol=lf
+docker/entrypoint.sh text eol=lf executable
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index b9e41df39..f73d7c031 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -32,6 +32,7 @@ services:
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf
       - ../history_data_agent:/ragflow/history_data_agent
       - ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template
+      - ./entrypoint.sh:/ragflow/entrypoint.sh
 
     env_file: .env
     environment:
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
old mode 100644
new mode 100755
diff --git a/docs/develop/mcp.md b/docs/develop/mcp.md
index e13ac15fc..82e624050 100644
--- a/docs/develop/mcp.md
+++ b/docs/develop/mcp.md
@@ -63,7 +63,7 @@ Here are three augments required, the first two,`host` and `port`, are self-expl
 
 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
+#### Alongside RAGFlow {#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.
@@ -81,10 +81,26 @@ services:
       - --mcp-base-url=http://127.0.0.1:9380
       - --mcp-script-path=/ragflow/mcp/server/server.py
       - --mcp-mode=self-host # `self-host` or `host`
-      - --mcp-host-api-key="ragflow-xxxxxxx" # only need to privide when mode is `self-host`
+      - --mcp-host-api-key=ragflow-xxxxxxx # only need to privide when mode is `self-host` and use bare string without quotation marks here.
 ```
 
-Then launch it normally `docker compose -f docker-compose.yml`.
+To troubleshoot, launch the service in the foreground using `docker compose -f docker-compose.yml`.
+
+### For those upgrading from versions before v0.18.0
+
+1. Get all MCP related files ready.
+   1. copy `mcp/` directory to local.
+   1. copy `docker/docker-compose.yml` to local.
+   1. copy `docker/entrypoint.sh` to local.
+   1. resolve necessary dependencies via `uv`.
+      - simply run `uv add mcp` if it works for you. Or:
+      - copy `pyproject.toml` and run `uv sync --python 3.10 --all-extras`.
+1. Change `docker-compose.yml` to enable MCP as it is disable by default, [see last section](#alongside_ragflow).
+1. Launch the service with `docker compose -f docker-compose.yml up -d`
+
+### Check the MCP server status
+
+Checking logs of RAGFlow server with `docker logs ragflow-server`. If you see the MCP server ASCII art there, it means all is OK!
 
 ```bash
 ragflow-server  | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380...