bangtu-open-mcp

帮图 공개 API용 MCP Server입니다. 공개된 API 계약을 도구 스키마와 서버 측 라우팅에 고정합니다: MCP 런타임은 API 문서 페이지에 접근하지 않으므로, 문서 페이지가 내려가더라도 공개된 인터페이스의 MCP 호출에는 영향을 주지 않습니다.

현재 지원:

• DWG 도면 기본 정보 인식: DWG 업로드, 작업 상태 조회, 도곽 및 도장(圖章) 구조화 결과 획득

• 건축 전문 구성요소 인식: 축번호, 실(방), 문/창, 계단, 문자, 입단면 및 상세도 등 23종 결과

• Streamable HTTP MCP 및 구형 클라이언트 호환 SSE MCP

고정된 상위(上游) 계약

API Key는 호출자의 자격 증명입니다. MCP 서버는 기본 비즈니스 API Key를 읽지 않고, 저장하지 않으며, 출력하지 않습니다. 유료 환경에서는 고객별로 별도의 API Key를 사용하십시오.

설치 및 시작

환경 요구사항: 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 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 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"}

또한 https://mcp.bangtu-ai.com/mcp에 실제로 MCP initialize 핸드셰이크를 수행하여 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에는 서비스 실행 파라미터와 상위 Base URL만 설정하고, 고객 apiKey를 환경 변수에 기록하지 마십시오. apiKey는 여전히 매번 MCP 도구 호출 시 도구 파라미터로 전달됩니다.

도구

DWG 호출 체인

1. bangtu_create_dwg_task를 호출합니다. 원격 Agent는 첨부 파일을 변환한 fileBase64와 fileName을 전달하는 것을 권장하며, 로컬 배포 시 filePath 또는 fileUrl도 전달할 수 있습니다.

2. 반환된 data.taskId를 저장합니다.

3. 짧은 작업의 경우 bangtu_wait_task를 호출하며, 기본적으로 실제로 여러 번 조회하고 pollCount, elapsedSeconds, timedOut을 반환합니다. data.status=RUNNING이고 timedOut=true가 반환되면 이는 이번 대기 창이 끝났다는 의미일 뿐 실패를 의미하지 않습니다. 동일한 taskId로 bangtu_wait_task를 다시 호출하십시오.

4. 복잡한 도면이거나 Agent 플랫폼의 도구 타임아웃 제한이 짧은 경우, 약 3~5초 간격으로 bangtu_get_task_status를 반복 호출합니다. 한 번의 도구 호출 종료, 클라이언트 타임아웃 또는 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 도구는 세 가지 파일 소스 방식을 정의합니다:

• fileBase64 + fileName: 원격 Agent 플랫폼이 첨부 파일 내용을 전달하는 방식으로, 내트워크 터널링이 필요 없어 권장됩니다.

• filePath: MCP 서버가 있는 서버에서 읽을 수 있는 로컬 .dwg 파일의 절대 경로로, 로컬 배포에 적합합니다.

• fileUrl: MCP 서버가 있는 서버에서 접근 및 다운로드 가능한 .dwg 파일 URL.

세 가지 소스는 반드시 하나만 선택해야 합니다. 원격 플랫폼이 파일 첨부를 지원하는 경우, Agent는 첨부 파일 내용을 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 파라미터가 아닙니다. 원격 Agent는 내트워크 터널링이 필요 없으며, 호출자 컴퓨터의 로컬 경로를 전달해서도 안 됩니다.

건축 결과 유형

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만 수신하며, 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이며, 공개 배포 시 플랫폼 또는 리버스 프록시가 해당 포트로 전달하도록 하고 HTTPS로 /mcp와 /sse를 외부에 제공해야 합니다. 헬스 체크 주소는 /health입니다.