bangtu-open-mcp

MCP-сервер для открытого API Bangtu. Он фиксирует опубликованные контракты API в схемах инструментов и серверных маршрутах: среда выполнения MCP не обращается к страницам документации API, поэтому отключение страниц документации не влияет на вызовы MCP для опубликованных интерфейсов.

В настоящее время поддерживается:

• Базовая идентификация чертежей DWG: загрузка DWG, запрос статуса задачи, получение структурированных результатов рамки и штампа

• Распознавание строительных компонентов: 23 типа результатов, включая оси, помещения, двери и окна, лестницы, текст, разрезы и детали

• Streamable HTTP MCP и SSE MCP для совместимости со старыми клиентами

Зафиксированные контракты вышестоящей системы

API-ключ является учётными данными вызывающей стороны. MCP-сервер не читает, не сохраняет и не выводит в журнал бизнес-API-ключ по умолчанию; в платной среде используйте отдельный API-ключ для каждого клиента.

Установка и запуск

Требования к окружению: 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-ключи. При вызове инструментов 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-ключ. Имя конфигурации 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"}

Также фактически выполнил MCP-рукопожатие initialize к https://mcp.bangtu-ai.com/mcp, получил 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 настраивает только параметры выполнения сервиса и базовый 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, это означает только завершение окна ожидания, а не сбой; вызовите bangtu_wait_task снова с тем же taskId.

4. Для сложных чертежей или при коротких ограничениях тайм-аута инструментов платформы агента повторяйте вызовы bangtu_get_task_status с интервалом примерно 3–5 секунд. Не считайте завершение одного вызова инструмента, тайм-аут клиента или статус 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 и параметры интерфейса вышестоящей системы

Интерфейс вышестоящей системы Bangtu POST /pre/createPreTask не принимает fileBase64, fileName, filePath или fileUrl; он фактически принимает поле file в формате multipart/form-data.

Текущий инструмент MCP определяет три способа источника файлов:

• fileBase64 + fileName: передача содержимого вложения с платформы удалённого агента, рекомендуемый способ, не требует проброса внутренних сетей;

• filePath: абсолютный путь к локальному файлу .dwg, который может прочитать сервер, на котором работает MCP, подходит для локального развёртывания;

• fileUrl: URL-адрес файла .dwg, доступный и загружаемый сервером, на котором работает MCP.

Необходимо выбрать ровно один из трёх источников. Если удалённая платформа поддерживает файловые вложения, агент должен преобразовать содержимое вложения в 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. Удалённому агенту не нужен проброс внутренних сетей, и он не должен передавать локальные пути с компьютера вызывающей стороны.

Типы строительных результатов

dataType для bangtu_get_arch_result поддерживает:

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 Bangtu; результаты задач сохраняются и запрашиваются вышестоящей системой.

Требования к конфигурации

Минимальная конфигурация подходит для тестирования и небольшого количества вызовов:

Для производственной среды рекомендуется 2 vCPU, 2 ГБ памяти и масштабирование в зависимости от количества одновременных вызовов. Задачи анализа DWG выполняются асинхронно на вышестоящей системе Bangtu; сам сервер не будет постоянно потреблять значительные ресурсы 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 на локальной машине, HTTPS обеспечивается Nginx. /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; при публичном развёртывании платформа или обратный прокси должны перенаправлять на этот порт и предоставлять /mcp и /sse через HTTPS. Адрес проверки работоспособности — /health.