bizagi-mcp

Convierte una descripción de un proceso en un diagrama BPMN 2.0 que se abre sin problemas en Bizagi Modeler.

Un servidor MCP que genera, lee, audita y previsualiza diagramas BPMN 2.0 — y controla la aplicación de escritorio Bizagi Modeler en Windows.

Generado a partir de una especificación JSON de 60 líneas. Cada coordenada de arriba fue calculada, no colocada a mano.

Por qué existe esto

Bizagi Modeler no tiene API de scripting. La única vía de integración que admite es el formato abierto BPMN 2.0 XML, a través de su pestaña Export / Import.

Pero hay un detalle que hace inútil la generación ingenua: Bizagi importa las coordenadas escritas en el archivo tal cual. No maqueta un diagrama por ti. Si emites un archivo BPMN estructuralmente perfecto sin geometría, se abre como un montón de cajas apiladas en el origen.

Así que la parte difícil de este servidor no es el XML. Es la maquetación.

Related MCP server: camunda-mcp

Qué hace

Los ocho primeros son Python puro y funcionan en cualquier sistema operativo, con o sin Bizagi instalado. Solo las cuatro herramientas bizagi_* necesitan Windows.

El motor de maquetación

Una maquetación por capas que tiene en cuenta los carriles, en el orden en que se ejecuta:

1. Romper ciclos para que el grafo pueda organizarse en capas

2. Capas por camino más largo → la columna horizontal de cada nodo

3. Ordenación por baricentro por (columna, carril) → menos cruces de líneas

4. Alturas de carril adaptativas, dimensionadas según la celda más alta que contiene cada banda

5. Franjas reservadas — una banda de derivación en la parte superior de cualquier carril que contenga una rama que salta columnas, y una franja de canal en la parte inferior para los bucles de retorno

6. Enrutado ortogonal que rodea los obstáculos en lugar de atravesarlos

7. Separación de etiquetas como pasada final

Qué garantiza

No son aspiraciones. Cada una es una prueba que falla cuando se elimina la regla:

• Ninguna forma se superpone con otra

• Ninguna arista se dibuja a través de una forma que no sea su propio extremo

• Todo elemento se encuentra dentro de su pool

• Los flujos de mensaje circulan por el corredor vacío entre pools, nunca horizontalmente a través de uno

• Cada flujo de mensaje tiene su propia línea en ese corredor, y el corredor se dimensiona según cuántos flujos lo cruzan — para que sus etiquetas no se apilen

• Los bucles de retorno tienen cada uno su propio canal en una franja reservada mientras se dimensionan los carriles

• Una rama que salta columnas se desvía dentro de su propio carril, por encima de las actividades que se salta

• Las ramas de una compuerta salen de puntos visiblemente distintos, de modo que una bifurcación de dos vías no se lea como una sola flecha

• Los flujos de eventos de borde salen hacia abajo, nunca hacia atrás a través de la actividad anfitriona

• Las anotaciones y los almacenes de datos se sitúan junto a lo que describen — o, cuando no tienen asociación, dentro del pool que declaran en lugar de fuera del lienzo

• Ninguna etiqueta se escribe sobre otra etiqueta ni sobre una forma

Notas de diseño

Algunas decisiones en las que es fácil equivocarse:

• Una etiqueta es tan ancha como su texto. Reservar una caja plana para cada etiqueta hace que las colisiones entre las largas sean invisibles para cualquier cosa que mida la caja reservada.

• El espacio reservado debe quedar fuera del centrado. Si agrandas un carril para hacer hueco a un canal y luego centras las formas en él, la mitad del nuevo espacio se devuelve como relleno superior — el canal acaba siendo demasiado estrecho para usarse.

• Un desvío va en los huecos entre formas, no rodeándolas todas. Enrutar por encima o por debajo de todo deja la línea fuera del pool, y las verticales que llegan a ella cruzan entonces todos los carriles de camino.

• Un almacén de datos puede estar asociado a muchas actividades, pero se sitúa junto a una sola. Colocarlo una vez por asociación deja huecos en los carriles donde estaban las colocaciones anteriores.

Instalación

pip install -e .

Para las herramientas de escritorio de Windows:

pip install -e ".[desktop]"

Python ≥ 3.10.

Registro con 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"
      }
    }
  }
}

Si bizagi-mcp no está en PATH:

{
  "mcpServers": {
    "bizagi-modeler": {
      "command": "python",
      "args": ["-m", "bizagi_mcp.server"],
      "env": { "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi" }
    }
  }
}

Para Claude Code: claude mcp add bizagi-modeler -- bizagi-mcp

Variables de entorno

Uso

Generar un diagrama

"Modela una solicitud de permiso: el empleado la envía, el responsable la aprueba o la rechaza, RR. HH. registra el resultado. Guárdalo en D:\Processes\leave.bpmn."

Luego, en Bizagi Modeler: Export / Import ▸ Import ▸ BPMN.

Analizar un modelo existente

Exporta desde Bizagi primero (Export / Import ▸ Export ▸ BPMN), luego:

"Lee D:\Processes\purchasing.bpmn, explícamelo paso a paso y dime qué le pasa."

Ejemplo

Consulta examples/purchase_request.json (la especificación), .bpmn (generado) y .svg (vista previa).

Reglas de validación

Estructura (BPMN001–BPMN020, severidad error / warning)

Faltan eventos de inicio o fin · elementos inalcanzables · callejones sin salida · flujos de secuencia que cruzan pools · flujos de mensaje dentro de un mismo pool · compuertas que ramifican sin condiciones · destinos de compuerta basada en eventos · división y fusión implícitas · eventos de borde en no-actividades · ids duplicados · un flujo por defecto que también lleva una condición · compuertas de una entrada y una salida.

Convenciones (BP001–BP017, severidad warning / info)

Nombres de actividad (verbo + objeto) · compuertas no formuladas como preguntas · ramas sin etiquetar · cobertura de documentación · pools sin carriles · carriles vacíos · tamaño del diagrama · nombres duplicados · pools que nunca intercambian mensajes.

Cada hallazgo nombra el elemento infractor y el paso concreto para corregirlo.

Control de la aplicación de escritorio

bizagi_open es la vía fiable: Modeler acepta un archivo como argumento de línea de comandos, así que no hay que manejar ningún menú.

bizagi_import_bpmn maneja la cinta de opciones, y es honesto al respecto:

• Reclama el primer plano y verifica que lo ha conseguido. Windows deniega SetForegroundWindow a un proceso que no posee el primer plano, y set_focus() devuelve como si hubiera funcionado — hacer clic de todos modos envía un clic de ratón real a lo que sea en lo que el usuario esté trabajando.

• Cuenta las pestañas de diagrama antes y después, e informa imported: true / false basándose en esa evidencia, no en la esperanza.

• Ambos recuentos se toman con la ventana elevada, porque una ventana que está detrás puede devolver un árbol de accesibilidad incompleto.

No hay modo en segundo plano

La importación no puede ejecutarse mientras la máquina se usa para otra cosa. Se probaron tres vías contra Modeler 4.3.0.008 y las tres están cerradas:

La cinta solo responde a la entrada real del ratón en una ventana enfocada. Para ejecuciones desatendidas, dale a Bizagi su propia sesión de Windows o una máquina virtual. Si quieres que eso quede registrado para que nadie lo reintente: esta tabla es el registro.

Seguridad

• Las rutas se resuelven por completo (~, .., enlaces simbólicos) antes de comprobarse, y luego se limitan a BIZAGI_MCP_ROOT cuando está definido

• El análisis XML pasa por defusedxml cuando está disponible (XXE, billion laughs)

• Los archivos nunca se sobrescriben sin overwrite=true

• Bizagi se lanza con una lista de argumentos y sin shell, de modo que un nombre de archivo nunca puede convertirse en un comando

• Cada error se devuelve como datos ({"ok": false, ...}), nunca como un traceback

Pruebas

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

72 pruebas: normalización de la especificación, orden de elementos XSD, completitud de BPMNDI, cada garantía de maquetación mencionada arriba, colisiones de etiquetas, idas y vueltas, cada regla de validación, recorrido de rutas, selección de botones de la cinta, verificación del primer plano y el contrato de error de cada herramienta.

Limitaciones conocidas

• .bpm no se lee. Es el formato propietario de Bizagi; exporta a BPMN primero. list_processes sigue listando los archivos .bpm y los marca.

• El control de escritorio es solo para Windows y necesita pywinauto.

• Los diagramas se generan a un solo nivel de profundidad. Un subproceso aparece como una forma contraída; su contenido no se genera.

• La pulcritud de la maquetación está garantizada para la geometría escrita en el archivo. Bizagi coloca los nombres de los nodos según sus propias reglas, que la sección de intercambio de diagramas no controla.

Licencia

MIT — consulta LICENSE.