bangtu-open-mcp

MCP-Server für die offene Bangtu-API. Er fixiert die veröffentlichten API-Verträge im Tool-Schema und in den serverseitigen Routen: Die MCP-Laufzeit greift nicht auf API-Dokumentationsseiten zu, daher hat das Abschalten der Dokumentationsseiten keinen Einfluss auf die MCP-Aufrufe veröffentlichter Schnittstellen.

Derzeit unterstützt:

• Erkennung von Basisinformationen aus DWG-Zeichnungen: DWG hochladen, Aufgabenstatus abfragen, strukturierte Ergebnisse für Rahmen und Schriftfeld abrufen

• Erkennung von Bauteilen der Disziplin Architektur: 23 Ergebnisarten wie Achsen, Räume, Türen/Fenster, Treppen, Texte, Ansichten, Schnitte und Detailzeichnungen

• Streamable HTTP MCP und SSE MCP für die Kompatibilität mit älteren Clients

Fixierte Upstream-Verträge

Der API Key gehört zu den Zugangsdaten des Aufrufers. Der MCP-Server liest, speichert und protokolliert keinen Standard-Business-API-Key; verwenden Sie in kostenpflichtigen Umgebungen für jeden Kunden einen separaten API Key.

Installation und Start

Systemvoraussetzung: Node.js 20 oder höher.

Wichtig: Bei der Verwendung von MCP gibt es zwei Wege, die nicht vermischt werden dürfen:

• Direkte Anbindung an eine vorhandene Remote-MCP: Nur den vom Dienstanbieter angegebenen MCP Endpoint eintragen; eine erneute Bereitstellung dieses Projekts ist nicht erforderlich.

• Dieses Projekt selbst bereitstellen: Code und Abhängigkeiten müssen als HTTP-Dienst bereitgestellt werden; verwenden Sie dann die von der Bereitstellungsplattform zugewiesene öffentliche Domain plus /mcp als MCP Endpoint. In diesem Fall darf die offizielle Dienstadresse einer anderen Umgebung nicht weiter eingetragen werden.

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

Unter Windows PowerShell kann Folgendes verwendet werden:

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

Produktions-Build und -Start:

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

Unter Windows PowerShell kann Folgendes verwendet werden:

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

npm start ist von den Laufzeitabhängigkeiten in node_modules abhängig. Wenn nur dist, public, package.json und package-lock.json kopiert werden, muss in diesem Verzeichnis zuerst npm ci ausgeführt werden; das Build-Artefakt ist kein in sich geschlossenes Einzeldatei-Programm.

.env.example konfiguriert nur den Dienstport, die Upstream-Basisadresse und die Polling-Parameter, nicht den Kunden-API-Key. Beim Aufruf von MCP-Tools muss der eigene apiKey des Kunden im Tool-Parameter übergeben werden. Komplexe DWG-Zeichnungen können bis zu etwa 120 Minuten dauern; BANGTU_MAX_TASK_DURATION_MINUTES kann an die tatsächliche Dienstkapazität angepasst werden.

MCP-Adressen

Direkte Anbindung an den vorhandenen offiziellen Dienst

Adressen der Produktionsumgebung:

Konfiguration für das neue Streamable HTTP (empfohlen)

Das Konfigurationsformat entspricht der offiziellen Startseite:

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

Testclient-Konfiguration

Dient zur schnellen Überprüfung von MCP-Toolaufrufen in der Testumgebung. Das Konfigurationsformat entspricht der Testclient-Konfiguration auf der Startseite:

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

Die Testkonfiguration dient nur zur Evaluierung und Integration; für den Produktivbetrieb wechseln Sie bitte zu einem exklusiven Kunden-API-Key. Der Konfigurationsname bangtu-api-test ist nur der Anzeigename im Client; die tatsächliche Verbindungsadresse wird weiterhin durch url bestimmt.

Konfiguration für Legacy SSE (ältere Version)

Wenn ältere Clients Streamable HTTP nicht unterstützen, ändern Sie die Adresse auf /sse:

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

/mcp und /sse unterscheiden sich nur im MCP-Transportprotokoll; die angebotenen Tools und fachlichen Funktionen sind identisch. Für neue Anbindungen sollte bevorzugt /mcp verwendet werden.

Lokaler Test

Nach dem Start des lokalen Dienstes gelten die folgenden Standardadressen:

Beispiel für die lokale Testclient-Konfiguration:

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

MCP-Adresse nach eigener Bereitstellung

Wenn Sie dieses Projekt auf einem Cloud-Server, einer Containerplattform oder einer anderen Hosting-Plattform bereitstellen, sollten Sie als Verbindungsadresse die von der Plattform zugewiesene öffentliche URL verwenden und /mcp anhängen, zum Beispiel:

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

Verwenden Sie nicht die Adresse der Bereitstellungsseite, die Repository-Adresse, die /health-Adresse oder die offizielle Dienstadresse einer anderen Umgebung als Ersatz für den MCP Endpoint. Prüfen Sie nach Abschluss der Bereitstellung zuerst:

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

Ich habe die Health-Check-Adresse des offiziellen Dienstes tatsächlich angefordert:

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

Der tatsächliche Rückgabewert lautet:

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

Außerdem wurde tatsächlich ein MCP-initialize-Handshake an https://mcp.bangtu-ai.com/mcp gesendet; zurückgegeben wurden HTTP/1.1 200 OK, Protokollversion 2025-06-18, Dienstname bangtu-open-api und Dienstversion 1.0.0. Das zeigt, dass der offizielle /mcp-Endpoint derzeit eine MCP-Sitzung aufbauen kann.

Health Check und MCP-Initialisierung verwenden keinen geschäftlichen apiKey; der geschäftliche apiKey wird nur beim Aufruf konkreter MCP-Tools übergeben.

Für die eigene Bereitstellung ist mindestens Folgendes erforderlich:

1. Laden Sie die vollständigen Projektdateien hoch oder verknüpfen Sie sie, einschließlich package.json, package-lock.json, src/, tsconfig.json, public/ und .env.example; verlassen Sie sich nicht auf ignorierte Dateien.

2. Abhängigkeiten installieren: npm ci.

3. Build ausführen: npm run build.

4. Starten: npm start; der Dienst lauscht auf dem von der Plattform injizierten PORT, der Port darf nicht hartkodiert werden.

5. Konfigurieren Sie die öffentliche Zugriffsadresse der Plattform als /mcp und führen Sie anschließend einen MCP-Verbindungstest durch.

Bei Remote-Bereitstellungen ist es in der Regel ungeeignet, den filePath des aufrufenden Computers direkt zu übergeben. Für DWG-Dateien sollten fileBase64 + fileName verwendet werden oder eine öffentliche fileUrl, auf die der Bereitstellungsserver zugreifen kann. .env konfiguriert nur Dienstlaufparameter und die Upstream-Basis-URL; schreiben Sie den Kunden-apiKey nicht in Umgebungsvariablen; apiKey wird weiterhin bei jedem MCP-Toolaufruf als Tool-Parameter übergeben.

Tools

DWG-Aufrufkette

1. Rufen Sie bangtu_create_dwg_task auf. Bei Remote-Agents wird empfohlen, die nach der Konvertierung des Anhangs erhaltenen fileBase64 und fileName zu übergeben; bei lokaler Bereitstellung können auch filePath oder fileUrl übergeben werden.

2. Speichern Sie die zurückgegebene data.taskId.

3. Rufen Sie für kurze Aufgaben bangtu_wait_task auf; standardmäßig wird tatsächlich mehrfach abgefragt, und pollCount, elapsedSeconds und timedOut werden zurückgegeben. Wenn data.status=RUNNING und timedOut=true zurückgegeben werden, bedeutet dies nur, dass das aktuelle Wartefenster beendet ist, keinen Fehlschlag; rufen Sie bangtu_wait_task mit derselben taskId erneut auf.

4. Bei komplexen Zeichnungen oder wenn die Tool-Timeout-Grenze der Agent-Plattform kurz ist, rufen Sie bangtu_get_task_status direkt in Abständen von etwa 3 bis 5 Sekunden wiederholt auf. Werten Sie das Ende eines einzelnen Tool-Aufrufs, ein Client-Timeout oder RUNNING nicht als Fehlschlag.

5. Wenn der Status zu SUCCESS wechselt, rufen Sie bangtu_get_frame_result auf; es wird die data[]-Liste der Rahmen zurückgegeben.

6. Wählen Sie aus den Rahmenergebnissen eine frameId aus und rufen Sie bangtu_create_cv_task({ product: "architecture", frameId }) auf, um die Architekturaufgabe zu erstellen.

7. Verwenden Sie für die Architekturaufgabe wiederholt bangtu_wait_task oder bangtu_get_task_status, bis der Status SUCCESS ist.

8. Rufen Sie bangtu_get_arch_result({ taskId, dataType }) auf, um die strukturierten Ergebnisse der Disziplin Architektur abzurufen.

Maßgeblich für den Aufgabenstatus ist data.status. Bei FAILED lesen Sie bitte data.logs; RUNNING ist kein Fehler und darf nicht wegen eines abgelaufenen Komfort-Pollings, eines durch den Client beendeten Tool-Aufrufs oder einer Nicht-Fertigstellung innerhalb kurzer Zeit als Fehlschlag gewertet werden. bangtu_wait_task ist ein synchron wartendes Tool; wenn der Client ein kürzeres Timeout für einzelne Tool-Aufrufe hat, sollte stattdessen das wiederholte bangtu_get_task_status verwendet werden.

Datei-Upload

MCP-Parameter und Upstream-Schnittstellenparameter

Die Bangtu-Upstream-Schnittstelle POST /pre/createPreTask akzeptiert weder fileBase64, fileName, filePath noch fileUrl; tatsächlich empfängt sie das Feld file als multipart/form-data.

Das aktuelle MCP-Tool definiert drei Arten von Dateiquellen:

• fileBase64 + fileName: Übertragung des Anhangsinhalts durch die Remote-Agent-Plattform; empfohlene Methode, kein Intranet-Tunneling erforderlich;

• filePath: Absoluter Pfad einer lokalen .dwg-Datei, die vom Server des MCP-Dienstes gelesen werden kann; geeignet für lokale Bereitstellung;

• fileUrl: Eine URL einer .dwg-Datei, die vom Server des MCP-Dienstes erreichbar und herunterladbar ist.

Von den drei Quellen muss genau eine ausgewählt werden. Wenn die Remote-Plattform Dateianhänge unterstützt, sollte der Agent den Anhangsinhalt in Base64 umwandeln (mit oder ohne data-URL-Präfix) und gleichzeitig den .dwg-Dateinamen übergeben:

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

Serverseitige Verarbeitungskette:

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

fileBase64, fileName, filePath und fileUrl sind Parameter der MCP-Ebene, keine Parameter der Bangtu-Upstream-API. Remote-Agents benötigen kein Intranet-Tunneling und sollten keine lokalen Pfade des aufrufenden Computers übergeben.

Architektur-Ergebnistypen

dataType von bangtu_get_arch_result unterstützt:

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

Server-Bereitstellung

Dies ist ein dauerhaft laufender Node.js-Dienst; er benötigt keine Datenbank und keinen gemounteten lokalen Speicher. DWG-Dateien werden vom MCP-Dienst temporär gelesen und an die Bangtu-API weitergeleitet; die Aufgabenergebnisse werden vom Upstream-Dienst gespeichert und abgefragt.

Anforderungen an die Konfiguration

Die Mindestkonfiguration eignet sich für Tests und geringe Aufrufmengen:

Für die Produktionsumgebung werden 2 vCPU und 2 GB Arbeitsspeicher empfohlen; skalieren Sie je nach Anzahl der gleichzeitigen Aufrufe. DWG-Analyseaufgaben werden beim Bangtu-Upstream asynchron ausgeführt; der Server selbst wird durch das Warten auf Aufgaben nicht dauerhaft stark durch die CPU belastet. Worauf Sie wirklich achten müssen, sind Bandbreite, die Anzahl gleichzeitiger Verbindungen und die Logkapazität.

Direkte Bereitstellung

Bereitstellung des vollständigen Quellcodes. Zuerst müssen die Projektabhängigkeiten installiert werden; npm run build oder npm start darf nicht direkt ausgeführt werden:

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

Wenn das Projekt eine package-lock.json enthält, kann in der Produktionsumgebung der strengere, reproduzierbare Installationsbefehl anstelle von npm install verwendet werden:

npm ci

Wenn Sie ein bereits erzeugtes Release-Verzeichnis verwenden, müssen mindestens dist/, public/, package.json, package-lock.json und .env zusammen bereitgestellt werden; führen Sie dann im Release-Verzeichnis aus:

npm ci --omit=dev
npm start

Kopieren Sie nicht nur dist/ und führen Sie dann npm start aus. Zur Laufzeit müssen Produktionsabhängigkeiten wie @modelcontextprotocol/sdk, cors, dotenv, express und zod installiert sein.

Prüfen Sie in .env mindestens die folgende Konfiguration:

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

Prüfen Sie nach dem Start des Dienstes zuerst:

curl http://127.0.0.1:3000/health

Prozessüberwachung mit PM2

Es wird empfohlen, PM2 zu verwenden, damit der Prozess nach einem unerwarteten Beenden automatisch neu gestartet wird; richten Sie außerdem den Autostart beim Systemstart ein:

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

Führen Sie nach pm2 startup den Systembefehl aus, den die Terminalausgabe angibt. Beim Aktualisieren des Codes:

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

Nginx-Reverse-Proxy

Der MCP-Dienst lauscht nur auf 127.0.0.1:3000 am lokalen Rechner; HTTPS wird von Nginx bereitgestellt. /mcp verwendet Streamable HTTP, /sse ist SSE für die Kompatibilität mit älteren Clients; beide Pfade müssen weitergeleitet werden:

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

Nach der Konfiguration verifizieren:

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

Öffnen Sie in der Produktionsumgebung Port 3000 nicht direkt. Konfigurieren Sie mindestens auf Nginx-, Cloud-Firewall- oder Gateway-Ebene HTTPS, Zugriffsauthentifizierung, Request-Rate-Limiting und Log-Maskierung. Der apiKey des Kunden ist eine geschäftliche Zugangsberechtigung, die bei jedem Toolaufruf übergeben wird; schreiben Sie ihn nicht in die serverseitige .env und protokollieren Sie ihn nicht.

Docker-Bereitstellung

Das Projekt enthält bereits ein Dockerfile. Das aktuelle Image wird wie folgt gebaut und gestartet:

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

Das vorhandene Dockerfile verwendet das Node.js-22.19.0-Basisimage; in der Build-Phase werden npm install und npm run build ausgeführt, in der Laufphase wird der Dienst mit pm2-runtime dist/index.js gestartet. .env sollte nicht in das Image geschrieben werden; beim Ausführen des Containers werden die Dienstkonfigurationen über --env-file .env oder Plattform-Umgebungsvariablen injiziert.

Der Dienstport im Container ist 3000; bei einer öffentlichen Bereitstellung sollten die Plattform oder der Reverse-Proxy an diesen Port weiterleiten und /mcp und /sse über HTTPS nach außen bereitstellen. Die Health-Check-Adresse ist /health.