bpmn-modeler

BPMN modeler

Use the tools exposed by the mcp-bpmn server. Refer to tools by their semantic names below; the host may display an MCP namespace prefix. Treat each live tool description and input schema as authoritative.

Route the request

1. Determine whether the requested artifact is a single process or a collaboration.
   • Use a process for one participant's control flow when pools and lanes are unnecessary.
   • Use a collaboration for pools or lanes, and when distinct participants or organizations exchange messages. Model each participant as a pool; use lanes only inside white-box pools.
   • Ask a focused question when participant boundaries, ownership, execution profile, or destructive file intent would materially change the model. Otherwise state a small assumption and proceed.
2. Choose the authoring path.
   • Prefer typed tools for edits, collaborations requiring precise ownership, specialized activity/event types, conditions, lanes, data, annotations, or extension-profile fields.
   • Use new_from_mermaid or open_mermaid_file only to bootstrap a diagram that fits the supported flowchart subset. Read references/capabilities.md before choosing Mermaid.
3. Default to the portable extension profile. Use camunda7 only when the user requests its supported execution metadata. Do not translate unsupported profiles into Camunda 7 or portable fields.

Operate on the diagram

1. Establish context with current, new_bpmn, new_from_mermaid, open_bpmn, or open_mermaid_file. If a diagram may already be current, inspect it before switching unless the request clearly authorizes the replacement.
2. For an existing diagram, inspect elements with list_elements and get_element, and inspect relationships with list_connections and get_connection, before editing. Follow pagination until hasMore is false when the complete model matters.
3. Create owners before their contents: collaboration, pools, then pool-owned elements. Create all required elements before relationships. Retain every returned processId, elementId, laneId, connectionId, associationId, and generated filename; never invent or reconstruct server IDs.
4. In collaborations, pass the returned pool processId as ownerId and normally scopeId for its flow nodes. Connect nodes within one scope as sequence flow and across participants as message flow. Let server validation reject illegal endpoints rather than forcing an approximation.
5. Add lanes only after their flow nodes exist. Add sequence flows, message flows, conditions/defaults, and associations only after both endpoints exist.
6. Before changing a connection, call get_connection, then pass its semanticRevision as expectedSemanticRevision to update_connection. Endpoint changes must name sourceId and/or targetId and explicitly set endpointPolicy to snap-to-boundary; do not infer or hand-edit endpoint geometry. On a revision conflict, refresh with get_connection, reassess the current state, and retry only if the requested change is still valid.
7. For a local connection obstruction, call route_connection in its default proposal-only mode with the current geometryRevision. Inspect its diagnostics and score before passing the returned patch directly to apply_geometry_patch; use apply: true only when immediate atomic selection is intended. Do not hand-invent waypoints before trying the router.
8. Run validate at meaningful semantic checkpoints, including after the main control-flow skeleton and after substantial edits. Resolve errors before continuing; report warnings that require user judgment.
9. For creation or edit deliverables, apply auto_layout near the end, after semantic construction, unless the user asks to preserve manual geometry. It replaces coordinates and autosaves. Run validate again at full level after layout. Do not mutate a review-only request.
10. Use export in the requested xml or svg format when the result should be returned inline. Use save_svg or save_png only when the user requests a separate managed artifact filename; set overwrite: true only with explicit replacement intent. Report the active BPMN filename, export or artifact format, validation result, and any warnings.