diff --git a/mcp/README.md b/mcp/README.md new file mode 100644 index 0000000..153c6e3 --- /dev/null +++ b/mcp/README.md @@ -0,0 +1,55 @@ +# MCP 服务集合 + +三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: + +| 目录 | 容器名 | 作用 | 宿主机端口(默认) | MCP 端点 | +|---|---|---|---|---| +| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `8081` | `POST /` | +| `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `8082` | `POST /mcp` | +| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步)+ 图片 `/upload` | `8083` | `POST /mcp` | + +## 部署(无 nginx-proxy,IP:端口直连) + +这些服务与 `agent` 仓库的 `agent-core` 共用外部网络 `my-app-network`(agent 按**容器名**访问, +如 `http://mcp_web_search:3000/`),所以该网络要先创建一次: + +```bash +docker network create my-app-network +``` + +`image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 +(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥,直接起: + +```bash +cd /root/workspace/tools/mcp +docker compose up -d --build +``` + +可选环境变量(写在仓库顶层 `.env` 即可,不写就用默认值): + +| 变量 | 默认 | 说明 | +|---|---|---| +| `WEB_SEARCH_PORT` | `8081` | web_search 映射到宿主机的端口 | +| `IMAGE_GEN_PORT` | `8082` | image_gen 映射到宿主机的端口 | +| `VIDEO_GEN_PORT` | `8083` | video_gen 映射到宿主机的端口 | +| `PUBLIC_BASE_URL` | `http://localhost:8083` | video_gen `/upload` 返回的 URL 前缀,必须是**外部可达**地址(智谱要能取到这张图);无域名时填 `http://<服务器IP>:` | + +## 端口暴露范围(安全) + +agent 走 `my-app-network` 用容器名 + 容器内端口(3000)访问,**不依赖宿主机端口**。所以对外 +只建议放行 `8083`(原因见下),`8081` / `8082` 建议不对公网开放: + +- `web_search`:服务端无鉴权,暴露即被白嫖搜索额度。 +- `image_gen`:token 由调用方自带,暴露后可被拿来消耗你自己的智谱额度(若 token 泄露)。 +- `video_gen`:`PUBLIC_BASE_URL` 指向它,智谱服务器要能下载你上传的参考图,所以**做图生视频时 + 必须对外放行**。注意它的 `/upload` 与 `/uploads/*` 本身不鉴权(8MB / 24h 临时文件), + 不需要图生视频就别放行。 + +## 单独调试 + +```bash +docker compose up -d --build mcp_web_search +curl http://localhost:8081/health +``` + +各目录下的 `README.md` 有该服务的工具说明、header 覆盖项与 curl 调试脚本。 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index a2685e4..821f2e6 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -1,14 +1,12 @@ +# 无 nginx-proxy 部署:每个服务把容器 3000 映射到各自宿主机端口,用 http://<服务器IP>:<端口>/mcp 访问。 +# 端口可用 .env / 环境变量覆盖(WEB_SEARCH_PORT / IMAGE_GEN_PORT / VIDEO_GEN_PORT)。 services: mcp_web_search: build: ./web_search container_name: mcp_web_search restart: unless-stopped - expose: - - "3000" - environment: - - VIRTUAL_HOST=web-search.ai.foresh.com - - VIRTUAL_PORT=3000 - - CERT_NAME=default + ports: + - "${WEB_SEARCH_PORT:-8081}:3000" networks: - my-app-network @@ -16,29 +14,27 @@ services: build: ./image_gen container_name: mcp_image_gen restart: unless-stopped - expose: - - "3000" - environment: - - VIRTUAL_HOST=image-gen.ai.foresh.com - - VIRTUAL_PORT=3000 - - CERT_NAME=default + ports: + - "${IMAGE_GEN_PORT:-8082}:3000" networks: - my-app-network mcp_video_gen: - build: ./video_gen - container_name: mcp_video_gen - restart: unless-stopped - expose: - - "3000" - environment: - - VIRTUAL_HOST=video-gen.ai.foresh.com - - VIRTUAL_PORT=3000 - - CERT_NAME=default - - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com - networks: - - my-app-network + build: ./video_gen + container_name: mcp_video_gen + restart: unless-stopped + ports: + - "${VIDEO_GEN_PORT:-8083}:3000" + environment: + # /upload 返回给浏览器/AI 的 URL 前缀,必须是【外部可达】地址: + # 无域名时填 http://<服务器IP>:,否则智谱取不到图,图生视频会失败。 + # 不设则退化为 http://localhost:8083(只在本机 curl 调试时可用)。 + - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-http://localhost:8083} + networks: + - my-app-network networks: + # 与 agent 仓库共用:agent-core 按容器名访问这些服务(如 http://mcp_web_search:3000/)。 + # 只需创建一次:docker network create my-app-network my-app-network: external: true diff --git a/mcp/image_gen/README.md b/mcp/image_gen/README.md index 7c942a5..b7627f4 100644 --- a/mcp/image_gen/README.md +++ b/mcp/image_gen/README.md @@ -21,14 +21,14 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_image_gen ``` -服务容器名 `mcp_image_gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_image_gen`,容器内端口 3000,默认映射到宿主机 8082,即 `http://<服务器IP>:8082/mcp`。 直接连容器调试: ```bash docker exec -it mcp_image_gen sh -# 或本机 -curl http://localhost:3000/health +# 或本机(宿主机映射端口) +curl http://localhost:8082/health # {"status":"ok","service":"image_gen","sessions":0} ``` @@ -42,7 +42,7 @@ curl http://localhost:3000/health { "mcpServers": { "image_gen": { - "url": "https://image-gen.ai.foresh.com/mcp", + "url": "http://<服务器IP>:8082/mcp", "headers": { "Authorization": "Bearer " } @@ -136,7 +136,7 @@ MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → ` TOKEN="" # 1. initialize 拿 sessionId -SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ +SESSION=$(curl -s -D - -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -154,7 +154,7 @@ SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ echo "Session: $SESSION" # 2. notifications/initialized -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -162,7 +162,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' # 3. 列出工具(可选验证) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -170,7 +170,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' # 4. 调 image_gen -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ diff --git a/mcp/video_gen/README.md b/mcp/video_gen/README.md index c52a1d4..34cea7e 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -22,14 +22,14 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_video_gen ``` -服务容器名 `mcp_video_gen`,通过反代暴露为 `https://video-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_video_gen`,容器内端口 3000,默认映射到宿主机 8083,即 `http://<服务器IP>:8083/mcp`。 直接连容器调试: ```bash docker exec -it mcp_video_gen sh -# 或本机 -curl http://localhost:3000/health +# 或本机(宿主机映射端口) +curl http://localhost:8083/health # {"status":"ok","service":"video_gen","sessions":0} ``` @@ -43,7 +43,7 @@ curl http://localhost:3000/health { "mcpServers": { "video_gen": { - "url": "https://video-gen.ai.foresh.com/mcp", + "url": "http://<服务器IP>:8083/mcp", "headers": { "Authorization": "Bearer " } @@ -67,25 +67,26 @@ curl http://localhost:3000/health ## 上传图片:POST /upload -供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。 +供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**:以前靠反代控制访问,现在端口直连,只能靠宿主机防火墙/安全组控制(做图生视频时 `PUBLIC_BASE_URL` 指向该端口,智谱服务器得能取到图)。不需要图生视频就别对公网放行该端口。 ### 配置 通过环境变量告诉服务端「对外公开的 base URL」,用于拼接返回的 `url` 字段: ```yaml -# docker-compose.yml +# docker-compose.yml(无域名部署:填服务器 IP + 宿主机映射端口) environment: - - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com + - PUBLIC_BASE_URL=http://<服务器IP>:8083 ``` -未设置时 fallback 到 `http://localhost:3000`(本机调试)。 +必须填**外部可达**地址:这个 URL 会交给智谱服务器去下载,填 `localhost` 或内网地址都会拉不到图。 +compose 未提供时的默认值是 `http://localhost:8083`(只适合本机 curl 调试);代码本身的 fallback 是 `http://localhost:3000`。 可选环境变量: | 变量 | 默认 | 说明 | |---|---|---| -| `PUBLIC_BASE_URL` | `http://localhost:3000` | 返回 `url` 字段里拼接的对外 base URL | +| `PUBLIC_BASE_URL` | `http://localhost:8083`(compose 提供;代码 fallback `http://localhost:3000`) | 返回 `url` 字段里拼接的对外 base URL | | `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录(容器内临时) | | `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | @@ -113,7 +114,7 @@ file: <二进制图片文件> ```jsonc { - "url": "https://video-gen.ai.foresh.com/uploads/abc123.png", + "url": "http://<服务器IP>:8083/uploads/abc123.png", "filename": "abc123.png", "size": 12345, "content_type": "image/png", @@ -123,22 +124,23 @@ file: <二进制图片文件> 返回的 `url` 可直接作为 `video_gen.image_url` 使用。 -### 反代路由 +### 端口与路由 -反代需要额外暴露两条路由到 `mcp_video_gen:3000`: +`/upload` 与 `/uploads/*` 由 `mcp_video_gen` 同一进程提供,不需要单独配路由;compose 已把 +容器 3000 映射到宿主机 `VIDEO_GEN_PORT`(默认 8083),两条路径直接可用: -- `POST /upload` → `/upload` -- `GET /uploads/*` → `/uploads/*` +- `POST /upload` +- `GET /uploads/*` ### curl 示例 ```bash -curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload -# {"url":"https://video-gen.ai.foresh.com/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} +curl -F "file=@/tmp/cat.png" http://<服务器IP>:8083/upload +# {"url":"http://<服务器IP>:8083/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} # 然后把 url 喂给 MCP: # tool: video_gen -# args: { image_url: "https://video-gen.ai.foresh.com/uploads/xxx.png", prompt: "..." } +# args: { image_url: "http://<服务器IP>:8083/uploads/xxx.png", prompt: "..." } ``` --- @@ -256,7 +258,7 @@ MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → ` TOKEN="" # 1. initialize 拿 sessionId -SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ +SESSION=$(curl -s -D - -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -274,7 +276,7 @@ SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ echo "Session: $SESSION" # 2. notifications/initialized -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -282,7 +284,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' # 3. 列出工具(可选验证) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -290,7 +292,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' # 4. 提交文生视频任务 -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -310,7 +312,7 @@ curl -s -X POST http://localhost:3000/mcp \ }' # 5. 查结果(替换下面的 ) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -331,12 +333,12 @@ curl -s -X POST http://localhost:3000/mcp \ ### 单独调试 `/upload` ```bash -# 上传图片,返回 url -curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload -# {"url":"https://video-gen.ai.foresh.com/uploads/xxx.png", ...} +# 上传图片,返回 url(宿主机映射端口) +curl -F "file=@/tmp/cat.png" http://localhost:8083/upload +# {"url":"http://localhost:8083/uploads/xxx.png", ...} # 下载上传过的文件 -curl -o cat.png https://video-gen.ai.foresh.com/uploads/xxx.png +curl -o cat.png http://localhost:8083/uploads/xxx.png ``` --- @@ -403,4 +405,4 @@ A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `video_gen.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 **Q: `PUBLIC_BASE_URL` 不设会怎样?** -A: fallback 到 `http://localhost:3000`,AI 拿到的 curl 是 `http://localhost:3000/upload`。外网访问不到。本机调试无所谓,生产请显式设置。 \ No newline at end of file +A: compose 会给个默认值 `http://localhost:8083`(代码 fallback 是 `http://localhost:3000`),本机 curl 调试没问题,但智谱服务器拉不到图——图生视频会失败。所以无域名部署时要显式设成 `http://<服务器IP>:<宿主机映射端口>`,并确保该端口对公网可达。 \ No newline at end of file diff --git a/mcp/web_search/README.md b/mcp/web_search/README.md index 01cf528..62d00f0 100644 --- a/mcp/web_search/README.md +++ b/mcp/web_search/README.md @@ -37,6 +37,13 @@ MCP 端点: `docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 +容器内监听 3000,默认映射到宿主机 `8081`(可用 `WEB_SEARCH_PORT` 覆盖): + ```bash docker compose build mcp_web_search && docker compose up -d mcp_web_search +curl http://localhost:8081/health +# {"name":"web_search","version":"...","transport":"http/sse","port":3000} ``` + +agent 侧走 `my-app-network` 用容器名访问(`http://mcp_web_search:3000/`),不依赖宿主机端口; +该服务**无服务端鉴权**,暴露到公网会被白嫆(消耗上游免费额度),建议不对公网放行 8081。