bizagi-mcp

将流程描述转换为可在 Bizagi Modeler 中干净打开的 BPMN 2.0 图。

一个 MCP 服务器，用于生成、读取、审计和预览 BPMN 2.0 图，并驱动 Windows 上的 Bizagi Modeler 桌面应用。

由一份 60 行的 JSON 规范生成。上面的每个坐标都是计算出来的，而非手工放置。

为什么存在

Bizagi Modeler 没有脚本 API。它支持的唯一集成路径是通过其 Export / Import 选项卡使用开放的 BPMN 2.0 XML 格式。

但有一个让朴素生成变得无用的陷阱：Bizagi 会原样导入文件中写入的坐标。 它不会为你自动布局。如果生成一个结构完美但没有几何信息的 BPMN 文件，打开后就会是一堆堆叠在原点的方框。

因此，这个服务器的难点不在于 XML，而在于布局。

Related MCP server: camunda-mcp

它能做什么

前八个是纯 Python 实现，可在任何操作系统上运行，无论是否安装 Bizagi。只有四个 bizagi_* 工具需要 Windows。

布局引擎

一个感知泳道的分层布局，按运行顺序如下：

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 会话或虚拟机。如果你希望这一点被记录下来以免有人重试：这张表就是记录。

安全

• 路径在检查之前会被完全解析（~、..、符号链接），然后在设置了 BIZAGI_MCP_ROOT 时被限制在该目录内

• XML 解析在可用时通过 defusedxml 进行（XXE、billion laughs）

• 没有 overwrite=true 时绝不覆盖文件

• Bizagi 通过参数列表启动，不使用 shell，因此文件名永远不会变成命令

• 每个错误都以数据形式返回（{"ok": false, ...}），绝不会是 traceback

测试

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

72 项测试：规范标准化、XSD 元素顺序、BPMNDI 完整性、上文列出的每一条布局保证、标签碰撞、往返转换、每条验证规则、路径遍历、功能区按钮选择、前台验证，以及每个工具的错误契约。

已知限制

• 不读取 .bpm。 它是 Bizagi 的专有格式；请先导出为 BPMN。list_processes 仍会列出 .bpm 文件并标记它们。

• 桌面控制仅限 Windows，并且需要 pywinauto。

• 图只生成一层深度。 子流程显示为折叠形状；其内容不会生成。

• 布局整洁性仅对写入文件的几何信息有保证。 Bizagi 按照自己的规则放置节点名称，而图交换部分无法控制这一点。

许可证

MIT — 参见 LICENSE。