MCP-BPMN Server

Сервер Model Context Protocol (MCP) для проверенного подмножества авторства BPMN 2.0, включая преобразование Mermaid, локальное сохранение, компоновку, валидацию и экспорт в XML или SVG.

🎯 Обзор

MCP-BPMN предоставляет интерфейс с состоянием для ИИ-ассистентов, позволяющий работать с одной диаграммой бизнес-процесса за раз. Он создает корректный XML BPMN 2.0 для перечисленных ниже конструкций; это не полный редактор BPMN 2.0, не исполнительный движок и не клиент развертывания. Переносимое ядро BPMN является контрактом авторства по умолчанию, с опциональным типизированным профилем Camunda 7, описанным в ADR 0001.

Ключевые возможности

• Целенаправленное авторство BPMN: поддерживаемые события, действия, шлюзы, объекты данных, аннотации, пулы, дорожки верхнего уровня, потоки управления и ассоциации

• Преобразование Mermaid: начальные диаграммы из документированного подмножества блок-схем

• Горизонтальная автоматическая компоновка: детерминированное размещение процессов и коллабораций

• Локальное сохранение: атомарное сохранение и повторное открытие диаграмм в настроенной директории

• Экспорт в XML и SVG: XML генерируется в процессе; SVG отображается через Puppeteer и bpmn-js

• Профили Portable и Camunda 7: вывод без привязки к вендору по умолчанию, с тремя типизированными полями пользовательских задач Camunda 7 при явном выборе

Related MCP server: BPMN-MCP

🚀 Быстрый старт

Требования

• Node.js 22.12.0 или новее

• npm с поддержкой lockfile

• Chrome или Chromium для export({ format: "svg" }); обычная установка Puppeteer загружает совместимый браузер

Авторство XML, валидация, компоновка, сохранение и экспорт XML не запускают браузер. Экспорт SVG — запускает. Если загрузка браузера Puppeteer намеренно пропущена, установите PUPPETEER_EXECUTABLE_PATH на совместимый исполняемый файл Chrome или Chromium перед запуском сервера. Рендеринг SVG выполняется в фоновом режиме, ограничен одним одновременным рендером на экземпляр сервера и имеет двадцатисекундный тайм-аут рендеринга.

Запуск из исходного кода

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

Установка упакованного релизного артефакта

В этом репозитории документируется установка npm-тарбола, а не предполагается, что mcp-bpmn-server доступен в публичном реестре npm. Производитель релиза может собрать канонический артефакт только для CLI из исходного кода:

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

Установите этот тарбол в выделенную директорию потребителя и запустите его упакованный исполняемый файл:

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. Пакет является CLI, а не импортируемой библиотекой JavaScript.

Установка для Claude Code и Codex

Из исходного кода установщик упаковывает текущий релиз в стабильное пользовательское расположение, регистрирует его MCP-сервер и устанавливает навык bpmn-modeler для каждого поддерживаемого клиента, найденного в PATH:

make install
make doctor

Расположение программы по умолчанию — ~/.local/share/mcp-bpmn, а диаграммы остаются вне установки в ~/mcp-bpmn. Навык копируется в ~/.codex/skills/bpmn-modeler для Codex и в ~/.claude/skills/bpmn-modeler для Claude Code. Перезапустите клиенты после установки, чтобы они обнаружили новый навык и MCP-сервер.

Установка идемпотентна: повторный запуск make install заменяет только файлы и регистрации, принадлежащие этому установщику. Существующие сторонние регистрации или директории навыков сохраняются, если только не запрошена замена с помощью FORCE=1. Нацельтесь на один клиент, обновите существующую установку или удалите, сохранив диаграммы, с помощью:

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

Установите PREFIX, чтобы изменить расположение программы, и MCP_BPMN_DIAGRAMS_PATH, чтобы использовать другую абсолютную директорию диаграмм. Предварительно собранный релизный тарбол можно воспроизводимо установить, задав как MCP_BPMN_PACKAGE_TARBALL, так и его обязательный MCP_BPMN_PACKAGE_SHA256. Запустите ./scripts/install-agent-integrations.sh --help для полного интерфейса. Установщик поддерживает macOS и Linux, включая WSL с Linux-нативным Node.js и клиентскими CLI.

Локальная разработка плагина Codex

Релизный артефакт также является плагином Codex. Его манифест обнаруживает канонический навык skills/bpmn-modeler и запускает один stdio-сервер mcp-bpmn через лаунчер, скопированный в кэш плагина. Лаунчер использует стабильный приватный релиз, установленный с помощью 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: инструменты, помеченные как read-only, могут выполняться автоматически, а мутации диаграмм остаются видимыми для одобрения. Удалите установку для разработки с помощью:

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

Запустите изолированный маркетплейс, кэш, обнаружение, запуск MCP и удаление без изменения реальной конфигурации Codex:

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 для проверки навыка и выполните /reload-plugins после изменения манифеста или конфигурации MCP. Исходный код содержит корневой CLAUDE.md для участников репозитория, поэтому проверка исходного кода сообщает, что это не контекст плагина; команда все равно завершается успешно. Упакованный плагин исключает этот файл, предназначенный только для репозитория, и проходит строгую проверку.

Запустите полный локальный маркетплейс smoke-тест с помощью:

npm run test:claude-plugin

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

Диаграммы никогда не записываются в ${CLAUDE_PLUGIN_ROOT}. Они остаются в MCP_BPMN_DIAGRAMS_PATH, если он задан, или в ~/mcp-bpmn по умолчанию, поэтому перезагрузки, обновления, отключение и удаление плагина не удаляют их. Перед переходом с ручной регистрации MCP в Claude на плагин проверьте claude mcp list и удалите старую регистрацию mcp-bpmn, если её команда отличается от конечной точки плагина; Claude дедуплицирует только плагины и пользовательские серверы, которые разрешаются в одну и ту же команду.

Оценка рабочих процессов агентов

Канонический машиночитаемый корпус — evals/bpmn-modeler/cases.json. Оба клиентских адаптера используют эти точные подсказки и семантические ожидания. Детерминированная проверка безопасна для обычной разработки и CI: она проверяет границы активации, метаданные навыка, имена инструментов, паритет клиентов и последовательность create/mutate/validate/layout/validate/export без вызова модели:

npm run test:evaluations

Аутентифицированные запуски моделей являются опциональными. Сначала соберите, затем выберите один ограниченный случай при итерации:

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

Адаптер Codex запускает codex exec во временном проекте, содержащем канонический навык и конфигурацию MCP stdio в области проекта. Адаптер Claude материализует те же случаи как нативные случаи claude plugin eval во временной копии плагина. Оба устанавливают MCP_BPMN_DIAGRAMS_PATH во временную директорию, копируют туда только объявленные фикстуры настройки и удаляют директорию после; они никогда не читают, не перезаписывают и не удаляют диаграммы из реального хранилища пользователя. Опустите --case, чтобы запустить полный корпус. Эти команды могут потреблять квоту модели и намеренно исключены из npm run check и CI.

Опциональный CommonJS-бандл

CommonJS-бандл — это отдельная сборка из исходного кода, которая не создается npm run build и не включена в канонический npm-тарбол:

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

Создайте новую BPMN-диаграмму из кода Mermaid и установите её как текущий контекст.

{
  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. Броски компенсации могут включать activityRef и waitForCompletion; граничные события компенсации являются не прерывающими.

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, идентифицирующий вызываемый элемент; он не обязан соответствовать идентификатору процесса в текущей диаграмме.

Действия могут использовать стандартные характеристики мультиэкземплярного цикла 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; переносимая схема не генерирует атрибут collection, специфичный для вендора. Специфичные для вендора атрибуты привязки или версии не генерируются переносимым диалектом 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_text_annotation

Добавить текстовую аннотацию BPMN. Текст сохраняется точно, включая разрывы строк и XML-метасимволы. textFormat по умолчанию равен text/plain BPMN; позиция и размер по умолчанию соответствуют геометрии аннотации движка. Указание 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

Добавить артефакт ассоциации BPMN между двумя BaseElements в совместимой области процесса или коллаборации. Это отличается от потоков последовательности и сообщений. associationDirection по умолчанию равен значению None BPMN.

{
  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

Экспортировать текущую диаграмму как XML BPMN 2.0 или отрендеренный 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
}

Раскладка выполняется в завершаемом подпроцессе с бюджетом по умолчанию пять секунд. Предварительная проверка на основе бенчмарков принимает не более 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 МиБ по умолчанию.

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 МиБ на импортированный/раскладываемый вход и на страницу метаданных списка, 2 000 элементов/соединений раскладки, плотность 10, два одновременных подпроцесса раскладки, 10 000 кандидатов в списке и 5 000 мс. Значения по умолчанию для раскладки взяты из локальных разреженных/плотных бенчмарков: 2 000/1 999 завершились примерно за 1,4 с, 25/300 заняли около 4,8 с, а 26/325 превысили пять секунд.

При SIGINT, SIGTERM или EOF на stdin сервер прекращает принимать вызовы инструментов и позволяет принятым операциям и их атомарному сохранению завершиться, прежде чем закрывает подпроцессы рендерера/раскладки и транспорт stdio. Корректное завершение имеет жёсткий крайний срок 15 секунд; превышение приводит к принудительному ненулевому выходу.

Новые диаграммы начинаются с имени файла {ProcessId}_{ProcessName}.bpmn. Каждая диаграмма имеет ровно одно активное имя файла: при открытии принимается открытое имя файла, а save_as переключает его после успешной записи нового файла. Операции добавления, обновления, удаления, соединения и компоновки сериализуются и атомарно автосохраняют активный файл; при сбое сериализации или записи и память, и диск остаются в последнем успешном состоянии.

🏗️ Архитектура

Технологический стек

• TypeScript — типобезопасная разработка

• Node.js — среда выполнения

• MCP SDK — реализация Model Context Protocol

• Jest — фреймворк для тестирования

Ключевые компоненты

• SimpleBpmnEngine — каноническое изменение BPMN-документа, сохранение и экспорт в XML

• BpmnSvgRenderer — изолированная отрисовка SVG с помощью bpmn-js в браузере

• DiagramContext — управление контекстом с состоянием для текущей диаграммы

• BpmnAutoLayoutV2Adapter — интеграция с авто-компоновкой BPMN

• BpmnRequestHandler — обработка MCP-запросов

• MermaidConverter — преобразование Mermaid в BPMN

• TypeMappings — преобразования типов элементов BPMN

• IdGenerator — генерация согласованных идентификаторов

Структура проекта

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-тарбол, а не установленный сервер: тарбол не включает производственные зависимости, в то время как установка разрешает девять прямых зависимостей времени выполнения в package.json и их транзитивные зависимости. Управляемая загрузка Chrome через Puppeteer также не входит в измерение тарбола. Повторно запустите команду для текущего артефакта, а не рассматривайте этот устаревший снимок как постоянную гарантию размера.

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

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

• API для создания диаграмм — это сфокусированное подмножество BPMN 2.0, а не полное покрытие BPMN 2.0. Неподдерживаемые импортированные конструкции могут быть отклонены, а не отредактированы без потерь.

• connect не предоставляет прямого создания потоков сообщений. Подмножество совместной работы Mermaid может создавать потоки сообщений между подграфами.

• add_lane создает дорожки верхнего уровня в пулах «белого ящика»; он не может расширить импортированную вложенную иерархию дорожек.

• Авто-компоновка поддерживает только горизонтальную компоновку. Вертикальные и радиальные алгоритмы не заявлены.

• Проверка предоставляет задокументированные уровни синтаксической, семантической и полной проверки; это не сертификация BPMN XSD и не проверка на соответствие движку развертывания.

• Профиль авторинга Camunda 7 ограничен assignee, candidateGroups и dueDate для пользовательских задач. Это не общее покрытие Camunda Modeler.

• Экспорт SVG требует Chrome/Chromium через Puppeteer и допускает только один одновременный рендер на экземпляр сервера. 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 для тестирования

• Conventional commits

📝 Лицензия

Лицензия MIT — см. файл LICENSE для подробностей.

Экспорт SVG использует bpmn-js@17.11.1. Каждый экспортированный SVG включает видимый логотип «Powered by bpmn.io» со ссылкой на https://bpmn.io; клиенты не должны обрезать, закрывать или удалять эту атрибуцию. См. THIRD_PARTY_NOTICES.md для условий лицензии зависимости и ADR 0002 для решения о выпуске.

📞 Поддержка

• Проблемы: GitHub Issues

• Документация: См. папку /docs для подробных руководств

🙏 Благодарности

• Построено на спецификации Model Context Protocol

• Вдохновлено bpmn-js для стандартов BPMN

• Спасибо команде Anthropic за разработку MCP