bangtu-open-mcp

Servidor MCP para la API abierta de Bangtu. Consolida los contratos de API publicados en los esquemas de herramientas y en las rutas del servidor: el runtime de MCP no accede a las páginas de documentación de la API, por lo que la desaparición de dichas páginas no afecta a las llamadas MCP de las interfaces ya publicadas.

Actualmente soporta:

• Reconocimiento de información básica de planos DWG: subir DWG, consultar el estado de la tarea, obtener resultados estructurados de marco y sello

• Reconocimiento de componentes de arquitectura: 23 tipos de resultados como ejes, habitaciones, puertas y ventanas, escaleras, texto, secciones y detalles

• MCP Streamable HTTP y MCP SSE compatible con clientes antiguos

Contratos ascendentes consolidados

La API Key es una credencial del llamador. El servidor MCP no lee, guarda ni imprime la API Key de negocio por defecto; en entornos de pago, use una API Key independiente para cada cliente.

Instalación y arranque

Requisitos del entorno: Node.js 20 o superior.

Importante: al usar MCP hay dos formas, no se pueden mezclar:

• Conectar directamente a un MCP remoto existente: solo rellene el Endpoint MCP proporcionado por el proveedor del servicio, no necesita volver a desplegar este proyecto.

• Desplegar este proyecto usted mismo: debe desplegar el código y las dependencias como un servicio HTTP, y luego usar el dominio público asignado por la plataforma de despliegue más /mcp como Endpoint MCP. En este caso, no puede seguir rellenando la dirección de servicio formal de otros entornos.

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

Windows PowerShell puede usar:

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

Compilación de producción y arranque:

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

Windows PowerShell puede usar:

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

npm start depende de las dependencias de runtime en node_modules. Si solo copia dist, public, package.json y package-lock.json, primero debe ejecutar npm ci en ese directorio; el artefacto de compilación no es un programa autocontenido de un solo archivo.

.env.example solo configura el puerto del servicio, la URL base ascendente y los parámetros de sondeo, no configura la API Key del cliente. Al llamar a las herramientas MCP, debe pasar la apiKey del cliente en los parámetros de la herramienta. Los planos DWG complejos pueden tardar hasta unos 120 minutos; puede ajustar BANGTU_MAX_TASK_DURATION_MINUTES según la capacidad real del servicio.

Dirección MCP

Conexión directa a un servicio formal existente

Dirección del entorno de producción:

Configuración del nuevo Streamable HTTP (recomendado)

El formato de configuración es el mismo que en la página oficial:

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

Configuración del cliente de prueba

Para verificar rápidamente las llamadas a herramientas MCP en el entorno de prueba. El formato de configuración es el mismo que la configuración del cliente de prueba en la página principal:

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

La configuración de prueba solo se usa para evaluación y pruebas de integración; para uso formal, cambie a una API Key de cliente dedicada. El nombre de configuración bangtu-api-test es solo el nombre mostrado por el cliente; la dirección de conexión real sigue determinada por url.

Configuración Legacy SSE antigua

Cuando los clientes antiguos no soporten Streamable HTTP, cambie la dirección a /sse:

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

/mcp y /sse solo difieren en el protocolo de transporte MCP; las herramientas y capacidades de negocio proporcionadas son las mismas; para nuevas conexiones, use /mcp preferentemente.

Prueba local

Después de iniciar el servicio local, las direcciones por defecto son:

Ejemplo de configuración del cliente de prueba local:

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

Dirección MCP después del despliegue propio

Si despliega este proyecto en un servidor en la nube, plataforma de contenedores u otra plataforma de alojamiento, la dirección de conexión debe usar la URL pública asignada por la plataforma y añadir /mcp, por ejemplo:

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

No use la dirección de la página de despliegue, la dirección del repositorio de código, la dirección /health ni la dirección de servicio formal de otros entornos como Endpoint MCP. Después del despliegue, compruebe primero:

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

He solicitado realmente la dirección de comprobación de salud del servicio formal:

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

El valor de retorno real es:

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

También he realizado realmente el handshake MCP initialize a https://mcp.bangtu-ai.com/mcp, que devuelve HTTP/1.1 200 OK, versión de protocolo 2025-06-18, nombre del servicio bangtu-open-api, versión del servicio 1.0.0. Esto indica que el Endpoint /mcp formal puede establecer una sesión MCP actualmente.

La comprobación de salud y la fase de inicialización MCP no usan la apiKey de negocio; la apiKey de negocio solo se pasa al llamar a herramientas MCP específicas.

El despliegue propio requiere al menos:

1. Subir o asociar los archivos completos del proyecto, incluyendo package.json, package-lock.json, src/, tsconfig.json, public/ y .env.example; no dependa de archivos ignorados.

2. Instalar dependencias: npm ci.

3. Compilar: npm run build.

4. Iniciar: npm start, el servicio escucha en el PORT inyectado por la plataforma, no fije el puerto.

5. Configurar la dirección de acceso público de la plataforma como /mcp, y luego ejecutar la prueba de conexión MCP.

El despliegue remoto generalmente no es adecuado para pasar filePath de la computadora del llamador directamente. Los archivos DWG deben usar fileBase64 + fileName, o usar una fileUrl pública que el servidor de despliegue pueda acceder. .env solo configura los parámetros de ejecución del servicio y la URL base ascendente; no escriba la apiKey del cliente en variables de entorno; la apiKey sigue pasándose como parámetro de herramienta en cada llamada MCP.

Herramientas

Cadena de llamadas DWG

1. Llame a bangtu_create_dwg_task. Para agentes remotos, se recomienda pasar el fileBase64 y fileName convertidos del adjunto; en despliegue local también puede pasar filePath o fileUrl.

2. Guarde el data.taskId devuelto.

3. Para tareas cortas, llame a bangtu_wait_task, que por defecto consulta varias veces y devuelve pollCount, elapsedSeconds y timedOut. Si devuelve data.status=RUNNING y timedOut=true, solo indica que la ventana de espera actual terminó, no un fallo; use el mismo taskId para llamar a bangtu_wait_task de nuevo.

4. Para planos complejos o cuando el límite de tiempo de herramienta de la plataforma de agentes es corto, repita bangtu_get_task_status a intervalos de aproximadamente 3 a 5 segundos. No considere el fin de una llamada de herramienta, el timeout del cliente o RUNNING como un fallo.

5. Cuando el estado cambie a SUCCESS, llame a bangtu_get_frame_result, que devuelve la lista de marcos data[].

6. Seleccione frameId de los resultados de marco, llame a bangtu_create_cv_task({ product: "architecture", frameId }) para crear la tarea de arquitectura.

7. Para la tarea de arquitectura, repita bangtu_wait_task o bangtu_get_task_status hasta que el estado sea SUCCESS.

8. Llame a bangtu_get_arch_result({ taskId, dataType }) para obtener los resultados estructurados de arquitectura.

El estado de la tarea se basa en data.status. Si es FAILED, lea data.logs; RUNNING no es un error, no lo considere un fallo por timeout de sondeo conveniente, fin de llamada de herramienta del cliente o no completarse en poco tiempo. bangtu_wait_task es una herramienta de espera síncrona; si el cliente tiene un timeout de herramienta más corto, use bangtu_get_task_status repetido.

Subida de archivos

Parámetros MCP y parámetros de la interfaz ascendente

La interfaz ascendente de Bangtu POST /pre/createPreTask no recibe fileBase64, fileName, filePath ni fileUrl; realmente recibe el campo file de multipart/form-data.

La herramienta MCP actual define tres formas de origen de archivo:

• fileBase64 + fileName: la plataforma de agentes remotos pasa el contenido del adjunto, forma recomendada, no requiere túnel de red interna;

• filePath: ruta absoluta local del archivo .dwg que el servidor MCP puede leer, adecuada para despliegue local;

• fileUrl: URL del archivo .dwg que el servidor MCP puede acceder y descargar.

Las tres formas deben elegir exactamente una. Cuando la plataforma remota soporta adjuntos de archivo, el agente debe convertir el contenido del adjunto a Base64 (con o sin prefijo data URL), y pasar también el nombre del archivo .dwg:

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

Cadena de procesamiento del servidor:

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

fileBase64, fileName, filePath y fileUrl son parámetros de la capa MCP, no parámetros de la API ascendente de Bangtu. Los agentes remotos no necesitan túnel de red interna, ni deben pasar rutas locales de la computadora del llamador.

Tipos de resultados de arquitectura

dataType de bangtu_get_arch_result soporta:

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

Despliegue del servidor

Es un servicio Node.js residente, no necesita base de datos ni almacenamiento local montado. Los archivos DWG son leídos temporalmente por el servicio MCP y reenviados a la API de Bangtu; los resultados de las tareas son guardados y consultados por el servicio ascendente.

Requisitos de configuración

La configuración mínima es adecuada para pruebas y pocas llamadas:

Para producción, se recomienda 2 vCPU, 2 GB de memoria, y escalar según el volumen de llamadas concurrentes. Las tareas de análisis DWG se ejecutan asíncronamente en el servicio ascendente de Bangtu; el servidor no consume mucha CPU continuamente por esperar tareas; lo que realmente importa es el ancho de banda, las conexiones concurrentes y la capacidad de registros.

Despliegue directo

Despliegue del código fuente completo. Primero debe instalar las dependencias del proyecto, no ejecute directamente npm run build o 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

Si el proyecto incluye package-lock.json, en producción también puede usar un comando de instalación más estricto y reproducible en lugar de npm install:

npm ci

Si usa un directorio de publicación ya generado, al menos debe proporcionar dist/, public/, package.json, package-lock.json y .env, y luego ejecutar en el directorio de publicación:

npm ci --omit=dev
npm start

No copie solo dist/ y ejecute npm start. El runtime necesita instalar dependencias de producción como @modelcontextprotocol/sdk, cors, dotenv, express y zod.

.env al menos confirme la siguiente configuración:

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

Después de iniciar el servicio, compruebe primero:

curl http://127.0.0.1:3000/health

Uso de PM2 para supervisión

Se recomienda usar PM2 para reiniciar automáticamente el proceso si sale anormalmente, y configurar el arranque al inicio:

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

Después de ejecutar pm2 startup, ejecute el comando del sistema que muestra en la salida del terminal. Al actualizar el código:

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

Proxy inverso Nginx

El servicio MCP solo escucha en 127.0.0.1:3000 local, y Nginx proporciona HTTPS. /mcp usa Streamable HTTP, /sse es SSE para compatibilidad con clientes antiguos, ambos caminos deben reenviarse:

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

Después de configurar, verifique:

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

En producción, no abra directamente el puerto 3000. Al menos configure HTTPS, autenticación de acceso, limitación de solicitudes y desidentificación de registros en Nginx, firewall en la nube o capa de puerta de enlace. La apiKey del cliente es una credencial de negocio pasada en cada llamada de herramienta, no la escriba en .env del servidor ni la imprima en registros.

Despliegue Docker

El proyecto ya proporciona Dockerfile. La forma actual de construir la imagen y arrancar es:

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

El Dockerfile actual usa la imagen base Node.js 22.19.0, la fase de construcción ejecuta npm install y npm run build, y la fase de ejecución usa pm2-runtime dist/index.js para iniciar el servicio. .env no debe escribirse en la imagen; al ejecutar el contenedor, inyecte la configuración del servicio mediante --env-file .env o variables de entorno de la plataforma.

El puerto interno del contenedor es 3000; en despliegue público, la plataforma o el proxy inverso deben reenviar a ese puerto y usar HTTPS para exponer /mcp y /sse. La dirección de comprobación de salud es /health.