MCP-BPMN Server

# Clone the repository
git clone https://github.com/your-org/mcp-bpmn.git
cd mcp-bpmn

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (optional)
npm test

{
  "mcpServers": {
    "mcp-bpmn": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
    }
  }
}

node dist/server/bundle.cjs

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

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

{
  filename: "my-process.bpmn"
}

{
  filename: "my-flowchart.mmd"
}

{}

{
  filename: "my-process.bpmn"
}

{}

{}

{
  eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
  name: "Order Received",
  eventDefinition: "message", // optional: message, timer, error, signal, etc.
  position: { x: 100, y: 200 } // optional
}

{
  activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
  name: "Review Order",
  position: { x: 250, y: 200 }, // optional
  properties: { assignee: "reviewer" } // optional
}

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

{
  sourceId: "StartEvent_1",
  targetId: "UserTask_1",
  label: "Start Flow", // optional
  condition: "amount > 1000" // optional, for conditional flows
}

{
  name: "Customer",
  position: { x: 100, y: 100 }, // optional
  size: { width: 600, height: 250 } // optional
}

{
  poolId: "Participant_1",
  name: "Sales Department",
  position: "bottom" // optional
}

{
  elementType: "bpmn:Task" // optional filter
}

{
  elementId: "UserTask_1"
}

{
  elementId: "UserTask_1",
  name: "Updated Task Name",
  properties: { assignee: "john.doe" }
}

{
  elementId: "Task_1"
}

{
  format: "xml", // only xml is currently supported
  formatted: true // optional, defaults to true
}

{}

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

{}

{
  filename: "old-process.bpmn"
}

{}

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

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

// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({ 
  name: "Approval Workflow",
  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();

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

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

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 test            # Run all tests
npm run test:unit   # Run unit 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

npm test                    # All tests
npm run test:coverage       # With coverage report
npm run test:watch         # Watch mode