MCP-BPMN 서버

테스트된 BPMN 2.0 작성 하위 집합을 위한 Model Context Protocol(MCP) 서버로, Mermaid 변환, 로컬 영속화, 레이아웃, 검증, XML 또는 SVG 내보내기를 포함합니다.

🎯 개요

MCP-BPMN은 AI 어시스턴트가 한 번에 하나의 비즈니스 프로세스 다이어그램을 작업할 수 있도록 상태 저장 인터페이스를 제공합니다. 아래 나열된 구성 요소에 대해 올바른 형식의 BPMN 2.0 XML을 작성합니다. 완전한 BPMN 2.0 편집기, 실행 엔진 또는 배포 클라이언트는 아닙니다. 휴대용 BPMN 코어가 기본 작성 계약이며, 옵트인 방식의 타입이 지정된 Camunda 7 프로필은 ADR 0001에 문서화되어 있습니다.

주요 기능

• 집중된 BPMN 작성: 지원되는 이벤트, 활동, 게이트웨이, 데이터 객체, 주석, 풀, 최상위 레인, 시퀀스 흐름 및 연관 관계

• Mermaid 변환: 문서화된 순서도 하위 집합에서 다이어그램 부트스트랩

• 수평 자동 레이아웃: 결정론적 프로세스 및 협업 배치

• 로컬 영속화: 구성된 디렉터리에 다이어그램을 원자적으로 저장하고 다시 열기

• XML 및 SVG 내보내기: XML은 프로세스 내에서 생성되고, SVG는 Puppeteer와 bpmn-js를 통해 렌더링됩니다

• 휴대용 및 Camunda 7 프로필: 기본적으로 공급업체에 종속되지 않는 출력을 제공하며, 명시적으로 선택하면 타입이 지정된 Camunda 7 사용자 작업 필드 세 개를 제공합니다

Related MCP server: BPMN-MCP

🚀 빠른 시작

요구 사항

• Node.js 22.12.0 이상

• lockfile을 지원하는 npm

• export({ format: "svg" })용 Chrome 또는 Chromium; 일반적인 Puppeteer 설치 시 호환 브라우저가 다운로드됩니다

XML 작성, 검증, 레이아웃, 영속화 및 XML 내보내기는 브라우저를 실행하지 않습니다. SVG 내보내기는 브라우저를 실행합니다. Puppeteer 브라우저 다운로드를 의도적으로 건너뛴 경우, 서버를 시작하기 전에 PUPPETEER_EXECUTABLE_PATH를 호환되는 Chrome 또는 Chromium 실행 파일로 설정하세요. SVG 렌더링은 헤드리스이며, 서버 인스턴스당 동시 렌더링 하나로 제한되고, 20초의 렌더링 제한 시간이 있습니다.

소스 체크아웃에서 실행

git clone https://github.com/oisee/mcp-bpmn.git
cd mcp-bpmn
npm ci
npm run build
npm start

npm run build는 표준 ESM 실행 파일을 dist/server/index.js에 생성합니다. 서버는 stdio를 사용하므로 터미널에서 시작하면 일반적으로 유휴 상태로 보이며, MCP 클라이언트가 실행하도록 설계되었습니다.

구성

Claude Desktop용

Claude Desktop 구성 파일에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-bpmn": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
    }
  }
}

다른 MCP 클라이언트용

절대 경로와 함께 동일한 ESM 진입점을 사용하세요:

node /absolute/path/to/mcp-bpmn/dist/server/index.js

패키징된 릴리스 아티팩트 설치

이 저장소는 mcp-bpmn-server가 공개 npm 레지스트리에서 사용 가능하다고 가정하지 않고 npm tarball 설치를 문서화합니다. 릴리스 생성자는 소스 체크아웃에서 표준 CLI 전용 아티팩트를 빌드할 수 있습니다:

artifact_dir=$(mktemp -d)
npm pack --pack-destination "$artifact_dir"

해당 tarball을 전용 소비자 디렉터리에 설치하고 패키징된 실행 파일을 실행하세요:

consumer_dir=$(mktemp -d)
npm install --prefix "$consumer_dir" "$artifact_dir"/mcp-bpmn-server-*.tgz
"$consumer_dir/node_modules/.bin/mcp-bpmn-server"

MCP 클라이언트의 경우 $consumer_dir/node_modules/.bin/mcp-bpmn-server의 절대값을 command로 사용하고 빈 args 배열을 사용하세요. 이 패키지는 가져올 수 있는 JavaScript 라이브러리가 아니라 CLI입니다.

Claude Code 및 Codex용 설치

소스 체크아웃에서 설치 프로그램은 현재 릴리스를 안정적인 사용자 소유 위치에 패키징하고, MCP 서버를 등록하며, PATH에서 발견된 지원되는 모든 클라이언트에 bpmn-modeler 스킬을 설치합니다:

make install
make doctor

기본 프로그램 위치는 ~/.local/share/mcp-bpmn이며, 다이어그램은 설치 외부의 ~/mcp-bpmn에 유지됩니다. 스킬은 Codex의 경우 ~/.codex/skills/bpmn-modeler로, Claude Code의 경우 ~/.claude/skills/bpmn-modeler로 복사됩니다. 설치 후 클라이언트를 다시 시작하여 새 스킬과 MCP 서버를 발견하세요.

설치는 멱등적입니다: make install을 다시 실행하면 이 설치 프로그램이 소유한 파일과 등록만 교체됩니다. 기존 타사 등록 또는 스킬 디렉터리는 FORCE=1로 교체를 명시적으로 요청하지 않는 한 보존됩니다. 하나의 클라이언트를 대상으로 하거나, 기존 설치를 업데이트하거나, 다이어그램을 보존하면서 제거하려면 다음을 사용하세요:

make install-codex
make install-claude
make update
make uninstall

PREFIX를 설정하여 프로그램 위치를 변경하고, MCP_BPMN_DIAGRAMS_PATH를 사용하여 다른 절대 다이어그램 디렉터리를 사용하세요. 사전 빌드된 릴리스 tarball은 MCP_BPMN_PACKAGE_TARBALL과 필수 MCP_BPMN_PACKAGE_SHA256을 모두 설정하여 재현 가능하게 설치할 수 있습니다. 전체 인터페이스는 ./scripts/install-agent-integrations.sh --help를 실행하세요. 설치 프로그램은 macOS와 Linux를 지원하며, Linux 네이티브 Node.js 및 클라이언트 CLI가 있는 WSL도 포함합니다.

Codex 플러그인 로컬 개발

릴리스 아티팩트는 Codex 플러그인이기도 합니다. 해당 매니페스트는 표준 skills/bpmn-modeler 스킬을 발견하고, 플러그인 캐시에 복사된 런처를 통해 하나의 mcp-bpmn stdio 서버를 시작합니다. 런처는 make install-codex로 설치된 안정적인 비공개 릴리스를 사용합니다. 설치 후 TypeScript를 실행하거나 체크아웃에 의존하지 않습니다.

릴리스 아티팩트를 빌드하고, 이 체크아웃을 임시 저장소 마켓플레이스로 추가하고, 플러그인을 설치하세요:

npm ci
npm run build
make install-codex
codex plugin marketplace add .
codex plugin list --available
codex plugin add mcp-bpmn@mcp-bpmn-local

설치 후 새 Codex 대화를 시작하여 스킬과 MCP 도구가 로드되도록 하세요. 번들된 서버는 기본적으로 writes 승인 모드를 사용합니다: 읽기 전용으로 표시된 도구는 자동으로 실행될 수 있는 반면, 다이어그램 변경은 승인을 위해 표시됩니다. 개발 설치를 제거하려면:

codex plugin remove mcp-bpmn@mcp-bpmn-local
codex plugin marketplace remove mcp-bpmn-local

실제 Codex 구성을 변경하지 않고 격리된 마켓플레이스, 캐시, 발견, MCP 시작 및 제거 스모크 테스트를 실행하세요:

npm run test:codex-plugin

Claude Code 플러그인 로컬 개발

릴리스 아티팩트는 Claude Code 플러그인이기도 합니다. Claude는 표준 skills/bpmn-modeler/SKILL.md를 네임스페이스가 지정된 /mcp-bpmn:bpmn-modeler 스킬로 발견하고, 플러그인 캐시에서 인라인 mcp-bpmn 서버를 시작합니다. 플러그인은 skills/를 사용하며, 레거시 commands/ 복사본을 포함하지 않습니다.

소스 체크아웃에서 한 개발 세션 동안 종속성을 설치하고, 빌드하고, 검증하고, 플러그인을 로드하세요:

npm ci
npm run build
claude plugin validate .
claude --plugin-dir .

Claude Code 내에서 /mcp를 사용하여 플러그인 제공 서버를 확인하고, /mcp-bpmn:bpmn-modeler를 호출하여 스킬을 검사하고, 매니페스트 또는 MCP 구성을 변경한 후 /reload-plugins를 실행하세요. 체크아웃에는 저장소 기여자를 위한 루트 CLAUDE.md가 포함되어 있으므로 소스 검증은 이것이 플러그인 컨텍스트가 아니라고 보고합니다. 명령은 여전히 성공합니다. 패키징된 플러그인은 해당 저장소 전용 파일을 제외하고 엄격한 검증을 통과합니다.

전체 로컬 마켓플레이스 스모크 테스트를 실행하세요:

npm run test:claude-plugin

이 검사는 임시 Claude 홈과 마켓플레이스를 사용합니다. 복사된 릴리스 아티팩트를 설치하고, Claude의 구성 요소 인벤토리를 확인하고, 캐시된 MCP 서버를 시작하고, 리로드를 실행한 다음 플러그인을 비활성화, 활성화 및 제거합니다. 개발자의 실제 Claude 구성을 변경하지 않습니다.

다이어그램은 ${CLAUDE_PLUGIN_ROOT}에 기록되지 않습니다. MCP_BPMN_DIAGRAMS_PATH가 설정된 경우 해당 위치에, 기본적으로는 ~/mcp-bpmn에 유지되므로 플러그인 리로드, 업데이트, 비활성화 및 제거 시 삭제되지 않습니다. 수동 Claude MCP 등록에서 플러그인으로 전환하기 전에 claude mcp list를 검사하고 명령이 플러그인 엔드포인트와 다른 경우 이전 mcp-bpmn 등록을 제거하세요. Claude는 동일한 명령으로 확인되는 플러그인 및 사용자 서버만 중복 제거합니다.

에이전트 워크플로 평가

표준 머신 판독 가능 말뭉치는 evals/bpmn-modeler/cases.json입니다. 두 클라이언트 어댑터 모두 정확히 동일한 프롬프트와 의미론적 기대치를 사용합니다. 결정론적 검사는 일반 개발 및 CI에 안전합니다: 모델을 호출하지 않고 활성화 경계, 스킬 메타데이터, 도구 이름, 클라이언트 패리티, 생성/변경/검증/레이아웃/검증/내보내기 시퀀스를 확인합니다:

npm run test:evaluations

인증된 모델 실행은 옵트인입니다. 먼저 빌드한 다음, 반복하는 동안 하나의 경계 케이스를 선택하세요:

npm run build
npm run eval:codex -- --case direct-process-svg
npm run eval:claude -- --case direct-process-svg

Codex 어댑터는 표준 스킬과 프로젝트 범위의 stdio MCP 구성을 포함하는 임시 프로젝트에서 codex exec를 실행합니다. Claude 어댑터는 동일한 케이스를 임시 플러그인 복사본의 네이티브 claude plugin eval 케이스로 구체화합니다. 둘 다 MCP_BPMN_DIAGRAMS_PATH를 임시 디렉터리로 설정하고, 선언된 설정 픽스처만 해당 위치에 복사한 후 디렉터리를 제거합니다. 사용자의 실제 저장소에 있는 다이어그램을 읽거나, 덮어쓰거나, 삭제하지 않습니다. --case를 생략하면 전체 말뭉치를 실행합니다. 이러한 명령은 모델 할당량을 소비할 수 있으며 의도적으로 npm run check 및 CI에서 제외됩니다.

선택적 CommonJS 번들

CommonJS 번들은 별도의 소스 체크아웃 빌드이며 npm run build로 생성되지 않고 표준 npm tarball에 포함되지 않습니다:

npm run build:bundle
npm run start:bundle

📚 API 참조

상태 저장 컨텍스트 관리

MCP-BPMN은 한 번에 하나의 다이어그램으로 작업하는 상태 저장 API 설계를 사용합니다. 모든 작업은 현재 다이어그램 컨텍스트에 적용되므로 processId 매개변수가 필요하지 않습니다.

광고된 도구 매트릭스

이 API 참조의 제목은 tools/list가 반환하는 모든 도구를 열거합니다. 실행 가능 패리티 기준은 tests/contracts/engine-contract.test.ts이며, 단위, 통합 및 엔드투엔드 스위트에 집중된 동작이 있습니다.

각 광고된 도구에는 표준 MCP readOnlyHint, destructiveHint, idempotentHint 및 openWorldHint 주석도 포함됩니다. 이러한 주석은 관찰 가능한 서버 동작을 설명합니다: 작성 호출은 자동 저장되고, 교체 및 삭제 호출은 기존 상태를 파괴할 수 있으며, 모든 작업은 구성된 로컬 다이어그램 저장소 내에 유지됩니다. MCP 주석은 권한 부여 경계가 아닌 조언적 힌트입니다. 클라이언트는 여전히 자체 신뢰 및 승인 정책을 적용해야 합니다.

생성 도구

new_bpmn

새 BPMN 프로세스 또는 협업 다이어그램을 만들고 현재 컨텍스트로 설정합니다.

{
  name: "Order Processing",
  type: "process" // or "collaboration" (optional, defaults to "process")
}

new_from_mermaid

Mermaid 코드에서 새 BPMN 다이어그램을 생성하고 현재 컨텍스트로 설정합니다.

{
  name: "My Process",
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

Mermaid 변환은 의도적으로 제한된 flowchart 하위 집합을 지원합니다:

서브그래프가 하나라도 있으면 모든 노드는 정확히 하나의 최상위 서브그래프에 속해야 합니다. 중첩 서브그래프와 데이터 노드에 대한 시퀀스 흐름 연결은 BPMN 내보내기 전에 거부됩니다. 스타일링, 클릭 핸들러, CSS 클래스 및 점선 엣지 모양은 BPMN에 표현되지 않습니다. 허용되는 손실 구문은 변환 경고를 반환합니다. 텍스트 레이블과 서브그래프 이름은 XML 이스케이프 처리되어 BPMN을 통해 변경 없이 왕복합니다.

파일 작업

open_bpmn

기존 BPMN 파일을 열고 현재 컨텍스트로 설정합니다.

{
  filename: "my-process.bpmn"
}

open_mermaid_file

Mermaid 파일을 열고 BPMN으로 변환하여 현재 컨텍스트로 설정합니다.

{
  filename: "my-flowchart.mmd"
}

save

현재 다이어그램을 활성 파일에 원자적으로 저장합니다. 새 다이어그램과 열린 다이어그램은 이미 활성 파일 이름을 가지고 있으며, 성공적인 변경은 동일한 파일에 자동 저장됩니다.

{}

save_as

현재 다이어그램을 새 파일 이름으로 원자적으로 저장하고 해당 파일 이름을 활성화합니다. 이후 변경 사항은 새 파일에만 반영됩니다. 이전 파일은 변경되지 않은 스냅샷으로 유지됩니다.

{
  filename: "my-process.bpmn"
}

close

현재 다이어그램을 닫고 컨텍스트를 지웁니다.

{}

current

현재 다이어그램에 대한 정보를 가져옵니다.

{}

요소 조작 도구

add_event

현재 다이어그램에 이벤트(시작, 종료, 중간, 경계)를 추가합니다.

{
  eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
  name: "Order Received",
  eventDefinition: "message", // optional; only BPMN-legal event kind/definition pairs are accepted
  eventDefinitionPayload: {
    reference: { name: "Order received" } // root ID is generated when omitted
  },
  position: { x: 100, y: 200 } // optional
}

타이머 정의에는 timer: { type: "timeDate" | "timeDuration" | "timeCycle", expression, language? }가 필요합니다. 조건부 정의에는 condition: { expression, language? }가 필요합니다. 오류 및 에스컬레이션 참조에는 code도 포함될 수 있습니다. 보상(compensation) throw에는 activityRef 및 waitForCompletion이 포함될 수 있습니다. 보상 경계 이벤트는 비중단(non-interrupting)입니다.

add_activity

현재 다이어그램에 활동(태스크, 서브프로세스)을 추가합니다.

{
  activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
  name: "Review Order",
  position: { x: 250, y: 200 }, // optional
  properties: { // optional; Camunda 7 profile only on userTask
    assignee: "reviewer",
    candidateGroups: ["operations", "approvers"],
    dueDate: "${dueDate}"
  }
}

새 BPMN 및 Mermaid 작성 문서는 extensionProfile: "portable" | "camunda7"를 허용합니다. 기본값은 portable입니다. Portable 모드는 세 가지 벤더 필드를 거부하고 벤더 네임스페이스를 내보내지 않습니다. Camunda 업데이트는 이들 중 하나에 null을 허용하여 해당 XML 속성을 제거합니다. 후보 그룹 항목에는 쉼표를 포함할 수 없습니다. 가져온 BPMN은 실제 Camunda 네임스페이스 사용을 감지하고 다른 경고 없는 확장을 불투명하게 보존합니다.

호출 활동은 bpmn:callActivity로 직렬화됩니다. 선택적 properties.calledElement는 호출 가능한 요소를 식별하는 어휘적 BPMN QName입니다. 현재 다이어그램의 프로세스 ID와 일치할 필요는 없습니다.

활동은 표준 BPMN 다중 인스턴스 루프 특성을 사용할 수 있습니다. 병렬 인스턴스의 경우 isSequential을 false로, 순차 인스턴스의 경우 true로 설정합니다:

{
  activityType: "serviceTask",
  name: "Process Batch",
  properties: {
    multiInstance: {
      isSequential: false,
      loopCardinality: {
        body: "requestedInstanceCount",
        language: "urn:example:expression-language"
      },
      completionCondition: {
        body: "completedInstanceCount >= requiredInstanceCount",
        language: "urn:example:expression-language"
      },
      loopDataInputRef: "DataObjectReference_Input",  // optional ItemAwareElement ID
      loopDataOutputRef: "DataObjectReference_Output" // optional ItemAwareElement ID
    }
  }
}

서버는 표현식 본문을 정확히 보존하고 BPMN FormalExpression 값으로 직렬화합니다. 서버는 이를 구문 분석하거나 평가하지 않으므로, 내보낸 다이어그램을 실행할 BPMN 엔진이 지원하는 언어/프로필을 선택하십시오. 루프 데이터 참조는 기존 BPMN ItemAwareElement 인스턴스를 식별해야 합니다. portable 스키마는 벤더별 collection 속성을 내보내지 않습니다. 벤더별 바인딩 또는 버전 속성은 portable BPMN 방언에서 내보내지지 않습니다.

{
  activityType: "callActivity",
  name: "Invoke fulfillment",
  properties: { calledElement: "FulfillmentProcess" }
}

add_gateway

현재 다이어그램에 분기 로직용 게이트웨이를 추가합니다.

{
  gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased, complex
  name: "Payment Check",
  position: { x: 400, y: 200 } // optional
}

add_data_object

표시되는 bpmn:dataObjectReference와 연결된 비렌더링 bpmn:dataObject를 추가합니다. 컬렉션 상태는 백킹 객체에 속합니다. 선택적 itemSubjectRef는 가져온 다이어그램에서 로드된 것과 같은 기존 bpmn:itemDefinition을 식별해야 합니다.

{
  name: "Order records",
  position: { x: 400, y: 320 }, // optional reference position
  isCollection: true, // optional, defaults to false
  itemSubjectRef: "ItemDefinition_Order" // optional existing definition ID
}

데이터 입력/출력 연결은 활동 소유의 BPMN 구성 요소이며 add_association으로 생성되지 않습니다. add_association은 일반 아티팩트 연결로 유지됩니다.

add_text_annotation

BPMN 텍스트 주석을 추가합니다. 텍스트는 줄 바꿈과 XML 메타 문자를 포함하여 정확히 보존됩니다. textFormat은 BPMN의 text/plain으로 기본 설정됩니다. 위치와 크기는 엔진의 주석 지오메트리로 기본 설정됩니다. associatedElementId를 제공하면 주석에서 해당 요소로의 별도 무방향 BPMN 연결도 생성됩니다.

{
  text: "Review the exception path\nbefore approval",
  textFormat: "text/markdown", // optional
  position: { x: 400, y: 320 }, // optional
  size: { width: 220, height: 80 }, // optional
  associatedElementId: "UserTask_1" // optional
}

connect

현재 다이어그램에서 두 요소를 시퀀스 흐름으로 연결합니다.

{
  sourceId: "ExclusiveGateway_1",
  targetId: "UserTask_1",
  label: "Start Flow", // optional
  condition: "amount > 1000", // optional, for conditional sequence flows
  conditionLanguage: "FEEL", // optional
  conditionType: "bpmn:FormalExpression", // optional
  isDefault: false // optional; default flows cannot have conditions
}

조건과 기본 흐름은 활동 및 배타적, 포괄적 또는 복합 게이트웨이에서 지원됩니다. 기본 흐름은 조건을 가질 수 없습니다.

add_association

호환되는 프로세스 또는 협업 범위에서 두 BaseElement 사이에 BPMN 연결 아티팩트를 추가합니다. 이는 시퀀스 및 메시지 흐름과 구별됩니다. associationDirection은 BPMN의 None 값으로 기본 설정됩니다.

{
  sourceId: "TextAnnotation_1",
  targetId: "UserTask_1",
  associationDirection: "One" // None, One, or Both
}

add_pool

협업 다이어그램에 풀(참여자)을 추가합니다.

{
  name: "Customer",
  position: { x: 100, y: 100 }, // optional
  size: { width: 600, height: 250 }, // optional
  blackBox: false // optional; true creates a participant without an owned process
}

add_lane

화이트박스 풀에 레인을 추가하고 직접 프로세스 흐름 노드를 할당합니다. 이미 다른 레인에 할당된 노드는 새 레인으로 이동됩니다.

{
  poolId: "Participant_1",
  name: "Sales Department",
  flowNodeIds: ["StartEvent_1", "UserTask_1"],
  position: "bottom" // optional
}

쿼리 및 조작 도구

list_elements

현재 다이어그램에서 ID 순으로 정렬된 안정적인 요소 및 연결 아티팩트 페이지를 나열합니다. 연결만 나열하려면 elementType: "bpmn:Association"으로 필터링합니다.

{
  elementType: "bpmn:Task", // optional filter
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

응답은 { count, returnedCount, offset, limit, hasMore, elements }입니다. 호환성 참고: 페이지네이션 봉투가 이전의 단순 배열 응답을 대체합니다. 해당 계약에 대해 작성된 클라이언트는 이제 elements를 읽어야 합니다. 기존 요소 필드는 의미를 유지하며 추가 메타데이터 필드와 레인 항목이 포함될 수 있습니다.

get_element

특정 요소 또는 연결의 세부 정보를 가져옵니다.

{
  elementId: "UserTask_1"
}

update_element

요소 속성을 업데이트합니다.

{
  elementId: "UserTask_1",
  name: "Updated Task Name",
  properties: { assignee: "john.doe", candidateGroups: ["reviewers"] },
  defaultFlow: "Flow_2" // outgoing flow ID, or null to clear
}

delete_element

요소와 그에 연결된 연결을 삭제합니다. 연결 ID를 전달하면 해당 연결만 삭제되고 끝점은 그대로 유지됩니다. 텍스트 주석을 포함한 끝점을 삭제하면 해당 연결로 계단식 삭제됩니다.

{
  elementId: "Task_1"
}

유틸리티 도구

export

현재 다이어그램을 BPMN 2.0 XML 또는 렌더링된 SVG로 내보냅니다.

{
  format: "xml", // "xml" or "svg"; defaults to "xml"
  formatted: true // optional; applies to XML and defaults to true
}

XML 내보내기는 텍스트를 반환하며 브라우저를 실행하지 않습니다. SVG 내보내기는 Puppeteer를 통해 헤드리스 브라우저를 실행하고 bpmn-js로 렌더링한 후 결과를 살균하고 포함된 image/svg+xml 리소스를 반환합니다. 사용 가능한 Chrome/Chromium 실행 파일이 필요하며 라이선스에 설명된 표시되는 bpmn.io 저작자 표시를 유지합니다.

validate

현재 다이어그램 구조를 검증합니다.

{
  level: "full" // "syntax", "semantic", or "full"; defaults to "full"
}

검증 수준은 누적됩니다. syntax는 XML을 구문 분석하고 참조를 해석합니다. semantic은 소유자 인식 이벤트, 흐름, 서브프로세스, 레인 및 협업 규칙을 추가합니다. full은 실행 가능한 프로필 시작/종료/연결성 지침도 추가합니다.

auto_layout

현재 다이어그램의 요소 위치를 자동 레이아웃으로 지정합니다.

{
  algorithm: "horizontal" // currently only horizontal is supported
}

레이아웃은 기본 5초 예산으로 종료 가능한 하위 프로세스에서 실행됩니다. 벤치마크 기반 사전 검사는 최대 2,000개 요소, 2,000개 연결 및 요소당 10개 연결을 허용합니다. 제한을 초과하는 입력은 레이아웃 전에 거부됩니다. 협업의 경우 각 참여자 프로세스가 독립적으로 순위가 매겨지므로 메시지 흐름이 시퀀스 흐름 순서를 변경하지 않습니다. 자동 레이아웃은 수동 노드 및 컨테이너 좌표를 대체하지만 요청/가져온 참여자 및 레인 치수는 하한으로 유지됩니다. 그런 다음 풀은 겹침 없이 쌓입니다. 레인과 소유 노드는 포함된 상태로 유지되고 메시지 흐름은 최종 풀 배치 후에만 라우팅됩니다. 연결되지 않은 노드는 소유 프로세스 내에서 결정적으로 패킹되고, 중첩 서브프로세스는 의미론적 포함을 유지하며, 블랙박스 참여자는 제작된 프로세스 콘텐츠 없이 요청된 최소 크기를 유지합니다.

파일 관리 도구

list_diagrams

저장된 BPMN 다이어그램의 파일 이름 순으로 정렬된 안정적인 페이지를 나열합니다.

{
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

기존 { count, diagrams, path } 응답 필드는 계속 사용할 수 있습니다. returnedCount, offset, limit 및 hasMore는 선택된 페이지를 설명합니다. 선택된 페이지의 파일만 포함된 BPMN 메타데이터를 위해 읽히며 집계 메타데이터 읽기는 기본적으로 5 MiB로 제한됩니다.

delete_diagram_file

저장된 다이어그램 파일을 삭제합니다.

{
  filename: "old-process.bpmn"
}

get_diagrams_path

다이어그램의 저장 경로를 가져옵니다.

{}

🔄 컨텍스트 관리

MCP-BPMN 서버는 한 번에 하나의 다이어그램으로 작업하는 상태 저장 설계를 사용합니다:

1. 생성 또는 열기: 새 다이어그램(new_bpmn, new_from_mermaid)을 생성하거나 기존 다이어그램(open_bpmn, open_mermaid_file)을 엽니다

2. 조작: 모든 작업(add_event, connect 등)은 현재 다이어그램에 적용됩니다

3. 저장: save 또는 save_as로 작업을 저장합니다

4. 닫기: close로 현재 다이어그램을 닫습니다

현재 컨텍스트 없이 작업을 수행하려고 하면 도움이 되는 오류 메시지가 표시됩니다:

No current context. Please create a diagram first with:
  - new_bpmn(name) to create a new BPMN diagram
  - new_from_mermaid(name, mermaidCode) to convert from Mermaid
  - open_bpmn(filename) to open an existing BPMN file
  - open_mermaid_file(filename) to convert a Mermaid file

💡 예제

예제 1: 승인 프로세스 처음부터 만들기

// Step 1: Create a new process (sets it as current context)
await new_bpmn({ name: "Approval Workflow" });

// Step 2: Add elements (all operations apply to current diagram)
await add_event({ eventType: "start", name: "Request Received" });
await add_activity({ activityType: "userTask", name: "Review Request" });
await add_gateway({ gatewayType: "exclusive", name: "Approved?" });
await add_activity({ activityType: "serviceTask", name: "Process Approval" });
await add_activity({ activityType: "userTask", name: "Handle Rejection" });
await add_event({ eventType: "end", name: "Complete" });

// Step 3: Connect elements
await connect({ sourceId: "StartEvent_1", targetId: "UserTask_1" });
await connect({ sourceId: "UserTask_1", targetId: "ExclusiveGateway_1" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "ServiceTask_1", label: "Yes" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "UserTask_2", label: "No" });
await connect({ sourceId: "ServiceTask_1", targetId: "EndEvent_1" });
await connect({ sourceId: "UserTask_2", targetId: "EndEvent_1" });

// Step 4: Apply auto-layout for proper positioning
await auto_layout();

// Step 5: Save and export the diagram
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

예제 2: Mermaid에서 부트스트랩 (낮은 토큰 사용에 권장)

// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({ 
  name: "Approval Workflow",
  extensionProfile: "camunda7",
  mermaidCode: `
    graph TD
      A((Request Received)) --> B[Review Request]
      B --> C{Approved?}
      C -->|Yes| D[Process Approval]
      C -->|No| E[Handle Rejection]
      D --> F((Complete))
      E --> F
  `
});

// Step 2: Apply auto-layout (Mermaid conversion includes basic layout)
await auto_layout();

// Step 3: Make additional edits if needed
await update_element({ 
  elementId: "UserTask_1", 
  properties: { assignee: "reviewer" }
});

// Step 4: Save and export
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

예제 3: 여러 다이어그램 작업

// Create first diagram
await new_bpmn({ name: "Process A" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task A" });
await save_as({ filename: "process-a.bpmn" });

// Create second diagram (automatically closes the first)
await new_bpmn({ name: "Process B" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task B" });
await save_as({ filename: "process-b.bpmn" });

// Go back to first diagram
await open_bpmn({ filename: "process-a.bpmn" });
await add_event({ eventType: "end" });
await save();

// Check current diagram info
const info = await current();
console.log(info); // Shows: { name: "Process A", filename: "process-a.bpmn", ... }

🗂️ 파일 저장

BPMN 다이어그램은 로컬 파일 시스템에 자동으로 저장됩니다:

• Unix/Linux/Mac: ~/mcp-bpmn/

• Windows: %USERPROFILE%\mcp-bpmn\

환경 변수를 통한 사용자 지정 경로:

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

리소스 제한은 MCP_BPMN_MAX_IMPORT_BYTES, MCP_BPMN_MAX_MERMAID_BYTES, MCP_BPMN_MAX_LAYOUT_ELEMENTS, MCP_BPMN_MAX_LAYOUT_CONNECTIONS, MCP_BPMN_MAX_LAYOUT_DENSITY, MCP_BPMN_MAX_LAYOUT_BYTES, MCP_BPMN_MAX_CONCURRENT_LAYOUTS, MCP_BPMN_MAX_LISTING_ITEMS, MCP_BPMN_MAX_LISTING_METADATA_BYTES 및 MCP_BPMN_LAYOUT_TIMEOUT_MS로 조정할 수 있습니다. 정상 종료 마감은 MCP_BPMN_SHUTDOWN_TIMEOUT_MS로 재정의할 수 있습니다. 기본값은 가져오기/레이아웃 입력 및 목록 메타데이터 페이지당 5 MiB, 레이아웃 요소/연결 2,000개, 밀도 10, 동시 레이아웃 하위 프로세스 2개, 목록 후보 10,000개, 5,000ms입니다. 레이아웃 기본값은 로컬 희소/밀집 벤치마크에서 비롯됩니다: 2,000/1,999는 약 1.4초, 25/300은 약 4.8초, 26/325는 5초를 초과했습니다.

SIGINT, SIGTERM 또는 stdin EOF 시 서버는 도구 호출 수락을 중지하고 렌더러/레이아웃 하위 프로세스와 stdio 전송을 닫기 전에 수락된 작업과 원자적 영속성이 완료되도록 허용합니다. 정상 종료에는 15초의 하드 마감이 있으며 이를 초과하면 0이 아닌 종료가 강제됩니다.

새 다이어그램은 파일 이름 {ProcessId}_{ProcessName}.bpmn으로 시작합니다. 각 다이어그램은 정확히 하나의 활성 파일 이름을 가집니다. 열기는 열린 파일 이름을 채택하고, save_as는 새 파일이 성공적으로 기록된 후에 파일 이름을 전환합니다. 추가, 업데이트, 삭제, 연결 및 레이아웃 작업은 활성 파일을 직렬화하고 원자적으로 자동 저장합니다. 직렬화 또는 쓰기 실패 시 메모리와 디스크 모두 마지막 성공 상태로 유지됩니다.

🏗️ 아키텍처

기술 스택

• TypeScript - 타입 안전 개발

• Node.js - 런타임 환경

• MCP SDK - Model Context Protocol 구현

• Jest - 테스트 프레임워크

핵심 구성 요소

• SimpleBpmnEngine - 표준 BPMN 문서 변형, 영속화 및 XML 내보내기

• BpmnSvgRenderer - 격리된 브라우저 기반 bpmn-js SVG 렌더링

• DiagramContext - 현재 다이어그램의 상태 저장 컨텍스트 관리

• BpmnAutoLayoutV2Adapter - BPMN 자동 레이아웃 통합

• BpmnRequestHandler - MCP 요청 처리

• MermaidConverter - Mermaid에서 BPMN으로 변환

• TypeMappings - BPMN 요소 유형 변환

• IdGenerator - 일관된 ID 생성

프로젝트 구조

mcp-bpmn/
├── src/
│   ├── core/           # Core BPMN engine
│   ├── server/         # MCP server implementation
│   ├── utils/          # Utilities (layout, ID generation)
│   ├── types/          # TypeScript type definitions
│   └── config/         # Configuration
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── e2e/           # End-to-end tests
├── dist/              # Compiled output
└── docs/              # Documentation

🧪 개발

사용 가능한 스크립트

npm run build        # Build TypeScript
npm run build:bundle # Build CommonJS bundle
npm run build:watch  # Build with watch mode
npm run check        # Complete clean contributor/CI quality gate
npm test            # Run source-level tests (no build output required)
npm run test:all    # Clean, build, and run every test including e2e
npm run test:unit   # Run unit tests only
npm run test:integration # Run integration tests only
npm run test:e2e    # Run end-to-end tests
npm run lint        # Run ESLint
npm run dev         # Development mode with hot reload
npm start           # Start the MCP server

테스트

이 프로젝트는 포괄적인 테스트 범위를 포함합니다. 소스 수준 명령은 dist/를 읽지 않으므로 이전 빌드가 결과에 영향을 미칠 수 없습니다:

• 단위 테스트: 핵심 기능 테스트

• 통합 테스트: 핸들러 및 도구 테스트

• E2E 테스트: 전체 MCP 프로토콜 테스트

다음으로 테스트를 실행합니다:

npm test                    # Source-level tests
npm run test:all            # Clean build plus all tests
npm run check               # Complete clean contributor/CI quality gate
npm run test:coverage       # Source-level tests with coverage
npm run test:watch          # Source-level tests in watch mode

📈 성능

정식 릴리스 아티팩트는 2026-08-22에 Node 25.9.0 및 npm 11.12.1을 사용하여 다음 명령으로 측정되었습니다:

npm pack --dry-run --json

해당 명령은 압축 시 약 195 kB, 압축 해제 시 1104270 바이트를 보고했습니다. 이 수치는 npm tarball을 설명하며 설치된 서버가 아닙니다. tarball은 프로덕션 종속성을 포함하지 않는 반면, 설치 시 package.json의 9개 직접 런타임 종속성과 그 전이 종속성을 해결합니다. Puppeteer의 관리형 Chrome 다운로드도 tarball 측정 범위 밖입니다. 이 날짜가 기록된 스냅샷을 영구적인 크기 보장으로 취급하지 말고 현재 아티팩트에 대해 명령을 다시 실행하십시오.

선택적 CommonJS 번들은 릴리스 아티팩트가 아니며 크기 보장이 없습니다. 레이아웃 입력 제한과 기본값 선택에 사용된 날짜가 기록된 벤치마크 관찰은 파일 저장 아래에 문서화되어 있습니다.

🐛 알려진 제한 사항

• 작성 API는 완전한 BPMN 2.0 범위가 아닌 집중된 BPMN 2.0 하위 집합입니다. 지원되지 않는 가져온 구성은 무손실 편집 대신 거부될 수 있습니다.

• connect는 직접 메시지 흐름 작성을 노출하지 않습니다. Mermaid 협업 하위 집합은 하위 그래프 간에 메시지 흐름을 생성할 수 있습니다.

• add_lane은 화이트박스 풀에서 최상위 레인을 작성합니다. 가져온 중첩 레인 계층을 확장할 수 없습니다.

• 자동 레이아웃은 가로 레이아웃만 지원합니다. 세로 및 방사형 알고리즘은 제공되지 않습니다.

• 검증은 문서화된 구문, 의미 및 전체 지침 수준을 제공합니다. BPMN XSD 인증 또는 배포 엔진에 대한 검증이 아닙니다.

• Camunda 7 작성 프로필은 사용자 태스크의 assignee, candidateGroups 및 dueDate로 제한됩니다. 일반적인 Camunda 모델러 범위가 아닙니다.

• SVG 내보내기는 Puppeteer를 통한 Chrome/Chromium이 필요하며 서버 인스턴스당 동시 렌더링을 하나만 허용합니다. XML 워크플로는 브라우저 없이 유지됩니다.

• 서버는 BPMN 프로세스를 실행, 시뮬레이션 또는 배포하지 않습니다.

🚧 로드맵

계획된 작업과 알려진 격차는 이 릴리스 문서에서 구현된 기능으로 약속되지 않고 Beads 이슈로 추적됩니다.

🤝 기여

기여를 환영합니다! 다음을 수행해 주세요:

1. 저장소를 포크합니다

2. 기능 브랜치를 생성합니다 (git checkout -b feature/amazing-feature)

3. 전체 품질 게이트를 실행합니다 (npm run check)

4. 변경 사항을 커밋합니다 (git commit -m 'Add amazing feature')

5. 브랜치에 푸시합니다 (git push origin feature/amazing-feature)

6. Pull Request를 엽니다

코드 스타일

• 엄격 모드의 TypeScript

• ESLint 구성 제공

• Jest 테스트

• 기존 커밋 규칙

📝 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

SVG 내보내기는 bpmn-js@17.11.1을 사용합니다. 내보낸 모든 SVG에는 https://bpmn.io에 연결된 보이는 "Powered by bpmn.io" 로고가 포함됩니다. 클라이언트는 해당 표시를 자르거나, 가리거나, 제거해서는 안 됩니다. 종속성의 라이선스 조건은 THIRD_PARTY_NOTICES.md를, 릴리스 결정은 ADR 0002를 참조하세요.

📞 지원

• 이슈: GitHub Issues

• 문서: 자세한 가이드는 /docs 폴더를 참조하세요

🙏 감사의 말

• Model Context Protocol 사양을 기반으로 구축됨

• BPMN 표준에 대해 bpmn-js에서 영감을 받음

• MCP 개발에 기여한 Anthropic 팀에 감사드립니다