@vscxml/mcp

MCP server for the VSCXML suite. Enables LLMs (Claude Code, Claude Desktop, Cursor, etc.) to design, simulate, generate, and visually edit SCXML state machines.

Architecture

LLM (Claude Code / Claude Desktop / Cursor)
        |
        | MCP Protocol (stdio)
        v
+-----------------------------------------------+
|  @vscxml/mcp                                 |
|                                                |
|  SimulatorBridge ----WS:48621----> Simulator   |
|  GeneratorBridge ---HTTP:48620---> Generator    |
|  EditorBridge ------WS:48623----> Editor       |
+-----------------------------------------------+

The MCP server is a thin client that bridges three VSCXML backends:

• VSCXML-Generator-CLI (REST API) -- code generation, validation, inspection
• VSCXML-Simulator (WebSocket) -- real-time simulation with trace visibility
• VSCXML-Editor (WebSocket) -- visual editor interaction

Setup

Claude Code (one-line)

# macOS / Linux — project-level (current project only):
claude mcp add vscxml -- npx -y @vscxml/mcp

# macOS / Linux — user-level (all projects):
claude mcp add -s user vscxml -- npx -y @vscxml/mcp

# Windows — requires cmd /c wrapper:
claude mcp add vscxml -- cmd /c npx -y @vscxml/mcp

# Windows — user-level:
claude mcp add -s user vscxml -- cmd /c npx -y @vscxml/mcp

Restart Claude Code after adding. The 52 tools will appear in the tool list.

Claude Desktop

In Settings > Developer > MCP Servers:

macOS / Linux:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "vscxml": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@vscxml/mcp"]
    }
  }
}

Custom backend URLs

# macOS / Linux:
claude mcp add vscxml -- npx -y @vscxml/mcp --generator http://localhost:48620 --simulator ws://localhost:48621 --editor ws://localhost:48623

# Windows:
claude mcp add vscxml -- cmd /c npx -y @vscxml/mcp --generator http://localhost:48620 --simulator ws://localhost:48621 --editor ws://localhost:48623

Or via environment variables: VSCXML_GENERATOR_URL, VSCXML_SIMULATOR_URL, VSCXML_EDITOR_URL.

Full setup guide with usage examples: vscxml.com/docs/mcp-setup.html

Prerequisites

The MCP server requires installed VSCXML backends to function:

| Backend | Purpose | Default Port | |---------|---------|-------------| | VSCXML-Generator-CLI | Code generation, validation, inspection, SCXML creation | 48620 (HTTP) | | VSCXML-Simulator | Real-time simulation, trace capture | 48621 (WS), 48622 (REST) | | VSCXML-Editor | Visual state machine editing | 48623 (WS) |

The MCP server auto-discovers backends on default ports. If not found, it attempts to spawn them from known install paths.

Tools (52)

Design (3)

| Tool | Description | |------|-------------| | scxml_create | Create SCXML from a structured specification (states, transitions, data). No raw XML needed. | | scxml_validate | Validate SCXML against the W3C spec. Returns errors, state/transition counts, datamodel. | | scxml_inspect | Get the full structured model: states, hierarchy, transitions, events, variables, actions. |

Simulation (7)

| Tool | Description | |------|-------------| | scxml_sim_start | Load SCXML into the simulator and start. Returns initial state + enabled events. | | scxml_sim_send | Send an event. Returns the trace (state exits/entries, transitions, variable changes) + new state. | | scxml_sim_scenario | Run a batch of events. The most useful tool for testing behavior. | | scxml_sim_timed_scenario | Run a timed scenario with delays between events. Required for machines using <send delay="..."/>. | | scxml_sim_get_state | Get current state without sending an event. | | scxml_sim_set_variable | Set a variable value during simulation. | | scxml_sim_reset | Reset the simulation to its initial state. |

Trace Management (6)

| Tool | Description | |------|-------------| | scxml_trace_embed | Embed a trace into the SCXML document (from session history or raw JSONL content). | | scxml_trace_list | List all embedded traces in the current SCXML document. | | scxml_trace_get | Get a trace by name. Returns parsed entries for inspection or comparison. | | scxml_trace_play | Start real-time playback of an embedded trace. | | scxml_trace_step | Step forward/backward through a loaded trace. | | scxml_trace_delete | Delete an embedded trace by name. |

Code Generation (3)

| Tool | Description | |------|-------------| | scxml_generate | Generate code for any of 9 targets (Java, JS, C#, C, C++, Python, Go, Rust, ST). Returns source files as text. | | scxml_generate_project | Generate a complete runnable project with build files, runtime, and scaffolding. | | scxml_list_targets | List available targets and their options. |

Verification (1)

| Tool | Description | |------|-------------| | scxml_compare_traces | Compare two execution traces and report differences. |

Editor Interaction (8)

| Tool | Description | |------|-------------| | editor_push_scxml | Push SCXML to the visual editor for the user to see. | | editor_get_scxml | Get the current SCXML from the editor (what the user is editing). | | editor_highlight | Highlight states with color: hex (#ef4444) or preset (error, success, warning, info, active, danger). | | editor_add_note | Add annotations with attachedTo (state), visibleWhen (conditional visibility), and color. | | editor_remove_notes | Remove MCP-added notes (by ID or all). | | editor_navigate | Navigate the canvas: center on a state, fit states, fit all, zoom. | | editor_show_notification | Show a toast notification in the editor UI. | | editor_status | Check if the editor is running and connected. |

Diagram Editing (11)

| Tool | Description | |------|-------------| | editor_add_state | Add a state to the diagram. Supports parentId (child placement), id, label. Returns stateId. | | editor_add_transition | Add a transition. Supports inline event and cond. Returns transitionId. | | editor_set_property | Set properties on a state or transition (label, color, events, guards, actions). | | editor_remove_element | Remove a state, transition, image, or note. State removal cascades to children and connected transitions; image removal garbage-collects unreferenced data. | | editor_clone_state | Clone/duplicate a state with all children, internal transitions, and actions. | | editor_auto_layout | Trigger automatic layout (hierarchical or grid algorithm). | | editor_add_image | Add an image to the canvas with optional state-dependent visibility. | | editor_set_image_property | Modify image properties (position, visibility, opacity, rotation). | | editor_list_images | List all canvas images with their IDs and metadata (name, position, size, visibility, groupId). | | editor_group_images | Group 2+ images so they select/move/resize together (Affinity-style). Returns the groupId. | | editor_ungroup_images | Ungroup images by IDs or by an entire groupId. |

File I/O (3)

| Tool | Description | |------|-------------| | editor_save_file | Save SCXML to a file path. Auto-fetches content from editor if not provided. | | editor_load_file | Load an SCXML file from disk into the editor. | | editor_screenshot | Capture the editor window as a PNG image. |

Export (3)

| Tool | Description | |------|-------------| | editor_export_svg | Export the full diagram as parseable SVG text (contains state IDs, positions, labels). | | editor_export_png | Export the full diagram as a 2x resolution PNG (entire diagram, not viewport). | | editor_export_player_html | Export a self-contained interactive HTML player with embedded SCXML runtime and trace playback. |

Selection & Awareness (3)

| Tool | Description | |------|-------------| | editor_get_selection | Get selected states, transitions, and MCP highlights with colors. Includes buffered selection events. | | editor_get_viewport | Get visible area, zoom level, pan offset, and buffered selection/document change events. | | editor_connect_simulator | Connect editor to the simulator for live state highlights during simulation. |

Simulator Sync (3)

| Tool | Description | |------|-------------| | editor_disconnect_simulator | Disconnect editor from the simulator backend. | | editor_pull_from_simulator | Pull the simulator's SCXML document (including traces) into the editor. | | editor_push_to_simulator | Push the editor's SCXML to the simulator (overwrites simulator document). |

Status (1)

| Tool | Description | |------|-------------| | scxml_status | Check connectivity of all three backends. |

Skills (Slash Commands)

When used as a Claude Code plugin, the following guided workflows are available:

| Command | Description | |---------|-------------| | /vscxml:design | Create and visualize state machines from descriptions | | /vscxml:simulate | Test with event injection, tracing, live highlights | | /vscxml:generate | Generate code for Java, JS, C#, C, Python, Go, ST | | /vscxml:trace | Record, compare, and replay execution traces |

Example Workflow

User: "Design a vending machine that accepts quarters and dimes, costs $1.25"

Claude (using MCP):
1. scxml_create(...)              -- build the state machine
2. scxml_validate(...)            -- check it's valid
3. editor_push_scxml(...)         -- show it in the visual editor
4. editor_highlight(..., "info")  -- highlight key states in blue
5. scxml_sim_scenario(...)        -- test with: dime, quarter, quarter, quarter, quarter
6. scxml_trace_embed(...)         -- save the execution trace
7. editor_export_svg(...)         -- export diagram for documentation
8. scxml_generate(...)            -- generate Python code
9. editor_save_file(...)          -- save SCXML to disk
10. editor_export_player_html(...) -- create interactive demo for team

Development

cd scxml-mcp
npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm start            # Run MCP server (stdio)

Testing

# Start backends first:
java -jar ../scxml-core/build/libs/scxml-core-*-all.jar serve --port 48620 --cors &
java -jar ../scxml-simulator/build/libs/scxml-simulator-*-all.jar serve --ws-port 48621 --rest-port 48622 --cors &

# Run tests:
python test-e2e.py              # Basic MCP protocol tests (13 tests)
python test-phase2.py           # Editor tools with mock WS (14 tests)
python test-phase4.py           # Collaborative tools with mock WS (11 tests)
python test-integration-all.py  # All 52 tools, real backends + mock editor (77 tests)

# Real integration test (requires real editor running):
# Start editor: cd ../scxml-editor && npm run dev:electron
python test-integration-real.py              # 77 tests, ZERO mocks
python test-integration-real.py --start-editor  # Auto-launches editor + REPL
python test-integration-real.py --quick      # Skip slow generation targets

Default Ports

| Port | Service | Protocol | |------|---------|----------| | 48620 | Generator REST API | HTTP | | 48621 | Simulator WebSocket | WS | | 48622 | Simulator REST API | HTTP | | 48623 | Editor API | WS |

License

MIT