bizagi-mcp

Превратите описание процесса в диаграмму BPMN 2.0, которая без проблем открывается в Bizagi Modeler.

Сервер MCP, который генерирует, читает, проверяет и показывает диаграммы BPMN 2.0 — и управляет настольным приложением Bizagi Modeler в Windows.

Сгенерировано из JSON-спецификации на 60 строк. Каждая координата выше вычислена, а не расставлена вручную.

Зачем это нужно

У Bizagi Modeler нет API для скриптов. Единственный поддерживаемый путь интеграции — открытый формат BPMN 2.0 XML через вкладку Export / Import.

Но есть загвоздка, из-за которой наивная генерация бесполезна: 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)

Отсутствующие начальные или конечные события · недостижимые элементы · тупики · потоки управления, пересекающие пулы · потоки сообщений внутри одного пула · шлюзы, ветвящиеся без условий · цели шлюзов на основе событий · неявное ветвление и слияние · граничные события на не-действиях · дублирующиеся идентификаторы · поток по умолчанию, который также имеет условие · шлюзы с одним входом и одним выходом.

Соглашения (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 запускается со списком аргументов и без оболочки, поэтому имя файла никогда не может стать командой

• Каждая ошибка возвращается как данные ({"ok": false, ...}), а не как traceback

Тесты

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

72 теста: нормализация спецификаций, порядок элементов XSD, полнота BPMNDI, все перечисленные выше гарантии раскладки, коллизии подписей, циклы преобразований, каждое правило валидации, обход путей, выбор кнопок ленты, проверка захвата фокуса и контракт ошибок каждого инструмента.

Известные ограничения

• .bpm не читается. Это проприетарный формат Bizagi; сначала экспортируйте в BPMN. list_processes по-прежнему перечисляет файлы .bpm и помечает их.

• Управление настольным приложением доступно только в Windows и требует pywinauto.

• Диаграммы генерируются на один уровень вглубь. Подпроцесс отображается как свёрнутая фигура; его содержимое не генерируется.

• Аккуратность раскладки гарантируется для геометрии, записанной в файл. Bizagi размещает имена узлов по собственным правилам, которые секция обмена диаграммами не контролирует.

Лицензия

MIT — см. LICENSE.