# 明道云 MCP 中转（Node.js）

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

## 本地启动

```bash
npm ci
npm start
```

验证：

```bash
curl http://127.0.0.1:8001/health
```

## Docker 部署

在仓库根目录构建镜像：

```bash
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` 版本：

```bash
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
```

上传到服务器后加载：

```bash
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` 同时使用。

运行容器：

```bash
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 用户名或组织名：

```bash
cp .env.example .env
```

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

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

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

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

使用仓库内的 [`deploy/nginx.conf.example`](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 个工具：

```env
MINGDAO_TOOL_OFFSET=0
MINGDAO_TOOL_LIMIT=34
```

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

```env
MINGDAO_TOOL_OFFSET=34
MINGDAO_TOOL_LIMIT=17
```

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

### Coze 工具兼容规则

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

```env
MINGDAO_EXCLUDED_TOOLS=batch_create_process_nodes,create_process
```

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

修改 `.env` 后执行：

```bash
docker compose up -d --force-recreate
```

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

## GitHub Actions 自动发布

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

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

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

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

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

```bash
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。