@vscxml/mcp 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# @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
+
+Add to your project's `.claude/settings.json` (or global `~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "scxml-gen": {
+      "command": "node",
+      "args": ["C:/dev/repos/scxml-gen/scxml-mcp/dist/bin/scxml-mcp.js"]
+    }
+  }
+}
+```
+
+Or after npm publish:
+
+```json
+{
+  "mcpServers": {
+    "scxml-gen": {
+      "command": "npx",
+      "args": ["@vscxml/mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to Claude Desktop settings (`Settings > Developer > MCP Servers`):
+
+```json
+{
+  "mcpServers": {
+    "scxml-gen": {
+      "command": "npx",
+      "args": ["@vscxml/mcp"]
+    }
+  }
+}
+```
+
+### Custom backend URLs
+
+```json
+{
+  "mcpServers": {
+    "scxml-gen": {
+      "command": "npx",
+      "args": ["@vscxml/mcp", "--generator", "http://localhost:48620", "--simulator", "ws://localhost:48621", "--editor", "ws://localhost:48623"]
+    }
+  }
+}
+```
+
+Or via environment variables:
+
+```
+VSCXML_GENERATOR_URL=http://localhost:48620
+VSCXML_SIMULATOR_URL=ws://localhost:48621
+VSCXML_EDITOR_URL=ws://localhost:48623
+```
+
+## 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 (37)
+
+### 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 (6)
+
+| 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_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 7 targets (Java, JS, C#, C, Python, Go, 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. |
+
+### 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. |
+
+### Status (1)
+
+| Tool | Description |
+|------|-------------|
+| `scxml_status` | Check connectivity of all three backends. |
+
+## 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
+
+```bash
+cd scxml-mcp
+npm install
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode
+npm start            # Run MCP server (stdio)
+```
+
+### Testing
+
+```bash
+# 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 37 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

package/dist/bin/scxml-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/scxml-mcp.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { startStdio } from '../index.js';
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const config = {};
+for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+        case '--generator':
+            config.generatorUrl = args[++i];
+            break;
+        case '--simulator':
+            config.simulatorUrl = args[++i];
+            break;
+        case '--editor':
+            config.editorUrl = args[++i];
+            break;
+        case '--help':
+            console.error(`
+@vscxml/mcp - MCP server for VSCXML state machine suite
+
+Usage: scxml-mcp [options]
+
+Options:
+  --generator <url>   Generator REST API URL (default: http://localhost:48620)
+  --simulator <url>   Simulator WebSocket URL (default: ws://localhost:48621)
+  --editor <url>      Editor WebSocket URL (default: ws://localhost:48623)
+  --help              Show this help
+
+Environment variables:
+  VSCXML_GENERATOR_URL   Override generator URL
+  VSCXML_SIMULATOR_URL   Override simulator URL
+  VSCXML_EDITOR_URL      Override editor URL
+
+Example Claude Desktop config (settings.json):
+  {
+    "mcpServers": {
+      "scxml-gen": {
+        "command": "npx",
+        "args": ["@vscxml/mcp"]
+      }
+    }
+  }
+`);
+            process.exit(0);
+    }
+}
+startStdio(config).catch((err) => {
+    console.error('Failed to start MCP server:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=scxml-mcp.js.map

package/dist/bin/scxml-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scxml-mcp.js","sourceRoot":"","sources":["../../src/bin/scxml-mcp.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,sBAAsB;AACtB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,MAAM,GAAc,EAAE,CAAC;AAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;IACrC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,KAAK,aAAa;YAChB,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAChC,MAAM;QACR,KAAK,aAAa;YAChB,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAChC,MAAM;QACR,KAAK,UAAU;YACb,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7B,MAAM;QACR,KAAK,QAAQ;YACX,OAAO,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBnB,CAAC,CAAC;YACG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC/B,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bridges/editor-bridge.d.ts

@@ -0,0 +1,135 @@
+/**
+ * WebSocket bridge to the VSCXML-Editor API.
+ * The editor's Electron main process runs a lightweight WS server on port 48623
+ * that relays commands to/from the React renderer via IPC.
+ */
+export declare class EditorBridge {
+    private ws;
+    private url;
+    private connected;
+    private requestId;
+    private pendingRequests;
+    private lastSelection;
+    private lastDocumentChange;
+    constructor(url?: string);
+    setUrl(url: string): void;
+    isConnected(): boolean;
+    /** Connect to the editor WebSocket API */
+    connect(): Promise<void>;
+    /** Disconnect */
+    disconnect(): void;
+    /** Check if editor is reachable */
+    isAvailable(): Promise<boolean>;
+    /** Push SCXML content to the editor */
+    pushScxml(scxml: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get current SCXML from the editor */
+    getScxml(): Promise<{
+        scxml: string;
+        modified: boolean;
+    }>;
+    /** Show a toast notification in the editor */
+    showNotification(message: string, severity?: 'info' | 'warning' | 'error' | 'success', duration?: number): Promise<void>;
+    /** Highlight specific states in the editor */
+    highlight(states: string[], options?: {
+        color?: string;
+        duration?: number;
+        clear?: boolean;
+    }): Promise<void>;
+    /** Add a note to the editor canvas */
+    addNote(content: string, options?: {
+        attachedTo?: string;
+        color?: string;
+        visibleWhen?: string[];
+    }): Promise<{
+        noteId: string;
+    }>;
+    /** Remove notes from the editor */
+    removeNotes(noteIds?: string[]): Promise<void>;
+    /** Navigate the editor canvas */
+    navigate(options: {
+        target?: string;
+        fitStates?: string[];
+        fitAll?: boolean;
+        zoom?: number;
+    }): Promise<void>;
+    /** Save content to a file path */
+    saveFile(filePath: string, content: string): Promise<{
+        success: boolean;
+        filePath: string;
+    }>;
+    /** Load a file from disk into the editor */
+    loadFile(filePath: string): Promise<{
+        content: string;
+        filePath: string;
+    }>;
+    /** Get the current file path from the editor */
+    getFilePath(): Promise<{
+        filePath: string | null;
+    }>;
+    /** Capture a screenshot of the editor window */
+    screenshot(): Promise<{
+        data: string;
+        format: string;
+        width: number;
+        height: number;
+    }>;
+    /** Connect the editor's simulator panel to the simulator backend */
+    connectSimulator(port?: number): Promise<{
+        success: boolean;
+    }>;
+    /** Get the current selection in the editor */
+    getSelection(): Promise<{
+        highlightedStates: string[];
+        cursorPosition: {
+            line: number;
+            column: number;
+        } | null;
+    }>;
+    /** Get the editor viewport state */
+    getViewport(): Promise<{
+        transform: {
+            x: number;
+            y: number;
+            scale: number;
+        };
+        viewportWidth: number;
+        viewportHeight: number;
+        visibleArea: {
+            left: number;
+            top: number;
+            right: number;
+            bottom: number;
+        };
+    }>;
+    /** Export the full diagram as SVG text */
+    exportSvg(): Promise<{
+        svg: string;
+    }>;
+    /** Export the full diagram as PNG (base64) */
+    exportPng(): Promise<{
+        data: string;
+        width: number;
+        height: number;
+    }>;
+    /** Export interactive Player HTML */
+    exportPlayerHtml(options?: {
+        exportMode?: string;
+        selectedTraceIds?: string[];
+    }): Promise<{
+        html: string;
+    }>;
+    /** Get editor status */
+    getStatus(): Promise<{
+        connected: boolean;
+        hasDocument: boolean;
+        documentName: string | null;
+    }>;
+    private handleMessage;
+    /** Get the latest buffered selection event */
+    getLastSelection(): typeof this.lastSelection;
+    /** Get the latest buffered document change event */
+    getLastDocumentChange(): typeof this.lastDocumentChange;
+    private sendRequest;
+}