bizagi-mcp

프로세스 설명을 Bizagi Modeler에서 깨끗하게 열리는 BPMN 2.0 다이어그램으로 바꿔줍니다.

BPMN 2.0 다이어그램을 생성, 읽기, 감사, 미리보기하고 Windows에서 Bizagi Modeler 데스크톱 앱을 구동하는 MCP 서버입니다.

60줄짜리 JSON 스펙에서 생성되었습니다. 위의 모든 좌표는 손으로 배치한 것이 아니라 계산된 것입니다.

왜 존재하는가

Bizagi Modeler에는 스크립팅 API가 없습니다. 지원하는 유일한 통합 경로는 Export / Import 탭을 통한 개방형 BPMN 2.0 XML 형식입니다.

하지만 순진한 생성을 무용지물로 만드는 문제가 있습니다: Bizagi는 파일에 기록된 좌표를 그대로 가져옵니다. 다이어그램을 자동 배치해 주지 않습니다. 지오메트리 없이 구조적으로 완벽한 BPMN 파일을 내보내면 원점에 쌓인 상자 더미로 열립니다.

따라서 이 서버의 어려운 부분은 XML이 아니라 레이아웃입니다.

Related MCP server: camunda-mcp

하는 일

처음 여덟 개는 순수 Python으로 작성되어 Bizagi 설치 여부와 관계없이 모든 OS에서 실행됩니다. Windows가 필요한 것은 bizagi_* 도구 네 개뿐입니다.

레이아웃 엔진

레인을 인식하는 계층형 레이아웃이 실행되는 순서는 다음과 같습니다:

1. 사이클 끊기 — 그래프를 레이어링할 수 있도록

2. 최장 경로 레이어링 → 각 노드의 수평 열

3. (열, 레인)별 무게중심 순서화 → 교차선 감소

4. 적응형 레인 높이 — 각 밴드가 담는 가장 높은 셀에 맞춰 크기 조정

5. 예약 스트립 — 열을 건너뛰는 분기를 담는 레인 상단의 우회 밴드와 루프백을 위한 하단의 채널 스트립

6. 직교 라우팅 — 장애물을 통과하지 않고 주위를 돌아갑니다

7. 라벨 분리를 마지막 패스로

보장하는 것

이것은 바람이 아닙니다. 각 항목은 규칙이 제거되면 실패하는 테스트입니다:

• 두 셰이프가 겹치지 않음

• 자신의 끝점이 아닌 셰이프를 통과하는 엣지가 없음

• 모든 요소가 자신의 풀 안에 위치함

• 메시지 흐름은 풀 사이의 빈 복도를 따라 흐르며, 풀을 가로질러 수평으로 지나가지 않음

• 각 메시지 흐름은 그 복도에서 자신만의 라인을 가지며, 복도 크기는 복도를 가로지르는 흐름 수에 따라 결정됩니다 — 그래서 라벨이 쌓이지 않습니다

• 루프백은 각각 레인 크기가 조정되는 동안 예약된 스트립에서 자신만의 채널을 가짐

• 열을 건너뛰는 분기는 자신의 레인 안에서, 건너뛰는 활동 위로 우회함

• 게이트웨이의 분기는 눈에 띄게 다른 지점에서 나가므로 양방향 분기가 단일 화살표로 읽히지 않음

• 경계 이벤트 흐름은 아래쪽으로 나가며, 호스트 활동을 통해 다시 올라가지 않음

• 주석과 데이터 저장소는 설명하는 대상 옆에 위치함 — 또는 연결이 없을 때는 캔버스 밖이 아니라 선언된 풀 안에 위치함

• 어떤 라벨도 다른 라벨이나 셰이프 위에 쓰이지 않음

설계 노트

쉽게 틀리기 쉬운 몇 가지 결정 사항:

• 라벨의 너비는 텍스트의 너비와 같습니다. 모든 라벨에 평평한 상자를 예약하면 긴 라벨 사이의 충돌이 예약된 상자를 측정하는 어떤 것에도 보이지 않게 됩니다.

• 예약된 공간은 중앙 정렬에서 제외되어야 합니다. 채널을 위한 공간을 만들기 위해 레인을 키운 다음 그 안의 셰이프를 중앙에 정렬하면 새 공간의 절반이 위쪽 패딩으로 돌아갑니다 — 채널은 결국 사용하기에 너무 얇아집니다.

• 우회로는 모든 셰이프의 주변이 아니라 셰이프 사이의 틈에 있어야 합니다. 모든 것을 위나 아래로 라우팅하면 선이 풀 밖으로 나가고, 그 선에 도달하는 수직선은 그 과정에서 모든 레인을 가로지릅니다.

• 데이터 저장소는 여러 활동과 연결될 수 있지만 하나의 옆에만 위치합니다. 연결마다 한 번씩 배치하면 이전 배치가 있던 레인에 구멍이 남습니다.

설치

pip install -e .

Windows 데스크톱 도구의 경우:

pip install -e ".[desktop]"

Python ≥ 3.10.

Claude에 등록

claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "bizagi-modeler": {
      "command": "bizagi-mcp",
      "env": {
        "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi"
      }
    }
  }
}

bizagi-mcp가 PATH에 없으면:

{
  "mcpServers": {
    "bizagi-modeler": {
      "command": "python",
      "args": ["-m", "bizagi_mcp.server"],
      "env": { "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi" }
    }
  }
}

Claude Code의 경우: claude mcp add bizagi-modeler -- bizagi-mcp

환경 변수

사용법

다이어그램 생성

"휴가 요청을 모델링하세요: 직원이 제출하고, 관리자가 승인 또는 거부하며, HR이 결과를 기록합니다. D:\Processes\leave.bpmn에 저장하세요."

그런 다음 Bizagi Modeler에서: Export / Import ▸ Import ▸ BPMN.

기존 모델 분석

먼저 Bizagi에서 내보내기를 수행하고(Export / Import ▸ Export ▸ BPMN), 그런 다음:

"D:\Processes\purchasing.bpmn을 읽고, 설명해 주고, 무엇이 잘못되었는지 알려주세요."

예시

examples/purchase_request.json(스펙), .bpmn(생성됨), .svg(미리보기)를 참조하세요.

검증 규칙

구조 (BPMN001–BPMN020, 심각도 error / warning)

시작 또는 종료 이벤트 누락 · 도달 불가능한 요소 · 막다른 끝 · 풀을 가로지르는 시퀀스 흐름 · 하나의 풀 안에 있는 메시지 흐름 · 조건 없이 분기하는 게이트웨이 · 이벤트 기반 게이트웨이 대상 · 암시적 분기와 병합 · 비활동에 대한 경계 이벤트 · 중복 id · 조건도 함께 가지는 기본 흐름 · 하나의 입력과 하나의 출력을 가진 게이트웨이.

관례 (BP001–BP017, 심각도 warning / info)

활동 이름 지정(동사 + 목적어) · 질문 형태가 아닌 게이트웨이 · 라벨이 없는 분기 · 문서화 범위 · 레인이 없는 풀 · 빈 레인 · 다이어그램 크기 · 중복 이름 · 메시지를 주고받지 않는 풀.

모든 발견 사항은 문제가 있는 요소와 이를 수정하기 위한 구체적인 단계를 명시합니다.

데스크톱 앱 구동

bizagi_open은 신뢰할 수 있는 경로입니다: Modeler는 파일을 명령줄 인자로 받으므로 메뉴를 조작할 필요가 없습니다.

bizagi_import_bpmn은 리본을 조작하며, 그 점을 솔직하게 밝힙니다:

• 포그라운드를 차지하고 실제로 그렇게 되었는지 확인합니다. Windows는 포그라운드를 소유하지 않은 프로세스에 SetForegroundWindow를 거부하며, set_focus()는 성공한 것처럼 반환합니다 — 그대로 클릭하면 사용자가 작업 중인 곳에 실제 마우스 클릭이 전달됩니다.

• 다이어그램 탭 수를 전후로 세어, 기대가 아닌 그 증거를 바탕으로 imported: true / false를 보고합니다.

• 두 횟수 모두 창을 앞으로 올린 상태에서 측정합니다. 뒤에 있는 창은 불완전한 접근성 트리를 반환할 수 있기 때문입니다.

백그라운드 모드는 없습니다

가져오기는 컴퓨터를 다른 용도로 사용하는 동안에는 실행할 수 없습니다. Modeler 4.3.0.008을 대상으로 세 가지 경로를 테스트했으며 세 가지 모두 막혀 있습니다:

리본은 포커스된 창에서 실제 마우스 입력에만 반응합니다. 무인 실행을 위해서는 Bizagi에 전용 Windows 세션 또는 VM을 제공하세요. 이를 기록해 두어 누구도 다시 시도하지 않도록 하려면: 이 표가 그 기록입니다.

보안

• 경로는 확인 전에 완전히 해석되고(~, .., 심볼릭 링크), BIZAGI_MCP_ROOT가 설정된 경우 그 안으로 제한됩니다

• XML 파싱은 가능한 경우 defusedxml을 거칩니다(XXE, billion laughs)

• overwrite=true 없이는 파일을 덮어쓰지 않습니다

• Bizagi는 셸 없이 인자 목록으로 실행되므로 파일 이름이 명령이 될 수 없습니다

• 모든 오류는 데이터로 반환됩니다({"ok": false, ...}). 트레이스백이 아닙니다

테스트

pip install -e ".[dev]"
pytest -q

72개의 테스트: 스펙 정규화, XSD 요소 순서, BPMNDI 완전성, 위에 나열된 모든 레이아웃 보장, 라벨 충돌, 라운드트립, 각 검증 규칙, 경로 탐색, 리본 버튼 선택, 포그라운드 확인, 그리고 모든 도구의 오류 계약.

알려진 제한 사항

• .bpm은 읽지 않습니다. Bizagi의 독점 형식이므로 먼저 BPMN으로 내보내세요. list_processes는 여전히 .bpm 파일을 나열하고 플래그를 표시합니다.

• 데스크톱 제어는 Windows 전용이며 pywinauto가 필요합니다.

• 다이어그램은 한 단계 깊이로 생성됩니다. 하위 프로세스는 접힌 셰이프로 나타나며 그 내용은 생성되지 않습니다.

• 레이아웃 정돈은 파일에 기록된 지오메트리에 대해서만 보장됩니다. Bizagi는 노드 이름을 자체 규칙에 따라 배치하며, 이는 다이어그램 교환 섹션이 제어하지 않습니다.

라이선스

MIT — LICENSE를 참조하세요.