bangtu-open-mcp

帮图开放 API 的 MCP Server。它把已发布的 API 契约固化在工具 schema 和服务端路由中：MCP 运行时不会访问 API 文档页面，因此文档页面下线不影响已发布接口的 MCP 调用。

当前支持：

• DWG 图纸基本信息识别：上传 DWG、查询任务状态、获取图框和图签结构化结果

• 建筑专业构件识别：轴号、房间、门窗、楼梯、文字、立剖面和详图等 23 类结果

• Streamable HTTP MCP 和兼容旧客户端的 SSE MCP

已固化的上游契约

API Key 属于调用方凭证。MCP 服务端不读取、不保存、不打印默认业务 API Key；收费环境请为每个客户使用独立 API Key。

安装与启动

环境要求：Node.js 20 或更高版本。

重要：使用 MCP 时有两种方式，不能混用：

• 直接接入已有远程 MCP：只填写服务提供方给出的 MCP Endpoint，不需要重新部署本项目。

• 自行部署本项目：需要把代码和依赖部署成一个 HTTP 服务，再使用部署平台分配的公网域名加 /mcp 作为 MCP Endpoint。此时不能继续填写其他环境的正式服务地址。

npm install
cp .env.example .env
npm run dev

Windows PowerShell 可使用：

npm install
Copy-Item .env.example .env
npm run dev

生产构建与启动：

npm ci
npm run build
cp .env.example .env
npm start

Windows PowerShell 可使用：

npm ci
npm run build
Copy-Item .env.example .env
npm start

npm start 依赖 node_modules 中的运行时依赖。仅复制 dist、public、package.json 和 package-lock.json 后，必须先在该目录执行 npm ci；构建产物不是自包含的单文件程序。

.env.example 只配置服务端口、上游基础地址和轮询参数，不配置客户 API Key。调用 MCP 工具时，必须在工具参数中传入客户自己的 apiKey。复杂 DWG 图纸最长可能需约 120 分钟，可按实际服务能力调整 BANGTU_MAX_TASK_DURATION_MINUTES。

MCP 地址

直接接入已有正式服务

生产环境地址：

新版 Streamable HTTP 配置（推荐）

配置格式与官方主页一致：

{
  "mcpServers": {
    "bangtu-api": {
      "url": "https://mcp.bangtu-ai.com/mcp",
      "apiKey": "请填入您的apiKey"
    }
  }
}

测试客户端配置

用于测试环境快速验证 MCP 工具调用。配置格式与主页中的测试客户端配置一致：

{
  "mcpServers": {
    "bangtu-api-test": {
      "url": "https://mcp.bangtu-ai.com/mcp",
      "apiKey": "btzlbnfhwr1dkndirgq5h6gy3838b8rh"
    }
  }
}

测试配置仅用于评估和联调，正式使用请切换为专属客户 API Key。配置名称 bangtu-api-test 只是客户端显示名称，实际连接地址仍由 url 决定。

旧版 Legacy SSE 配置

旧客户端不支持 Streamable HTTP 时，将地址改为 /sse：

{
  "mcpServers": {
    "bangtu-api": {
      "url": "https://mcp.bangtu-ai.com/sse",
      "apiKey": "请填入您的apiKey"
    }
  }
}

/mcp 与 /sse 只是 MCP 传输协议不同，提供的工具和业务能力相同；新接入优先使用 /mcp。

本地测试

启动本地服务后，默认地址如下：

本地测试客户端配置示例：

{
  "mcpServers": {
    "bangtu-local": {
      "url": "http://localhost:3000/mcp",
      "apiKey": "请填入您的apiKey"
    }
  }
}

自行部署后的 MCP 地址

如果你把本项目部署到云服务器、容器平台或其他托管平台，连接地址应使用平台分配的公网 URL，并追加 /mcp，例如：

https://<你的服务域名>/mcp

不要使用部署页面地址、代码仓库地址、/health 地址或其他环境的正式服务地址代替 MCP Endpoint。部署完成后先检查：

https://<你的服务域名>/health

我已实际请求正式服务的健康检查地址：

GET https://mcp.bangtu-ai.com/health
HTTP/1.1 200 OK

实际返回值为：

{"ok":true,"service":"bangtu-open-api-mcp","version":"1.0.0"}

也已实际向 https://mcp.bangtu-ai.com/mcp 发起 MCP initialize 握手，返回 HTTP/1.1 200 OK，协议版本为 2025-06-18，服务名称为 bangtu-open-api，服务版本为 1.0.0。这说明正式 /mcp Endpoint 当前可以建立 MCP 会话。

健康检查和 MCP 初始化阶段不使用业务 apiKey；业务 apiKey 只在调用具体 MCP 工具时传入。

自行部署至少需要：

1. 上传或关联完整项目文件，包括 package.json、package-lock.json、src/、tsconfig.json、public/ 和 .env.example；不要依赖被忽略的文件。

2. 安装依赖：npm ci。

3. 构建：npm run build。

4. 启动：npm start，服务监听平台注入的 PORT，不要把端口写死。

5. 将平台公网访问地址配置为 /mcp，再执行 MCP 连接测试。

远程部署通常不适合直接传调用方电脑的 filePath。DWG 文件应使用 fileBase64 + fileName，或使用部署服务器能够访问的公网 fileUrl。.env 只配置服务运行参数和上游 Base URL，不要把客户 apiKey 写入环境变量；apiKey 仍然作为每次 MCP 工具调用的工具参数传入。

工具

DWG 调用链

1. 调用 bangtu_create_dwg_task。远程 Agent 推荐传入附件转换后的 fileBase64 和 fileName；本地部署也可传 filePath 或 fileUrl。

2. 保存返回的 data.taskId。

3. 对短任务调用 bangtu_wait_task，默认会实际查询多次并返回 pollCount、elapsedSeconds 和 timedOut。若返回 data.status=RUNNING 且 timedOut=true，只表示本次等待窗口结束，不表示失败；使用同一个 taskId 再次调用 bangtu_wait_task。

4. 复杂图纸或 Agent 平台工具超时限制较短时，直接按约 3 至 5 秒间隔重复调用 bangtu_get_task_status。不要把一次工具调用结束、客户端超时或 RUNNING 判定为失败。

5. 当状态变为 SUCCESS，调用 bangtu_get_frame_result，返回 data[] 图框列表。

6. 从图框结果中选择 frameId，调用 bangtu_create_cv_task({ product: "architecture", frameId }) 创建建筑任务。

7. 对建筑任务重复使用 bangtu_wait_task 或 bangtu_get_task_status，直到状态为 SUCCESS。

8. 调用 bangtu_get_arch_result({ taskId, dataType }) 获取建筑专业结构化结果。

任务状态以 data.status 为准。FAILED 时请读取 data.logs；RUNNING 不是错误，不能因便捷轮询超时、客户端结束工具调用或短时间内未完成而视为失败。bangtu_wait_task 是同步等待式工具，客户端若有更短的单次工具超时，应改用重复的 bangtu_get_task_status。

文件上传

MCP 参数与上游接口参数

帮图上游接口 POST /pre/createPreTask 不接收 fileBase64、fileName、filePath 或 fileUrl，它真正接收的是 multipart/form-data 的 file 字段。

当前 MCP 工具定义了三种文件来源方式：

• fileBase64 + fileName：远程 Agent 平台传递附件内容，推荐方式，不需要内网穿透；

• filePath：MCP 服务所在服务器可读取的本地 .dwg 文件绝对路径，适合本地部署；

• fileUrl：MCP 服务所在服务器可访问且可下载的 .dwg 文件 URL。

三种来源必须且只能选择一种。远程平台支持文件附件时，Agent 应将附件内容转换为 Base64（不含或包含 data URL 前缀均可），同时传入 .dwg 文件名：

{
  "apiKey": "你的客户API Key",
  "fileBase64": "<DWG 文件的 Base64 内容>",
  "fileName": "drawing.dwg"
}

服务端处理链路：

第三方平台附件
    -> Agent 传 fileBase64 + fileName
    -> MCP 服务在内存中还原 DWG 文件
    -> 构造 multipart/form-data
    -> 以 file 字段上传到帮图 API

fileBase64、fileName、filePath 和 fileUrl 是 MCP 层参数，不是帮图上游 API 参数。远程 Agent 不需要内网穿透，也不应传调用方电脑上的本地路径。

建筑结果类型

bangtu_get_arch_result 的 dataType 支持：

axisNumber, indexNumber, texts, textelvation, arrows, alignedDims, subFrame,
planRoom, planStair, planLift, planDoor, planWindow, facadeStorey,
sectionStorey, stairPlanDetWall, stairPlanDetSeg, stairPlanDetPlatform,
stairPlanDetRail, stairSecDetPlatform, stairSecDetSeg, wallDetContour,
doorWinDetail, doorWinTable

服务器部署

这是一个 Node.js 常驻服务，不需要数据库，也不需要挂载本地存储。DWG 文件由 MCP 服务临时读取并转发给帮图 API，任务结果由上游服务保存和查询。

配置要求

最低配置适合测试和少量调用：

生产环境建议使用 2 vCPU、2 GB 内存，并根据并发调用量扩容。DWG 解析任务在帮图上游异步执行，服务器本身不会因为等待任务而持续占用大量 CPU；真正需要关注的是带宽、并发连接数和日志容量。

直接部署

完整源码部署。必须先安装项目依赖，不能直接执行 npm run build 或 npm start：

# 服务器安装 Node.js 20+
git clone <你的代码仓库地址> bangtu-open-mcp
cd bangtu-open-mcp
npm install
cp .env.example .env
npm run build
npm start

如果项目中包含 package-lock.json，生产环境也可以使用更严格、可复现的安装命令替换 npm install：

npm ci

如果使用已经生成好的发布目录，至少需要一起提供 dist/、public/、package.json、package-lock.json 和 .env，然后在发布目录执行：

npm ci --omit=dev
npm start

不要只复制 dist/ 后执行 npm start。运行时需要安装 @modelcontextprotocol/sdk、cors、dotenv、express 和 zod 等生产依赖。

.env 至少确认以下配置：

PORT=3000
HOST=127.0.0.1
BANGTU_API_BASE_URL=https://openapi.bangtu-ai.com/openApi/
BANGTU_POLL_INTERVAL_MS=5000
BANGTU_MAX_TASK_DURATION_MINUTES=120
BANGTU_DEFAULT_WAIT_SECONDS=20
BANGTU_MAX_WAIT_SECONDS=45

服务启动后先检查：

curl http://127.0.0.1:3000/health

使用 PM2 守护

推荐用 PM2 保证进程异常退出后自动重启，并设置开机启动：

npm install -g pm2
pm2 start dist/index.js --name bangtu-open-mcp
pm2 save
pm2 startup
pm2 logs bangtu-open-mcp

执行 pm2 startup 后，按照终端输出执行它给出的那条系统命令。更新代码时：

npm ci
npm run build
pm2 restart bangtu-open-mcp

Nginx 反向代理

MCP 服务只监听本机 127.0.0.1:3000，由 Nginx 提供 HTTPS。/mcp 使用 Streamable HTTP，/sse 为兼容旧客户端的 SSE，两个路径都要转发：

server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 7200s;
        proxy_send_timeout 7200s;
    }
}

配置后验证：

curl https://mcp.example.com/health

生产环境不要直接开放 3000 端口。至少应在 Nginx、云防火墙或网关层配置 HTTPS、访问认证、请求限流和日志脱敏。客户的 apiKey 是每次工具调用传入的业务凭证，不要写入服务端 .env，也不要打印到日志。

Docker 部署

项目已提供 Dockerfile。当前镜像构建和启动方式如下：

docker build -t bangtu-open-mcp .
docker run -d --name bangtu-open-mcp -p 3000:3000 --env-file .env bangtu-open-mcp

现有 Dockerfile 使用 Node.js 22.19.0 基础镜像，构建阶段执行 npm install 和 npm run build，运行阶段使用 pm2-runtime dist/index.js 启动服务。.env 不应写入镜像，运行容器时通过 --env-file .env 或平台环境变量注入服务配置。

容器内部服务端口为 3000，公网部署时应将平台或反向代理转发到该端口，并使用 HTTPS 对外提供 /mcp 和 /sse。健康检查地址为 /health。