bangtu-open-mcp

MCP Server for the Bangtu Open API. It fixes the published API contract in tool schemas and server-side routes: the MCP runtime never accesses the API documentation pages, so the documentation pages going offline does not affect MCP calls to already published interfaces.

Currently supported:

• DWG drawing basic information recognition: upload DWG, query task status, get structured frame and title block results

• Architectural component recognition: 23 types of results including axis numbers, rooms, doors and windows, stairs, text, elevations, sections, and detail drawings

• Streamable HTTP MCP and SSE MCP for compatibility with older clients

Fixed upstream contract

The API Key is the caller's credential. The MCP server does not read, save, or print the default business API Key; in a paid environment, use a separate API Key for each customer.

Installation and startup

Environment requirements: Node.js 20 or higher.

Important: there are two ways to use MCP, and they cannot be mixed:

• Connect directly to an existing remote MCP: only fill in the MCP Endpoint provided by the service provider; no need to redeploy this project.

• Deploy this project yourself: you need to deploy the code and dependencies as an HTTP service, then use the public domain name assigned by the deployment platform plus /mcp as the MCP Endpoint. In this case, you cannot continue to fill in the official service address of another environment.

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

Windows PowerShell can use:

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

Production build and startup:

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

Windows PowerShell can use:

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

npm start depends on the runtime dependencies in node_modules. After copying only dist, public, package.json, and package-lock.json, you must run npm ci in that directory first; the build output is not a self-contained single-file program.

.env.example only configures the service port, upstream base URL, and polling parameters; it does not configure customer API Keys. When calling MCP tools, you must pass the customer's own apiKey in the tool parameters. Complex DWG drawings may take up to about 120 minutes; you can adjust BANGTU_MAX_TASK_DURATION_MINUTES according to your actual service capacity.

MCP addresses

Connect directly to an existing official service

Production environment addresses:

New Streamable HTTP configuration (recommended)

The configuration format is the same as on the official homepage:

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

Test client configuration

Used for quickly verifying MCP tool calls in a test environment. The configuration format is the same as the test client configuration on the homepage:

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

The test configuration is only for evaluation and integration testing; switch to a dedicated customer API Key for production use. The configuration name bangtu-api-test is only the client display name; the actual connection address is still determined by url.

Legacy SSE configuration

When older clients do not support Streamable HTTP, change the address to /sse:

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

/mcp and /sse differ only in the MCP transport protocol; they provide the same tools and business capabilities. For new integrations, prefer /mcp.

Local testing

After starting the local service, the default addresses are as follows:

Example local test client configuration:

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

MCP address after self-deployment

If you deploy this project to a cloud server, container platform, or other hosting platform, the connection address should use the public URL assigned by the platform, with /mcp appended, for example:

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

Do not use the deployment page address, code repository address, /health address, or the official service address of another environment as the MCP Endpoint. After deployment, first check:

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

I have actually requested the health check address of the official service:

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

The actual return value is:

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

I have also actually initiated an MCP initialize handshake against https://mcp.bangtu-ai.com/mcp, which returned HTTP/1.1 200 OK, with protocol version 2025-06-18, service name bangtu-open-api, and service version 1.0.0. This shows that the official /mcp Endpoint can currently establish an MCP session.

The health check and MCP initialization phases do not use the business apiKey; the business apiKey is only passed in when calling specific MCP tools.

Self-deployment requires at least:

1. Upload or link the complete project files, including package.json, package-lock.json, src/, tsconfig.json, public/, and .env.example; do not rely on ignored files.

2. Install dependencies: npm ci.

3. Build: npm run build.

4. Start: npm start. The service listens on the platform-injected PORT; do not hard-code the port.

5. Configure the platform's public access address as /mcp, then run the MCP connection test.

Remote deployment is generally not suitable for passing the caller's computer's filePath directly. DWG files should use fileBase64 + fileName, or use a public fileUrl that the deployment server can access. .env only configures service runtime parameters and the upstream Base URL; do not write customer apiKey into environment variables; apiKey is still passed in as a tool parameter for each MCP tool call.

Tools

DWG call chain

1. Call bangtu_create_dwg_task. For remote Agents, it is recommended to pass the attachment converted to fileBase64 and fileName; for local deployment, you can also pass filePath or fileUrl.

2. Save the returned data.taskId.

3. For short tasks, call bangtu_wait_task. By default it actually queries multiple times and returns pollCount, elapsedSeconds, and timedOut. If the return has data.status=RUNNING and timedOut=true, it only means this waiting window has ended, not that it failed; call bangtu_wait_task again with the same taskId.

4. For complex drawings or when the Agent platform's tool timeout limit is short, directly call bangtu_get_task_status repeatedly at intervals of about 3 to 5 seconds. Do not treat the end of a single tool call, a client timeout, or RUNNING as a failure.

5. When the status changes to SUCCESS, call bangtu_get_frame_result, which returns the data[] frame list.

6. Select a frameId from the frame results and call bangtu_create_cv_task({ product: "architecture", frameId }) to create an architectural task.

7. For the architectural task, repeatedly use bangtu_wait_task or bangtu_get_task_status until the status is SUCCESS.

8. Call bangtu_get_arch_result({ taskId, dataType }) to get the structured architectural results.

The task status is determined by data.status. When FAILED, read data.logs; RUNNING is not an error and must not be treated as a failure due to a convenient polling timeout, the client ending the tool call, or not completing within a short time. bangtu_wait_task is a synchronous waiting tool; if the client has a shorter single tool timeout, switch to repeated bangtu_get_task_status calls.

File upload

MCP parameters and upstream interface parameters

The Bangtu upstream interface POST /pre/createPreTask does not accept fileBase64, fileName, filePath, or fileUrl; what it actually accepts is the file field of multipart/form-data.

The current MCP tool defines three file source methods:

• fileBase64 + fileName: the remote Agent platform passes attachment content; recommended method, no need for intranet tunneling;

• filePath: an absolute path to a local .dwg file readable by the server where the MCP service runs; suitable for local deployment;

• fileUrl: a URL to a .dwg file that is accessible and downloadable from the server where the MCP service runs.

Exactly one of the three sources must be selected. When the remote platform supports file attachments, the Agent should convert the attachment content to Base64 (with or without the data URL prefix) and pass the .dwg file name at the same time:

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

Server-side processing chain:

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

fileBase64, fileName, filePath, and fileUrl are MCP-layer parameters, not Bangtu upstream API parameters. Remote Agents do not need intranet tunneling and should not pass local paths on the caller's computer.

Architectural result types

The dataType of bangtu_get_arch_result supports:

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

Server deployment

This is a Node.js resident service; it does not need a database and does not need to mount local storage. DWG files are temporarily read by the MCP service and forwarded to the Bangtu API; task results are saved and queried by the upstream service.

Configuration requirements

The minimum configuration is suitable for testing and light usage:

For production, 2 vCPU and 2 GB memory are recommended, with scaling based on concurrent call volume. DWG parsing tasks run asynchronously on the Bangtu upstream, so the server itself does not continuously consume significant CPU while waiting for tasks; what really matters is bandwidth, concurrent connections, and log capacity.

Direct deployment

Full source deployment. You must install project dependencies first; you cannot run npm run build or npm start directly:

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

If the project includes package-lock.json, you can also use a stricter, reproducible install command in production to replace npm install:

npm ci

If you use an already generated release directory, you need to provide at least dist/, public/, package.json, package-lock.json, and .env together, then run in the release directory:

npm ci --omit=dev
npm start

Do not copy only dist/ and then run npm start. The runtime requires production dependencies such as @modelcontextprotocol/sdk, cors, dotenv, express, and zod to be installed.

At minimum, confirm the following configuration in .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

After the service starts, first check:

curl http://127.0.0.1:3000/health

Using PM2 for process management

PM2 is recommended to ensure automatic restart after abnormal process exit and to set up startup on boot:

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

After running pm2 startup, execute the system command it outputs in the terminal. When updating code:

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

Nginx reverse proxy

The MCP service only listens on the local 127.0.0.1:3000, with Nginx providing HTTPS. /mcp uses Streamable HTTP, and /sse is SSE for compatibility with older clients; both paths must be forwarded:

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;
    }
}

Verify after configuration:

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

Do not expose port 3000 directly in production. At minimum, configure HTTPS, access authentication, request rate limiting, and log redaction at the Nginx, cloud firewall, or gateway layer. The customer's apiKey is the business credential passed in with each tool call; do not write it into the server-side .env or print it to logs.

Docker deployment

The project provides a Dockerfile. The current image build and startup method is as follows:

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

The existing Dockerfile uses the Node.js 22.19.0 base image, runs npm install and npm run build in the build stage, and starts the service with pm2-runtime dist/index.js in the runtime stage. .env should not be baked into the image; inject service configuration at container runtime via --env-file .env or platform environment variables.

The internal service port in the container is 3000. For public deployment, forward the platform or reverse proxy to this port and expose /mcp and /sse over HTTPS. The health check address is /health.