BULC MCP

한국어

무엇인가

BULC MCP 는 Model Context Protocol 서버입니다. Claude Desktop, Claude Code, Cursor, VS Code 같은 MCP 클라이언트의 AI 가 이 PC 에서 실행 중인 BULC 데스크톱 앱(FDS 6.10.1 기반 GPU 화재 시뮬레이터, 2D/3D 건물 편집기)을 자연어로 조작하게 합니다.

• 앱의 모든 기능: 프로젝트 열기·저장, 도면 인식, 형상·Shape Studio, 격자, 해석 설정·사전 점검·실행·진행 확인, 출력, 화원, 재료, 감지기·제어, 스프링클러/물분무 배관망과 수리계산·펌프 사양·설계 검토, HVAC 덕트망, 피난 배치·실행·결과, 화재 결과 요약·ASET 판정, 결과 뷰어, 화면 캡처 — BULC 0.90 기준 앱 도구 239종을 그대로 노출합니다. 앱을 업데이트하면 새 도구가 이 서버를 다시 설치하지 않아도 따라옵니다.

• 도면 기반 작업: 사용자가 PC 의 도면 파일(DWG, DXF, PDF, 이미지, ZIP 묶음, IFC) 경로를 알려 주면, 서버가 파일을 로컬에서 분류하고(bulc_drawing_intake) 맞는 작업 절차를 돌려줍니다. 건축 평면도는 앱이 벽·문·창·기둥·실명을 인식해 건물을 만들고(arch_analyze_drawing → arch_import_building), 스프링클러·물분무 배관 도면은 배관망을 만듭니다(spr_analyze_drawing → spr_import_network).

• 오류를 줄이는 지식 팩: 온톨로지(클래스 79개), 규칙 166개(조건 → 확인 → 고치는 법), 흔한 LLM 실수 38개, 단계별 플레이북 6편, 한·영·FDS·도구 용어집, FDS 6.10.1 키 참조를 MCP resources·prompts·도구로 제공합니다. 실행 전 계획 점검(bulc_plan_check)과 덱 점검(bulc_check_deck)이 들어 있습니다.

이 저장소에는 BULC 앱이나 해석 엔진의 소스가 없습니다. 서버는 앱이 127.0.0.1 에서 여는 브리지에 요청을 전달하는 얇은 클라이언트입니다.

분야별로 할 수 있는 일

앱 버전에 따라 도구 집합이 다릅니다. 0.88 이하 앱에는 project_*·sim_*·fire_*·evac_run·arch_*·capture_view 가 없고, 지식 팩의 규칙이 그때의 대안(앱 파일 메뉴, run_simulation, 수동 벽 입력)을 알려 줍니다.

동작 방식

MCP 클라이언트 ──stdio──▶ bulc-mcp (이 저장소)
 (Claude 등)               ├─ 로컬 도구: 연결 상태 · 지식 검색 · 규칙 · 계획 점검 · 도면 분류 · 덱 점검 · 격자 조언
                           ├─ resources: bulc://knowledge/… (온톨로지·규칙·플레이북·용어집·FDS 키)
                           ├─ prompts: 작업 절차 8종
                           └─ 앱 도구 ──HTTP 127.0.0.1──▶ BULC 데스크톱 앱 (2D/3D 편집기 · 도면 인식 · 덱 생성 · GPU/CPU 솔버)

• 앱이 켜져 있으면 앱의 도구 목록을 그대로 쓰고, 꺼져 있으면 내장 스냅샷(이름·설명·입력 스키마만)으로 목록을 채웁니다. 앱이 나중에 켜지거나 도구 집합이 바뀌면 tools/list_changed 알림을 보냅니다.

• 앱이 돌려준 그림(capture_view)은 이미지로, 구조화 결과(sim_preflight, fire_compute_aset 등)는 structuredContent 로 전달합니다.

• 앱이 HTTP 200 으로 돌려주는 오류 문구(Tool input error, Unknown tool 등)는 오류(isError)로 표시하고 관련 규칙을 덧붙입니다.

• 브리지 포트에서 BULC 가 아닌 프로그램이 응답하면 알아채고 알려 줍니다. 루프백(127.0.0.1) 밖의 주소에는 연결하지 않습니다.

요구 사항

1. BULC 데스크톱 앱(라이선스 필요), 실행 중이어야 합니다. 0.90 이상을 권합니다(0.88 은 줄어든 도구 집합으로 동작). 설치 파일: Meteor-Simulation/bulc-releases. 브리지는 기본으로 켜져 있습니다(앱 환경 변수 BULC_BRIDGE=0 이면 꺼짐).

2. Node.js 20 이상

3. MCP 클라이언트(Claude Desktop, Claude Code, Cursor, VS Code 등)

설치

Claude Desktop — 설정 파일(Windows %APPDATA%\Claude\claude_desktop_config.json, macOS ~/Library/Application Support/Claude/claude_desktop_config.json)에 추가합니다.

{
  "mcpServers": {
    "bulc": {
      "command": "npx",
      "args": ["-y", "github:Meteor-Simulation/bulc-mcp"]
    }
  }
}

Windows 에서 npx 를 찾지 못하면 "command": "cmd", "args": ["/c", "npx", "-y", "github:Meteor-Simulation/bulc-mcp"] 로 바꿉니다.

Claude Code

claude mcp add bulc --scope user -- npx -y github:Meteor-Simulation/bulc-mcp

Cursor (~/.cursor/mcp.json) — 도구 수 상한이 있는 클라이언트는 compact 프로필을 권합니다.

{ "mcpServers": { "bulc": { "command": "npx", "args": ["-y", "github:Meteor-Simulation/bulc-mcp"], "env": { "BULC_MCP_PROFILE": "compact" } } } }

VS Code (.vscode/mcp.json)

{ "servers": { "bulc": { "type": "stdio", "command": "npx", "args": ["-y", "github:Meteor-Simulation/bulc-mcp"] } } }

소스에서

git clone https://github.com/Meteor-Simulation/bulc-mcp.git
cd bulc-mcp
npm install        # prepare 단계에서 빌드합니다
node build/server.js

클라이언트 설정의 command 는 node, args 는 ["<저장소 경로>/build/server.js"] 로 둡니다.

앱 찾기(브리지 주소와 토큰)

설정 없이 동작합니다. BULC 앱(0.90 이상)은 브리지를 열 때 사용자 설정 폴더에 발견 파일 BULC/bridge.json(Windows %APPDATA%\BULC\bridge.json)을 쓰고, 이 서버가 그 파일에서 주소·포트·토큰을 읽습니다. 앱이 8787 이 아닌 포트에서 돌아도(다른 프로그램이 8787 을 쓰는 경우) 그대로 찾습니다. 종료된 앱이 남긴 파일은 무시합니다.

• 순서: BULC_BRIDGE_URL → 발견 파일 → BULC_BRIDGE_HOST/BULC_BRIDGE_PORT(기본 127.0.0.1:8787).

• 앱을 BULC_BRIDGE_AUTH=sensitive|all 로 실행하면 파일·실행 도구(또는 전부)에 토큰이 필요합니다. 서버는 발견 파일의 토큰을 그 주소에만 Authorization: Bearer 로 보냅니다. 발견 파일을 읽을 수 없는 환경에서는 BULC_BRIDGE_TOKEN 을 씁니다.

• 발견 파일을 쓰지 않는 구버전 앱이 다른 포트에서 돌면 BULC_BRIDGE_URL(예: http://127.0.0.1:8790)을 지정합니다. bulc_connection_status 가 연결 여부, 주소를 찾은 경로, "BULC 가 아닌 프로그램이 응답함", 앱과 내장 스냅샷의 도구 집합 차이를 알려 줍니다.

환경 변수

도구

이 서버의 로컬 도구 — 앱 없이도 동작하는 것은 ○ 로 표시했습니다.

앱 도구(BULC 0.90 기준 239종): 프로젝트·실행·결과 24 · 건축 도면 3 · 형상 14 · 화재 6 · 경계 5 · 장치·제어 14 · 격자 21 · 재료 6 · 표면 8 · 출력 10 · 조회·점검 7 · 피난 16 · 스프링클러·물분무 32 · HVAC 20 · 층 7 · 가구 3 · 결과 뷰어 11 · Shape Studio 32. 도구마다 읽기 전용·파괴적·멱등 주석이 붙고, 실행 중인 앱에서만 동작하는 도구(열기·저장·실행·캡처 등)는 "Live app only" 로 표시됩니다.

지식 팩

LLM 이 지식 팩을 쓰는 방식:

1. 초기화 instructions — 연결하면 서버가 핵심 규칙 10개(단위, 읽고 쓰기, 도면, 화원 지시, 실행 전 점검·확인, 결과 보고)를 보냅니다.

2. 도구 설명의 규칙 힌트 — 앱 도구마다 관련 규칙 id 가 붙어 있어([bulc-mcp rules] VENT-002 …) 모델이 bulc_knowledge_search "<id>" 로 원문을 찾습니다.

3. 계획 점검 — 여러 단계 작업 전에 bulc_plan_check 가 도구 순서를 규칙으로 점검해 오류·경고와 따를 플레이북을 돌려줍니다(앱 없이 동작).

4. 오류 응답의 안내 — 앱이 인자를 거절하거나 없는 도구를 부르면 결과에 규칙 id 와 실제 도구 이름을 덧붙입니다.

5. prompts·resources — 작업별 prompt 가 플레이북 전문과 그 규칙을 한 번에 넣어 줍니다.

자세한 내용은 knowledge/README.md 를 보십시오.

도면으로 작업하기

1. 도면을 PC 에 두고 절대 경로를 AI 에게 알려 줍니다(채팅 첨부 파일은 MCP 서버가 읽을 수 없습니다).

2. AI 가 bulc_drawing_intake 로 분류하고, 단위·축척·기준점·층고·최종 출구를 묻습니다.

3. 건축 평면도: arch_analyze_drawing 이 벽·문·창·기둥·실명·층 표기를 인식하고 확인할 질문을 냅니다 → arch_import_building 을 dryRun(기본)으로 개수·크기를 보여 주고 → 동의하면 건물을 만듭니다(되돌리기 1단계). 그림이나 글자가 윤곽선인 PDF 는 AI 가 그림을 읽어 arch_import_floorplan_report 로 넣습니다.

4. 스프링클러 평면·배관 ISO: spr_analyze_drawing → 열린 끝·참조선·모호한 항목 확인 → spr_import_network(먼저 dryRun) → 수리계산·펌프·검토.

5. 그 건물 위에서 화재(사용자가 정한 화원만), 피난, HVAC, 스프링클러 작업을 이어 갑니다. 실행은 sim_preflight → 조건 요약·확인 → sim_start 순서이고, 결과는 fire_results_summary·fire_compute_aset·evac_get_results 가 돌려준 값만 보고합니다.

합성 예제: examples/ (평면 DXF, 물분무 ISO DXF, FDS 덱, 예시 세션).

개인정보와 보안

• 서버는 사용자 PC 에서만 실행되고 127.0.0.1 의 BULC 앱에만 연결합니다. 텔레메트리는 없습니다.

• 서버가 직접 읽는 파일은 사용자가 지정한 도면·덱과 앱의 발견 파일뿐이며, 어디에도 올리지 않습니다. 브리지 토큰은 그 앱 주소에만 보냅니다.

• 다만 도구 결과(도면 인식 요약, 화면 캡처 포함)는 대화의 일부로 사용자가 쓰는 AI 공급자에게 전달됩니다. 보안이 엄격한 도면은 로컬 LLM 을 쓰는 MCP 클라이언트를 검토하십시오.

• 자세한 내용: PRIVACY_POLICY.md, SECURITY.md

문제 해결

라이선스

이 서버의 코드와 지식 팩은 MIT 입니다. BULC 데스크톱 앱과 해석 엔진은 별도의 상용 라이선스로 제공되며 이 저장소에 포함되지 않습니다. "BULC" 는 Meteor Simulation 의 상표이며, MIT 라이선스는 상표 사용권을 주지 않습니다. 인용한 외부 자료의 출처는 NOTICE.md 에 있습니다.

Related MCP server: ANSYS MCP Server

English

What it is

BULC MCP is a Model Context Protocol server. It lets the AI in an MCP client — Claude Desktop, Claude Code, Cursor, VS Code and others — drive the BULC desktop app running on the same PC (a GPU fire simulator built on FDS 6.10.1, with a 2D/3D building editor) in plain language.

• Every app feature: opening and saving projects, drawing recognition, geometry, Shape Studio, meshing, run settings, pre-flight checks, runs and progress, outputs, fires, materials, detectors and controls, sprinkler / water-spray networks with hydraulics, pump sizing and design review, HVAC ducts, evacuation set-up, runs and results, fire result summaries and ASET, the result viewer and screenshots — 239 app tools as of BULC 0.90, taken live from the app so new app versions bring new tools without reinstalling this server.

• Work from drawings: give the AI the local path of a DWG, DXF, PDF, image, ZIP bundle or IFC file. bulc_drawing_intake classifies it on your PC and returns the playbook. The app recognises architectural floor plans (walls, doors, windows, columns, room names) and builds the building (arch_analyze_drawing → arch_import_building), and turns sprinkler / water-spray piping drawings into pipe networks (spr_analyze_drawing → spr_import_network).

• A knowledge pack that prevents mistakes: an ontology (79 classes), 166 rules (condition → check → fix), 38 common LLM mistakes, six playbooks, a Korean–English–FDS–tool glossary and an FDS 6.10.1 key reference, served as MCP resources, prompts and tools. Plans and decks are checked before acting (bulc_plan_check, bulc_check_deck).

This repository contains no BULC application or solver source. The server is a thin client of the bridge the app opens on 127.0.0.1.

What it can do, by domain

BULC 0.88 and older lack project_*, sim_*, fire_*, evac_run, arch_* and capture_view; the rules describe the fallbacks.

Requirements

1. The BULC desktop app (licensed), running — 0.90 or later recommended (0.88 works with the smaller tool set). Installer: Meteor-Simulation/bulc-releases. The bridge is on by default (BULC_BRIDGE=0 in the app's environment turns it off).

2. Node.js 20+

3. An MCP client.

Install

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "bulc": { "command": "npx", "args": ["-y", "github:Meteor-Simulation/bulc-mcp"] } } }

Claude Code: claude mcp add bulc --scope user -- npx -y github:Meteor-Simulation/bulc-mcp

Cursor / VS Code: same command; clients with a tool-count limit should set BULC_MCP_PROFILE=compact. From source: git clone, npm install (builds in prepare), then run node build/server.js.

Finding the app

No configuration is needed. When BULC (0.90+) opens its bridge it writes a discovery file BULC/bridge.json in the user's config folder (%APPDATA%\BULC\bridge.json on Windows); this server reads the address, port and token from it — also when the app runs on a port other than 8787. Files left behind by an app that has ended are ignored. Order: BULC_BRIDGE_URL → discovery file → BULC_BRIDGE_HOST/BULC_BRIDGE_PORT (default 127.0.0.1:8787). With BULC_BRIDGE_AUTH=sensitive|all in the app, the token from the discovery file is sent as Authorization: Bearer to that address only; BULC_BRIDGE_TOKEN covers set-ups without the file. All environment variables are listed in the Korean section above.

Tools, knowledge and prompts

• Local tools: bulc_connection_status, bulc_knowledge_search, bulc_get_rules, bulc_plan_check, bulc_drawing_intake, bulc_check_deck, bulc_mesh_advisor, bulc_find_tools (all work without the app), bulc_call (compact profile), get_project_summary, run_simulation (guarded run for any app version).

• App tools carry read-only / destructive / idempotent annotations, "Live app only" marks, side-effect notes and, by default, a short list of related rule ids — never pushing a description past 1,024 characters.

• App pictures (capture_view) arrive as image content and structured results as structuredContent.

• Resources: bulc://knowledge/{index, ontology, ontology.jsonld, rules, glossary, fds-6.10.1/keys}, playbooks, templates bulc://knowledge/rule/{id}, …/rules/{domain}, …/class/{name}, …/fds-6.10.1/namelist/{group}, bulc://tools/{name}, live bulc://project/summary and bulc://project/deck, and the synthetic bulc://examples/….

• Prompts: bulc-start, drawing-to-fire-aset, evacuation-rset, hvac-smoke-control, sprinkler-design, marine-water-spray-iso, troubleshooting, review-fds-deck.

Example session (synthetic)

user: Build a fire model from D:\work\office-plan-synthetic.dxf — ground floor, 3 m storey, exit on the south side.
→ bulc_connection_status · project_info · bulc_drawing_intake {"path": "D:\\work\\office-plan-synthetic.dxf", "purpose": "fire"}
→ arch_analyze_drawing {"filePath": "D:\\work\\office-plan-synthetic.dxf"} → mm, 5 walls, 2 doors, 1 window + questions
assistant: confirms units, origin, which door is the final exit and the fire scenario (no fire until the user gives one — GEN-015)
→ arch_import_building {"candidateId": "…", "story": 1} (dry run) → user agrees → … "dryRun": false
→ bulc_plan_check {...} → set_mesh · set_all_boundaries_open · add_fire · output_add_tenability_slices · set_time
→ sim_preflight → summary → user confirms → project_save → sim_start {"confirm": true} → sim_status … → fire_compute_aset

More in examples/sessions.

Privacy and security

The server runs on your PC and talks only to the BULC app on 127.0.0.1; no telemetry. It reads only the files you point it to and the app's discovery file, and uploads nothing; the bridge token is sent only to that app. Tool results (including drawing summaries and screenshots) become part of your conversation with the AI provider you use — consider an MCP client with a local model for confidential drawings. See PRIVACY_POLICY.md and SECURITY.md.

Development

npm install
npm run check          # typecheck, build, tests, knowledge lint, public-content scan, licence check, package contents
npm run gen:examples   # regenerate the synthetic DXF examples
node scripts/import-snapshot.mjs <export.json> --app-version X.Y.Z   # refresh the bundled tool snapshot

License

The server code and the knowledge pack are MIT. The BULC desktop app and its solvers are commercial software under a separate licence and are not part of this repository. "BULC" is a trademark of Meteor Simulation; the MIT licence grants no trademark rights. Sources cited by the knowledge pack are listed in NOTICE.md.