bangtu-open-mcp

帮图オープンAPIのMCPサーバーです。公開済みのAPI契約をツールスキーマとサーバーサイドルーティングに固定化しています：MCPランタイムはAPIドキュメントページにアクセスしません。そのため、ドキュメントページがオフラインになっても、公開済みインターフェースのMCP呼び出しには影響しません。

現在対応している機能：

• DWG図面基本情報認識：DWGのアップロード、タスク状態の照会、図枠と図簽の構造化結果の取得

• 建築専門部材認識：軸番号、部屋、ドア・窓、階段、文字、立面・断面・詳細図など23種類の結果

• Streamable HTTP MCP および旧クライアント互換のSSE MCP

固定化された上流契約

API Keyは呼び出し側の認証情報です。MCPサーバーはデフォルトの業務API Keyを読み取らず、保存せず、出力しません。有料環境では、顧客ごとに独立したAPI Keyを使用してください。

インストールと起動

環境要件：Node.js 20 以上。

重要：MCPを使用する際には2つの方法があり、混在させることはできません。

• 既存のリモートMCPに直接接続：サービス提供者が指定したMCPエンドポイントのみを入力し、本プロジェクトを再デプロイする必要はありません。

• 本プロジェクトを自前でデプロイ：コードと依存関係をHTTPサービスとしてデプロイし、デプロイプラットフォームが割り当てた公開ドメインに /mcp を追加したものをMCPエンドポイントとして使用します。この場合、他の環境の正式サービスアドレスを入力し続けることはできません。

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エンドポイントの代わりに使用しないでください。デプロイ完了後、まず確認してください：

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 エンドポイントが現在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 にはサービス実行パラメータと上流のベースURLのみを設定し、顧客の apiKey を環境変数に書き込まないでください。apiKey は引き続き各MCPツール呼び出しのツールパラメータとして渡されます。

ツール

DWG呼び出しチェーン

1. bangtu_create_dwg_task を呼び出します。リモートエージェントでは、添付ファイルを変換した fileBase64 と fileName を渡すことを推奨します。ローカルデプロイでは filePath や fileUrl も渡せます。

2. 返された data.taskId を保存します。

3. 短いタスクには bangtu_wait_task を呼び出します。デフォルトで実際に複数回照会し、pollCount、elapsedSeconds、timedOut を返します。data.status=RUNNING かつ timedOut=true が返された場合、それは今回の待機ウィンドウが終了したことを示すだけで、失敗を意味しません。同じ taskId で再度 bangtu_wait_task を呼び出してください。

4. 複雑な図面や、エージェントプラットフォームのツールタイムアウト制限が短い場合は、約3〜5秒間隔で bangtu_get_task_status を繰り返し呼び出します。1回のツール呼び出しの終了、クライアントのタイムアウト、または RUNNING を失敗と判定しないでください。

5. 状態が SUCCESS になったら、bangtu_get_frame_result を呼び出し、data[] の図枠リストを取得します。

6. 図枠結果から frameId を選択し、bangtu_create_cv_task({ product: "architecture", frameId }) を呼び出して建築タスクを作成します。

7. 建築タスクに対して、状態が SUCCESS になるまで bangtu_wait_task または bangtu_get_task_status を繰り返し使用します。

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ツールでは、3つのファイルソース方法が定義されています：

• fileBase64 + fileName：リモートエージェントプラットフォームが添付ファイルの内容を渡します。推奨方法で、イントラネットの穴あけは不要です。

• filePath：MCPサービスが動作するサーバーが読み取れるローカルの .dwg ファイルの絶対パス。ローカルデプロイに適しています。

• fileUrl：MCPサービスが動作するサーバーがアクセス・ダウンロードできる .dwg ファイルのURL。

3つのソースは、必ず1つだけ選択する必要があります。リモートプラットフォームがファイル添付をサポートしている場合、エージェントは添付ファイルの内容を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パラメータではありません。リモートエージェントはイントラネットの穴あけを必要とせず、呼び出し元コンピューターのローカルパスを渡すべきでもありません。

建築結果タイプ

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 です。