明道云 MCP 中转（Node.js）

该服务使用 Streamable HTTP 提供 MCP 地址 POST /mcp、健康检查 GET /health 和 connection_check 工具。它从服务器环境变量读取明道云凭证，向明道云发现并代理 MCP 工具；Coze 只连接你的自建服务，不会接触明道云 Token。

本地启动

npm ci
npm start

验证：

curl http://127.0.0.1:8001/health

Related MCP server: Coze MCP Server For OpenClaw

Docker 部署

在仓库根目录构建镜像：

docker build -t mingdao-mcp-connection-check-node:1.0 .

在 M1/M2/M3 Mac 上构建 Linux 服务器镜像

Apple 芯片是 arm64 架构；多数云服务器是 linux/amd64。若镜像要导入常见的 x86 Linux 服务器，使用 Docker Desktop 的 buildx 显式构建 linux/amd64 版本：

docker buildx build --platform linux/amd64 --load -t mingdao-mcp-connection-check-node:1.0 .
docker save mingdao-mcp-connection-check-node:1.0 | gzip > mingdao-mcp-connection-check-node-linux-amd64.tar.gz

上传到服务器后加载：

gunzip -c mingdao-mcp-connection-check-node-linux-amd64.tar.gz | docker load

如果你的服务器也是 ARM Linux，则将命令中的 linux/amd64 改为 linux/arm64。发布到镜像仓库时可改用 --platform linux/amd64,linux/arm64 --push 发布多架构镜像；多架构构建不能与 --load 同时使用。

运行容器：

docker run -d --name mingdao-mcp-connection-check-node --restart unless-stopped -p 127.0.0.1:8001:8001 mingdao-mcp-connection-check-node:1.0

使用 Compose 从 GHCR 部署

服务器上下载本仓库后，创建部署变量文件并填入 GitHub 用户名或组织名：

cp .env.example .env

编辑 .env，设置 GHCR_OWNER、MINGDAO_MCP_URL 和 MINGDAO_MCP_AUTH_TOKEN。明道云 Token 只保存在服务器的 .env 中，建议执行 chmod 600 .env。

然后拉取并启动公开镜像：

docker compose pull
docker compose up -d
docker compose ps
curl http://127.0.0.1:8001/health

docker-compose.yml 默认只暴露本机端口；再使用 deploy/nginx.conf.example 将 HTTPS 的 /mcp 请求转发给它。

使用仓库内的 deploy/nginx.conf.example 配置 HTTPS 反向代理。Coze 中选择 Streamable HTTP，并填写 https://你的域名/mcp；第一阶段无需认证。

服务默认使用 8001。若同一服务器已有其他服务占用此端口，修改容器的主机端口，并相应调整 Nginx 上游地址。

明道云转发验收

1. 使用上面的 Compose 配置启动服务，并确认 curl http://127.0.0.1:8001/health 返回 mingdao_configured: true。

2. 初次部署时，MINGDAO_TOOL_OFFSET=0、MINGDAO_TOOL_LIMIT=1，因此 Coze 刷新 MCP 工具列表后会看到 connection_check 和明道云原始 tools/list 顺序中的第 1 个工具。容器日志的 mingdao_tools_exposed 事件会显示该工具名称。

3. 调用 connection_check。当返回 mingdao_reachable: true 和 mingdao_tool_count 时，说明服务器到明道云的鉴权和 MCP 工具发现均成功。

4. 在 Coze 调用任意明道云工具，参数和结果会由中转服务原样传递。

如果工具列表只有 connection_check，先调用它查看 error 字段，再执行 docker compose logs mcp-relay-node。这能区分 Coze 到中转服务的问题和中转服务到明道云的问题。

工具发现默认在 5 秒内未完成就返回本地 connection_check，避免明道云网络异常拖垮 Coze 的 MCP 握手。可在 .env 中通过 MINGDAO_DISCOVERY_TIMEOUT_MS 调整；单个明道云工具调用的默认上限为 45 秒，可通过 MINGDAO_TOOL_CALL_TIMEOUT_MS 调整。日志只记录 MCP 方法、工具名、耗时和脱敏错误，不记录 Token 或工具参数。

完成 Coze 兼容性验证后，将 MINGDAO_TOOL_OFFSET=0、MINGDAO_TOOL_LIMIT=0，再执行 docker compose up -d --force-recreate，即可恢复暴露全部明道云工具。

工具 Schema 二分定位

中转会保留明道云 tools/list 的原始顺序，不会按工具名称重排。因此可用 MINGDAO_TOOL_OFFSET（零基起点）和 MINGDAO_TOOL_LIMIT（连续数量）对 68 个工具二分测试。每次修改 .env 后均执行 docker compose up -d --force-recreate，并在 Coze 刷新工具列表。

例如先测试第 1–34 个工具：

MINGDAO_TOOL_OFFSET=0
MINGDAO_TOOL_LIMIT=34

如果 Coze 能正常识别，问题在后 34 个工具，下一次测试第 35–51 个：

MINGDAO_TOOL_OFFSET=34
MINGDAO_TOOL_LIMIT=17

如果 Coze 不能识别，问题在当前区间的前半部分。持续将当前区间减半，直到定位到单个工具。mingdao_tools_exposed 日志包含实际的偏移量、数量和工具名称，可用于核对区间。

Coze 工具兼容规则

不再对所有工具做通用 Schema 降级。默认不向 Coze 暴露已确认导致导入失败的 batch_create_process_nodes 与 create_process；可通过环境变量按需增删排除项：

MINGDAO_EXCLUDED_TOOLS=batch_create_process_nodes,create_process

get_record_list 仍会单独使用精简后的输入 Schema：移除过长说明和无关细节，但保留 filter.value.oneOf（字符串、数值或字符串数组）。调用该工具时参数会原样转发给明道云。

修改 .env 后执行：

docker compose up -d --force-recreate

容器日志中的 mingdao_tools_exposed.excluded_tool_names 可核对当前实际排除的工具。

GitHub Actions 自动发布

工作流 .github/workflows/mcp-relay-node-image.yml 会在 main 或 master 分支收到推送后，构建并发布 linux/amd64 镜像到 GitHub Container Registry：

ghcr.io/<GitHub 用户名或组织名>/mingdao-mcp-connection-check-node:latest

这是公开仓库，首次推送后在仓库的 Actions 页面确认工作流成功；若组织限制默认令牌的包写入权限，需要在仓库或组织的 Actions 设置中允许 GITHUB_TOKEN 使用 packages: write。GHCR 容器包可能首次仍默认为私有：在 GitHub 仓库主页右侧的 Packages 中打开该镜像，进入 Package settings，将可见性改为 Public。设置一次后，服务器可免登录拉取：

docker pull ghcr.io/<GitHub-用户名或组织名>/mingdao-mcp-connection-check-node:latest

如果你决定让镜像保持私有，服务器拉取前才需要创建一个只具备 read:packages 权限的 GitHub Personal Access Token（不要使用有仓库写入权限的 Token），并登录 GHCR：

echo <GitHub-PAT> | docker login ghcr.io -u <GitHub-用户名> --password-stdin
docker pull ghcr.io/<GitHub-用户名或组织名>/mingdao-mcp-connection-check-node:latest

通过标准输入登录可避免 Token 写入 shell 历史；Docker 会将登录凭据保存到当前用户的 Docker 配置中。Token 不能写入仓库、镜像、docker-compose.yml 或 Actions Secret。登录一次后即可执行 docker pull；如需撤销服务器访问权限，直接在 GitHub 删除该 Token。