Servidor MCP-BPMN

Un servidor del Model Context Protocol (MCP) para un subconjunto probado de autoría de BPMN 2.0, incluyendo conversión a Mermaid, persistencia local, diseño, validación y exportación a XML o SVG.

🎯 Resumen

MCP-BPMN proporciona una interfaz con estado para que los asistentes de IA trabajen con un diagrama de proceso de negocio a la vez. Autoriza XML de BPMN 2.0 bien formado para los constructos que se enumeran a continuación; no es un editor completo de BPMN 2.0, un motor de ejecución ni un cliente de despliegue. El núcleo portátil de BPMN es el contrato de autoría predeterminado, con un perfil tipado opcional de Camunda 7 documentado en ADR 0001.

Características clave

• Autoría enfocada de BPMN: Eventos, actividades, compuertas, objetos de datos, anotaciones, piscinas, carriles de nivel superior, flujos de secuencia y asociaciones admitidos

• Conversión a Mermaid: Iniciar diagramas desde el subconjunto documentado de diagramas de flujo

• Diseño automático horizontal: Colocación determinista de procesos y colaboraciones

• Persistencia local: Guardar y reabrir diagramas atómicamente en un directorio configurado

• Exportación a XML y SVG: El XML se genera en el proceso; el SVG se renderiza mediante Puppeteer y bpmn-js

• Perfiles portátil y Camunda 7: Salida sin proveedor por defecto, con tres campos tipados de tarea de usuario de Camunda 7 cuando se seleccionan explícitamente

Related MCP server: BPMN-MCP

🚀 Inicio rápido

Requisitos

• Node.js 22.12.0 o más reciente

• npm con soporte de lockfile

• Chrome o Chromium para export({ format: "svg" }); la instalación normal de Puppeteer descarga un navegador compatible

La autoría de XML, la validación, el diseño, la persistencia y la exportación a XML no inician un navegador. La exportación a SVG sí lo hace. Si la descarga del navegador de Puppeteer se omite intencionalmente, establezca PUPPETEER_EXECUTABLE_PATH a un ejecutable compatible de Chrome o Chromium antes de iniciar el servidor. El renderizado SVG es sin cabeza, limitado a un renderizado concurrente por instancia del servidor y tiene un tiempo de espera de renderizado de veinte segundos.

Ejecutar desde un checkout de la fuente

git clone https://github.com/oisee/mcp-bpmn.git
cd mcp-bpmn
npm ci
npm run build
npm start

npm run build emite el ejecutable ESM canónico en dist/server/index.js. El servidor usa stdio, por lo que normalmente parece inactivo cuando se inicia en una terminal y está destinado a ser lanzado por un cliente MCP.

Configuración

Para Claude Desktop

Agregue a su archivo de configuración de 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"]
    }
  }
}

Para otros clientes MCP

Use el mismo punto de entrada ESM con una ruta absoluta:

node /absolute/path/to/mcp-bpmn/dist/server/index.js

Instalar un artefacto de lanzamiento empaquetado

Este repositorio documenta actualmente una instalación de tarball de npm en lugar de asumir que mcp-bpmn-server está disponible en el registro público de npm. Un productor de lanzamientos puede construir el artefacto canónico solo CLI desde un checkout de la fuente:

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

Instale ese tarball en un directorio de consumidor dedicado y ejecute su ejecutable empaquetado:

consumer_dir=$(mktemp -d)
npm install --prefix "$consumer_dir" "$artifact_dir"/mcp-bpmn-server-*.tgz
"$consumer_dir/node_modules/.bin/mcp-bpmn-server"

Para un cliente MCP, use el valor absoluto de $consumer_dir/node_modules/.bin/mcp-bpmn-server como command y un array args vacío. El paquete es una CLI, no una biblioteca de JavaScript importable.

Instalar para Claude Code y Codex

Desde un checkout de la fuente, el instalador empaqueta la versión actual en una ubicación estable propiedad del usuario, registra su servidor MCP e instala la habilidad bpmn-modeler para cada cliente compatible encontrado en PATH:

make install
make doctor

La ubicación predeterminada del programa es ~/.local/share/mcp-bpmn, mientras que los diagramas permanecen fuera de la instalación en ~/mcp-bpmn. La habilidad se copia a ~/.codex/skills/bpmn-modeler para Codex y a ~/.claude/skills/bpmn-modeler para Claude Code. Reinicie los clientes después de la instalación para que descubran la nueva habilidad y el servidor MCP.

La instalación es idempotente: ejecutar make install nuevamente reemplaza solo los archivos y registros propiedad de este instalador. Las registraciones de terceros existentes o los directorios de habilidades se conservan a menos que se solicite explícitamente el reemplazo con FORCE=1. Apunte a un cliente, actualice una instalación existente o desinstale mientras preserva los diagramas con:

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

Establezca PREFIX para cambiar la ubicación del programa y MCP_BPMN_DIAGRAMS_PATH para usar un directorio de diagramas absoluto diferente. Un tarball de lanzamiento precompilado se puede instalar de manera reproducible estableciendo tanto MCP_BPMN_PACKAGE_TARBALL como su MCP_BPMN_PACKAGE_SHA256 requerido. Ejecute ./scripts/install-agent-integrations.sh --help para la interfaz completa. El instalador admite macOS y Linux, incluido WSL con Node.js nativo de Linux y CLIs de cliente.

Desarrollar el plugin de Codex localmente

El artefacto de lanzamiento también es un plugin de Codex. Su manifiesto descubre la habilidad canónica skills/bpmn-modeler e inicia un servidor stdio mcp-bpmn a través de un lanzador copiado en la caché del plugin. El lanzador usa la versión privada estable instalada por make install-codex; no ejecuta TypeScript ni depende del checkout después de la instalación.

Construya el artefacto de lanzamiento, agregue este checkout como un marketplace de repositorio temporal e instale el plugin con:

npm ci
npm run build
make install-codex
codex plugin marketplace add .
codex plugin list --available
codex plugin add mcp-bpmn@mcp-bpmn-local

Inicie una nueva conversación de Codex después de la instalación para que la habilidad y las herramientas MCP se carguen. El servidor incluido tiene como valor predeterminado el modo de aprobación writes: las herramientas marcadas como de solo lectura pueden ejecutarse automáticamente, mientras que las mutaciones de diagramas permanecen visibles para su aprobación. Elimine la instalación de desarrollo con:

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

Ejecute el marketplace aislado, la caché, el descubrimiento, el inicio de MCP y la prueba de humo de eliminación sin cambiar la configuración real de Codex:

npm run test:codex-plugin

Desarrollar el plugin de Claude Code localmente

El artefacto de lanzamiento también es un plugin de Claude Code. Claude descubre la habilidad canónica skills/bpmn-modeler/SKILL.md como la habilidad con espacio de nombres /mcp-bpmn:bpmn-modeler e inicia el servidor mcp-bpmn en línea desde la caché del plugin. El plugin usa skills/; no lleva una copia heredada de commands/.

Desde un checkout de la fuente, instale las dependencias, construya, valide y cargue el plugin para una sesión de desarrollo:

npm ci
npm run build
claude plugin validate .
claude --plugin-dir .

Dentro de Claude Code, use /mcp para confirmar el servidor proporcionado por el plugin, invoque /mcp-bpmn:bpmn-modeler para inspeccionar la habilidad y ejecute /reload-plugins después de cambiar el manifiesto o la configuración de MCP. El checkout contiene un CLAUDE.md raíz para los contribuyentes del repositorio, por lo que la validación de la fuente informa que no es contexto de plugin; el comando aún tiene éxito. El plugin empaquetado excluye ese archivo solo del repositorio y pasa la validación estricta.

Ejecute la prueba de humo completa del marketplace local con:

npm run test:claude-plugin

Esa verificación usa un hogar y marketplace temporales de Claude. Instala un artefacto de lanzamiento copiado, verifica el inventario de componentes de Claude, lanza el servidor MCP en caché, ejercita una recarga y luego deshabilita, habilita y elimina el plugin. No cambia la configuración real de Claude del desarrollador.

Los diagramas nunca se escriben en ${CLAUDE_PLUGIN_ROOT}. Permanecen en MCP_BPMN_DIAGRAMS_PATH cuando se establece, o en ~/mcp-bpmn por defecto, por lo que las recargas, actualizaciones, deshabilitaciones y eliminaciones del plugin no los eliminan. Antes de cambiar de una registración manual de MCP de Claude al plugin, inspeccione claude mcp list y elimine la registración antigua de mcp-bpmn si su comando difiere del punto final del plugin; Claude solo deduplica los servidores de plugin y de usuario que se resuelven al mismo comando.

Evaluar flujos de trabajo de agentes

El corpus canónico legible por máquina es evals/bpmn-modeler/cases.json. Ambos adaptadores de cliente consumen esos prompts exactos y expectativas semánticas. La verificación determinista es segura para el desarrollo normal y CI: verifica los límites de activación, los metadatos de habilidad, los nombres de herramientas, la paridad de clientes y la secuencia crear/mutar/validar/diseñar/validar/exportar sin llamar a un modelo:

npm run test:evaluations

Las ejecuciones de modelo autenticadas son opcionales. Construya primero, luego seleccione un caso acotado mientras itera:

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

El adaptador de Codex ejecuta codex exec en un proyecto temporal que contiene la habilidad canónica y una configuración de MCP stdio con ámbito de proyecto. El adaptador de Claude materializa los mismos casos como casos nativos de claude plugin eval en una copia temporal del plugin. Ambos establecen MCP_BPMN_DIAGRAMS_PATH a un directorio temporal, copian solo los fixtures de configuración declarados allí y eliminan el directorio después; nunca leen, sobrescriben ni eliminan diagramas del almacén real del usuario. Omita --case para ejecutar el corpus completo. Estos comandos pueden consumir cuota de modelo y están excluidos intencionalmente de npm run check y CI.

Paquete CommonJS opcional

El paquete CommonJS es una compilación separada del checkout de la fuente y no se produce con npm run build ni se incluye en el tarball canónico de npm:

npm run build:bundle
npm run start:bundle

📚 Referencia de la API

Gestión de contexto con estado

MCP-BPMN utiliza un diseño de API con estado donde se trabaja con un diagrama a la vez. Todas las operaciones se aplican al contexto de diagrama actual, eliminando la necesidad de parámetros de processId.

Matriz de herramientas anunciadas

Los encabezados de esta referencia de API enumeran cada herramienta devuelta por tools/list. La línea base de paridad ejecutable es tests/contracts/engine-contract.test.ts, con comportamiento enfocado en las suites de unidad, integración y extremo a extremo.

Cada herramienta anunciada también incluye las anotaciones estándar de MCP readOnlyHint, destructiveHint, idempotentHint y openWorldHint. Estas anotaciones describen el comportamiento observable del servidor: las llamadas de autoría auto-guardan, las llamadas de reemplazo y eliminación pueden destruir el estado existente, y todas las operaciones permanecen dentro del almacén de diagramas local configurado. Las anotaciones de MCP son sugerencias informativas, no un límite de autorización; los clientes deben aplicar sus propias políticas de confianza y aprobación.

Herramientas de creación

new_bpmn

Cree un nuevo diagrama de proceso o colaboración BPMN y establézcalo como contexto actual.

{
  name: "Order Processing",
  type: "process" // or "collaboration" (optional, defaults to "process")
}

new_from_mermaid

Crea un nuevo diagrama BPMN a partir de código Mermaid y establécelo como contexto actual.

{
  name: "My Process",
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

La conversión de Mermaid admite intencionadamente un subconjunto de diagramas de flujo:

Cuando hay algún subgrafo, cada nodo debe pertenecer exactamente a un subgrafo de nivel superior. Los subgrafos anidados y las conexiones de flujo de secuencia a nodos de datos se rechazan antes de la exportación a BPMN. El estilo, los manejadores de clic, las clases CSS y la apariencia de bordes punteados no se representan en BPMN; la sintaxis aceptada con pérdida devuelve una advertencia de conversión. Las etiquetas de texto y los nombres de subgrafos se escapan en XML y se conservan sin cambios al pasar por BPMN.

Operaciones de archivo

open_bpmn

Abre un archivo BPMN existente y lo establece como contexto actual.

{
  filename: "my-process.bpmn"
}

open_mermaid_file

Abre y convierte un archivo Mermaid a BPMN, estableciéndolo como contexto actual.

{
  filename: "my-flowchart.mmd"
}

save

Guarda atómicamente el diagrama actual en su archivo activo. Los diagramas nuevos y abiertos ya tienen un nombre de archivo activo, y las mutaciones exitosas se guardan automáticamente en ese mismo archivo.

{}

save_as

Guarda atómicamente el diagrama actual con un nuevo nombre de archivo y hace que ese nombre sea el activo. Las mutaciones posteriores actualizan solo el nuevo archivo; el archivo anterior permanece como una instantánea sin cambios.

{
  filename: "my-process.bpmn"
}

close

Cierra el diagrama actual y limpia el contexto.

{}

current

Obtiene información sobre el diagrama actual.

{}

Herramientas de manipulación de elementos

add_event

Añade eventos (inicio, fin, intermedio, de borde) al diagrama actual.

{
  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
}

Las definiciones de temporizador requieren timer: { type: "timeDate" | "timeDuration" | "timeCycle", expression, language? }; las definiciones condicionales requieren condition: { expression, language? }. Las referencias de error y escalamiento también pueden incluir code. Los lanzamientos de compensación pueden incluir activityRef y waitForCompletion; los eventos de borde de compensación no son interrumpibles.

add_activity

Añade actividades (tareas, subprocesos) al diagrama actual.

{
  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}"
  }
}

Los documentos BPMN nuevos y los creados desde Mermaid aceptan extensionProfile: "portable" | "camunda7"; el valor predeterminado es portable. El modo portátil rechaza los tres campos de proveedor y no emite ningún espacio de nombres de proveedor. Las actualizaciones de Camunda aceptan null para cualquiera de ellos para eliminar el atributo XML correspondiente. Las entradas de grupo candidato no pueden contener comas. El BPMN importado detecta el uso real del espacio de nombres de Camunda y conserva de forma opaca otras extensiones sin advertencias.

Las actividades de llamada se serializan como bpmn:callActivity. Su opcional properties.calledElement es un QName BPMN léxico que identifica el elemento invocable; no es necesario que coincida con un ID de proceso en el diagrama actual.

Las actividades pueden usar características estándar de bucle múltiple de BPMN. Establece isSequential en false para instancias paralelas o true para instancias secuenciales:

{
  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
    }
  }
}

El servidor conserva exactamente los cuerpos de las expresiones y los serializa como valores FormalExpression de BPMN. No los analiza ni los evalúa, así que elige un lenguaje/perfil compatible con el motor BPMN que ejecutará el diagrama exportado. Las referencias de datos del bucle deben identificar instancias ItemAwareElement existentes de BPMN; el esquema portátil no emite un atributo collection específico del proveedor. El dialecto BPMN portátil no emite atributos de enlace o versión específicos del proveedor.

{
  activityType: "callActivity",
  name: "Invoke fulfillment",
  properties: { calledElement: "FulfillmentProcess" }
}

add_gateway

Añade compuertas para lógica de ramificación al diagrama actual.

{
  gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased, complex
  name: "Payment Check",
  position: { x: 400, y: 200 } // optional
}

add_data_object

Añade una bpmn:dataObjectReference visible y su bpmn:dataObject vinculado y no renderizado. El estado de colección pertenece al objeto subyacente. Un itemSubjectRef opcional debe identificar una bpmn:itemDefinition existente, como una cargada desde un diagrama importado.

{
  name: "Order records",
  position: { x: 400, y: 320 }, // optional reference position
  isCollection: true, // optional, defaults to false
  itemSubjectRef: "ItemDefinition_Order" // optional existing definition ID
}

Las asociaciones de entrada/salida de datos son construcciones BPMN propiedad de la actividad y no se crean con add_association, que sigue siendo la asociación de artefactos genérica.

add_text_annotation

Añade una anotación de texto BPMN. El texto se conserva exactamente, incluidos los saltos de línea y los metacaracteres XML. textFormat tiene como valor predeterminado text/plain de BPMN; la posición y el tamaño tienen como valor predeterminado la geometría de anotación del motor. Proporcionar associatedElementId también crea una asociación BPMN separada y no dirigida desde la anotación a ese elemento.

{
  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

Conecta dos elementos con un flujo de secuencia en el diagrama actual.

{
  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
}

Se admiten condiciones y valores predeterminados para actividades y compuertas exclusivas, inclusivas o complejas. Un flujo predeterminado no puede tener también una condición.

add_association

Añade un artefacto de asociación BPMN entre dos BaseElements en un ámbito de proceso o colaboración compatible. Esto es distinto de los flujos de secuencia y mensaje. associationDirection tiene como valor predeterminado el valor None de BPMN.

{
  sourceId: "TextAnnotation_1",
  targetId: "UserTask_1",
  associationDirection: "One" // None, One, or Both
}

add_pool

Añade un pool (participante) a un diagrama de colaboración.

{
  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

Añade un carril a un pool de caja blanca y asigna nodos de flujo de proceso directos a él. Los nodos ya asignados a otro carril se mueven al nuevo carril.

{
  poolId: "Participant_1",
  name: "Sales Department",
  flowNodeIds: ["StartEvent_1", "UserTask_1"],
  position: "bottom" // optional
}

Herramientas de consulta y manipulación

list_elements

Lista una página estable, ordenada por ID, de elementos y artefactos de asociación en el diagrama actual. Filtra con elementType: "bpmn:Association" para listar solo asociaciones.

{
  elementType: "bpmn:Task", // optional filter
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

La respuesta es { count, returnedCount, offset, limit, hasMore, elements }. Nota de compatibilidad: el envoltorio de paginación reemplaza la respuesta anterior de matriz simple; los clientes escritos para ese contrato ahora deben leer elements. Los campos de elementos existentes conservan sus significados; pueden estar presentes campos de metadatos adicionales y entradas de carril.

get_element

Obtiene detalles de un elemento o asociación específicos.

{
  elementId: "UserTask_1"
}

update_element

Actualiza las propiedades del elemento.

{
  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

Elimina un elemento y sus conexiones incidentes. Pasar un ID de asociación elimina solo esa asociación y deja sus extremos intactos; eliminar un extremo, incluida una anotación de texto, se propaga a sus asociaciones.

{
  elementId: "Task_1"
}

Herramientas de utilidad

export

Exporta el diagrama actual como XML BPMN 2.0 o un SVG renderizado.

{
  format: "xml", // "xml" or "svg"; defaults to "xml"
  formatted: true // optional; applies to XML and defaults to true
}

La exportación XML devuelve texto y no abre un navegador. La exportación SVG abre un navegador sin interfaz gráfica a través de Puppeteer, renderiza con bpmn-js, sanea el resultado y devuelve un recurso image/svg+xml incrustado. Requiere un ejecutable de Chrome/Chromium disponible y conserva la atribución visible de bpmn.io descrita en Licencia.

validate

Valida la estructura del diagrama actual.

{
  level: "full" // "syntax", "semantic", or "full"; defaults to "full"
}

Los niveles de validación son acumulativos. syntax analiza XML y resuelve referencias; semantic añade reglas de eventos, flujos, subprocesos, carriles y colaboración conscientes del propietario; full también añade orientación de inicio/fin/conectividad del perfil ejecutable.

auto_layout

Aplica un diseño automático para posicionar elementos en el diagrama actual.

{
  algorithm: "horizontal" // currently only horizontal is supported
}

El diseño se ejecuta en un subproceso que se puede eliminar con un presupuesto predeterminado de cinco segundos. Una verificación previa basada en puntos de referencia acepta como máximo 2,000 elementos, 2,000 conexiones y 10 conexiones por elemento; las entradas que superen cualquier límite se rechazan antes del diseño. Para colaboraciones, cada proceso participante se clasifica de forma independiente, por lo que los flujos de mensaje no cambian su orden de flujo de secuencia. El diseño automático reemplaza las coordenadas manuales de nodos y contenedores, pero las dimensiones de participantes y carriles solicitadas/importadas siguen siendo límites inferiores. Los pools se apilan luego sin superposición; los carriles y los nodos propios permanecen contenidos, y los flujos de mensaje se enrutan solo después de la colocación final del pool. Los nodos desconectados se empaquetan de forma determinista en su proceso propietario, los subprocesos anidados conservan la contención semántica y los participantes de caja negra mantienen su tamaño mínimo solicitado sin contenido de proceso fabricado.

Herramientas de gestión de archivos

list_diagrams

Lista una página estable, ordenada por nombre de archivo, de diagramas BPMN guardados.

{
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

Los campos de respuesta existentes { count, diagrams, path } siguen disponibles; returnedCount, offset, limit y hasMore describen la página seleccionada. Solo se leen los archivos de la página seleccionada para los metadatos BPMN incrustados, y la lectura de metadatos agregada está limitada a 5 MiB de forma predeterminada.

delete_diagram_file

Elimina un archivo de diagrama guardado.

{
  filename: "old-process.bpmn"
}

get_diagrams_path

Obtiene la ruta de almacenamiento de los diagramas.

{}

🔄 Gestión de contexto

El servidor MCP-BPMN utiliza un diseño con estado en el que trabajas con un diagrama a la vez:

1. Crear o abrir: Comienza creando un nuevo diagrama (new_bpmn, new_from_mermaid) o abriendo uno existente (open_bpmn, open_mermaid_file)

2. Manipular: Todas las operaciones (add_event, connect, etc.) se aplican al diagrama actual

3. Guardar: Guarda tu trabajo con save o save_as

4. Cerrar: Cierra el diagrama actual con close

Si intentas realizar operaciones sin un contexto actual, recibirás un mensaje de error útil:

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

💡 Ejemplos

Ejemplo 1: Crear un proceso de aprobación desde cero

// 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();

Ejemplo 2: Iniciar desde Mermaid (recomendado para menor uso de tokens)

// 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();

Ejemplo 3: Trabajar con múltiples diagramas

// 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", ... }

🗂️ Almacenamiento de archivos

Los diagramas BPMN se guardan automáticamente en tu sistema de archivos local:

• Unix/Linux/Mac: ~/mcp-bpmn/

• Windows: %USERPROFILE%\mcp-bpmn\

Ruta personalizada mediante variable de entorno:

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

Los límites de recursos se pueden ajustar con 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 y MCP_BPMN_LAYOUT_TIMEOUT_MS. El plazo de apagado elegante se puede anular con MCP_BPMN_SHUTDOWN_TIMEOUT_MS. Los valores predeterminados son 5 MiB por entrada importada/diseño y por página de metadatos de listado, 2,000 elementos/conexiones de diseño, densidad 10, dos subprocesos de diseño concurrentes, 10,000 candidatos de listado y 5,000 ms. Los valores predeterminados de diseño provienen de puntos de referencia locales dispersos/densos: 2,000/1,999 completados en aproximadamente 1.4s, 25/300 tardaron aproximadamente 4.8s y 26/325 superaron los cinco segundos.

Ante SIGINT, SIGTERM o EOF de stdin, el servidor deja de aceptar llamadas a herramientas y permite que las operaciones aceptadas y su persistencia atómica terminen antes de cerrar los subprocesos de renderizado/diseño y el transporte stdio. El apagado elegante tiene un plazo máximo de 15 segundos; superarlo fuerza una salida con código distinto de cero.

Los diagramas nuevos comienzan con el nombre de archivo {ProcessId}_{ProcessName}.bpmn. Cada diagrama tiene exactamente un nombre de archivo activo: abrir adopta el nombre de archivo abierto y save_as lo cambia después de que el nuevo archivo se escriba correctamente. Las operaciones de agregar, actualizar, eliminar, conectar y diseñar serializan y guardan automáticamente de forma atómica el archivo activo; una serialización o escritura fallida deja tanto la memoria como el disco en el último estado exitoso.

🏗️ Arquitectura

Stack Tecnológico

• TypeScript - Desarrollo con seguridad de tipos

• Node.js - Entorno de ejecución

• MCP SDK - Implementación del Model Context Protocol

• Jest - Framework de pruebas

Componentes Clave

• SimpleBpmnEngine - Mutación canónica de documentos BPMN, persistencia y exportación XML

• BpmnSvgRenderer - Renderizado SVG aislado de bpmn-js respaldado por navegador

• DiagramContext - Gestión de contexto con estado para el diagrama actual

• BpmnAutoLayoutV2Adapter - Integración de auto-diseño BPMN

• BpmnRequestHandler - Procesamiento de solicitudes MCP

• MermaidConverter - Conversión de Mermaid a BPMN

• TypeMappings - Conversiones de tipos de elementos BPMN

• IdGenerator - Generación de ID consistente

Estructura del Proyecto

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

🧪 Desarrollo

Scripts Disponibles

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

Pruebas

El proyecto incluye una cobertura de pruebas exhaustiva. Los comandos a nivel de fuente no leen dist/, por lo que una compilación antigua no puede afectar su resultado:

• Pruebas Unitarias: Pruebas de funcionalidad central

• Pruebas de Integración: Pruebas de manejadores y herramientas

• Pruebas E2E: Pruebas completas del protocolo MCP

Ejecute las pruebas con:

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

📈 Rendimiento

El artefacto de lanzamiento canónico se midió el 2026-08-22 con Node 25.9.0 y npm 11.12.1 usando:

npm pack --dry-run --json

Ese comando informó aproximadamente 195 kB comprimidos y 1104270 bytes descomprimidos. Estas cifras describen el tarball de npm, no un servidor instalado: el tarball no incluye dependencias de producción, mientras que la instalación resuelve las nueve dependencias directas de tiempo de ejecución en package.json y sus dependencias transitivas. La descarga de Chrome administrada por Puppeteer también está fuera de la medición del tarball. Vuelva a ejecutar el comando para el artefacto actual en lugar de tratar esta instantánea fechada como una garantía de tamaño permanente.

El paquete CommonJS opcional no es el artefacto de lanzamiento y no tiene una afirmación de tamaño. Los límites de entrada de diseño y las observaciones de referencia fechadas utilizadas para elegir sus valores predeterminados se documentan en Almacenamiento de Archivos.

🐛 Limitaciones Conocidas

• La API de autoría es un subconjunto enfocado de BPMN 2.0, no una cobertura completa de BPMN 2.0. Las construcciones importadas no admitidas pueden rechazarse en lugar de editarse sin pérdidas.

• connect no expone la autoría directa de flujos de mensajes. El subconjunto de colaboración de Mermaid puede crear flujos de mensajes entre subgrafos.

• add_lane crea carriles de nivel superior en piscinas de caja blanca; no puede extender una jerarquía de carriles anidados importada.

• El auto-diseño solo admite diseño horizontal. Los algoritmos verticales y radiales no se anuncian.

• La validación proporciona los niveles documentados de sintaxis, semántica y guía completa; no es una certificación BPMN XSD ni una validación contra un motor de despliegue.

• El perfil de autoría de Camunda 7 se limita a assignee, candidateGroups y dueDate en tareas de usuario. No es una cobertura general del modelador de Camunda.

• La exportación SVG requiere Chrome/Chromium a través de Puppeteer y permite solo una renderización concurrente por instancia de servidor. Los flujos de trabajo XML permanecen sin navegador.

• El servidor no ejecuta, simula ni despliega procesos BPMN.

🚧 Hoja de Ruta

El trabajo planificado y las brechas conocidas se rastrean como problemas de Beads en lugar de prometerse como características implementadas en este documento de versión.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haga un fork del repositorio

2. Cree una rama de características (git checkout -b feature/amazing-feature)

3. Ejecute la puerta de calidad completa (npm run check)

4. Confirme sus cambios (git commit -m 'Add amazing feature')

5. Empuje a la rama (git push origin feature/amazing-feature)

6. Abra una Solicitud de Extracción (Pull Request)

Estilo de Código

• TypeScript con modo estricto

• Configuración de ESLint proporcionada

• Jest para pruebas

• Commits convencionales

📝 Licencia

Licencia MIT - consulte el archivo LICENSE para obtener detalles.

La exportación SVG utiliza bpmn-js@17.11.1. Cada SVG exportado incluye un logotipo visible "Powered by bpmn.io" enlazado a https://bpmn.io; los clientes no deben recortar, cubrir ni eliminar esa atribución. Consulte THIRD_PARTY_NOTICES.md para los términos de licencia de la dependencia y ADR 0002 para la decisión de versión.

📞 Soporte

• Problemas: GitHub Issues

• Documentación: Consulte la carpeta /docs para guías detalladas

🙏 Agradecimientos

• Construido sobre la especificación Model Context Protocol

• Inspirado por bpmn-js para los estándares BPMN

• Gracias al equipo de Anthropic por el desarrollo de MCP