mcp protocol bridge for draw.io diagram operations
Implements the Model Context Protocol (MCP) specification to expose Draw.io as a callable tool interface for LLM clients like Claude Desktop and oterm. The server receives structured tool calls from MCP clients, translates them into Draw.io operations via a WebSocket-connected browser extension, and returns structured responses back through the MCP protocol. Uses the @modelcontextprotocol/sdk (v1.10.1) for protocol implementation and event-driven message routing through Node.js EventEmitter.
Unique: Uses event-driven architecture with decoupled message bus (bus_request_stream and bus_reply_stream) to separate MCP protocol handling from WebSocket communication, enabling bidirectional LLM-to-Draw.io integration without direct API access
vs alternatives: First MCP server for Draw.io, enabling native integration with Claude and other MCP clients without requiring custom API wrappers or REST middleware
websocket-based real-time browser extension communication
Operates a uWebSockets.js server on port 3000 that maintains persistent WebSocket connections with the Draw.io MCP Browser Extension, enabling real-time bidirectional message exchange. Commands from MCP clients are queued and sent to the extension, which executes them in the Draw.io DOM context and returns results asynchronously. The event bus (Node.js EventEmitter) decouples incoming MCP requests from outgoing WebSocket messages, allowing multiple concurrent diagram operations.
Unique: Uses uWebSockets.js (high-performance C++ WebSocket library) with event-driven message bus decoupling to handle concurrent MCP requests without blocking browser extension communication, enabling non-blocking async operation queuing
vs alternatives: Faster and more responsive than polling-based approaches; event-driven architecture prevents head-of-line blocking when multiple diagram operations are queued simultaneously
browser extension protocol handshake and connection management
Manages WebSocket connection lifecycle with the Draw.io MCP Browser Extension, including initial handshake, connection validation, and graceful disconnection handling. When the extension connects, the server validates the connection, registers event listeners for incoming messages, and begins routing MCP requests to the extension. On disconnection, the server cleans up event listeners and queues pending operations for retry or failure notification to MCP clients.
Unique: Implements explicit handshake validation with the browser extension to ensure protocol compatibility before routing MCP requests, preventing invalid operations on incompatible extension versions
vs alternatives: Handshake validation catches version mismatches early; cleaner than silent failures when extension protocol changes
tool registry and dynamic tool exposure to mcp clients
Maintains a registry of available tools (add-rectangle, update-cell-properties, delete-cell, etc.) with their schemas, descriptions, and input/output specifications. When an MCP client connects, the server exposes this tool registry through the MCP protocol, allowing clients to discover available operations and their parameters. Tools are dynamically loaded from the tool system and registered with their zod schemas, enabling MCP clients to understand tool capabilities without hardcoding.
Unique: Exposes tool registry through MCP protocol with full schema information, enabling LLM clients to understand tool capabilities and constraints without external documentation
vs alternatives: Dynamic tool discovery is more flexible than hardcoded tool lists; schema exposure enables LLM agents to generate valid tool calls without trial-and-error
diagram element inspection and metadata retrieval
Provides tools to query the current state of a Draw.io diagram without modifying it: get-selected-cell retrieves properties of the currently selected element, get-shape-categories lists available shape libraries, get-shapes-in-category enumerates shapes within a category, and get-shape-by-name finds specific shapes by name. These tools execute read-only queries through the WebSocket connection to the browser extension, which accesses the Draw.io DOM to extract metadata and return structured JSON responses.
Unique: Implements read-only query tools that execute in the Draw.io DOM context through the browser extension, providing direct access to diagram metadata without requiring diagram export or serialization
vs alternatives: Faster than exporting and parsing diagram XML; provides real-time access to current diagram state without round-tripping through file I/O
diagram element creation with schema-validated properties
Provides tools to create diagram elements (rectangles, circles, diamonds, text, connectors) with validated properties using zod schema validation. Tools like add-rectangle, add-circle, add-diamond, add-text, and add-connector accept structured input parameters (position, size, style, label, connections) that are validated against predefined schemas before being sent to the Draw.io extension. The extension executes the creation in the Draw.io DOM and returns the created element's ID and properties.
Unique: Uses zod schema validation to enforce input correctness before WebSocket transmission, preventing invalid diagram operations from reaching the browser extension and reducing round-trip error handling
vs alternatives: Schema validation at the server layer catches errors early and provides clear error messages to LLM clients; faster than trial-and-error approaches where invalid operations are sent to Draw.io and rejected
diagram element modification and property updates
Provides tools to modify existing diagram elements after creation: update-cell-properties changes properties of a selected or specified element (label, style, position, size), delete-cell removes elements from the diagram, and style-cell applies predefined or custom styling. Modifications are sent through the WebSocket connection to the browser extension, which updates the Draw.io DOM and returns confirmation with updated element state. Uses event-driven message routing to queue modifications and handle asynchronous responses.
Unique: Separates element creation from modification into distinct tools, allowing LLM agents to create a diagram structure first, then refine properties in a second pass without re-creating elements
vs alternatives: Enables iterative diagram refinement without full diagram regeneration; more efficient than recreating elements when only properties change
connector and relationship creation with validation
Provides the add-connector tool to create connections between diagram elements with validated source and target element IDs. The tool accepts source element ID, target element ID, and optional label/style properties, validates the IDs exist, and sends the connector creation request through WebSocket to the Draw.io extension. The extension creates the connector in the DOM and returns the connector's ID and properties, enabling programmatic relationship mapping in diagrams.
Unique: Validates element IDs before sending connector creation request, preventing orphaned connectors and ensuring diagram structural integrity at the server layer
vs alternatives: Server-side validation prevents invalid connectors from being created in Draw.io; reduces error handling complexity in LLM agents by failing fast with clear error messages
+4 more capabilities