@vscxml/mcp 0.1.3 → 0.1.5

package/dist/server.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { GeneratorBridge } from './bridges/generator-bridge.js';
 import { SimulatorBridge } from './bridges/simulator-bridge.js';
 import { EditorBridge } from './bridges/editor-bridge.js';
-import { ProcessManager } from './process-manager.js';
+import { readDiscoveryFiles } from './process-manager.js';
 // Semantic color presets for editor_highlight
 const HIGHLIGHT_PRESETS = {
     error: '#ef4444',
@@ -21,17 +21,96 @@ export function createServer(config = {}) {
     const generator = new GeneratorBridge(config.generatorUrl);
     const simulator = new SimulatorBridge(config.simulatorUrl);
     const editor = new EditorBridge(config.editorUrl);
-    const processManager = new ProcessManager();
+    // ═══════════════════════════════════════════════
+    // Availability Guards
+    // ═══════════════════════════════════════════════
+    const GENERATOR_TOOLS = ['scxml_validate', 'scxml_inspect', 'scxml_create', 'scxml_generate', 'scxml_generate_project', 'scxml_list_targets'];
+    const SIMULATOR_TOOLS = ['scxml_sim_start', 'scxml_sim_send', 'scxml_sim_scenario', 'scxml_sim_get_state', 'scxml_sim_reset', 'scxml_sim_set_variable', 'scxml_trace_list', 'scxml_trace_embed', 'scxml_trace_get', 'scxml_trace_play', 'scxml_trace_step', 'scxml_trace_delete'];
+    const EDITOR_TOOLS = ['editor_push_scxml', 'editor_get_scxml', 'editor_highlight', 'editor_add_note', 'editor_remove_notes', 'editor_navigate', 'editor_show_notification', 'editor_save_file', 'editor_load_file', 'editor_screenshot', 'editor_export_svg', 'editor_export_png', 'editor_export_player_html', 'editor_get_selection', 'editor_get_viewport', 'editor_connect_simulator'];
+    function errorResult(obj) {
+        return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+    }
+    async function checkGenerator() {
+        if (await generator.isAvailable())
+            return null;
+        return errorResult({
+            error: 'Generator is not running',
+            url: generator.getUrl(),
+            startHint: 'Start the generator server: vscxml-generator-cli serve --port 48620 --cors',
+            tools: GENERATOR_TOOLS,
+        });
+    }
+    async function checkSimulator() {
+        if (await simulator.isAvailable())
+            return null;
+        return errorResult({
+            error: 'Simulator is not running',
+            url: simulator.getUrl(),
+            startHint: 'Start the simulator or open it from VSCXML-Editor',
+            tools: SIMULATOR_TOOLS,
+        });
+    }
+    async function checkEditor() {
+        if (await editor.isAvailable())
+            return null;
+        return errorResult({
+            error: 'VSCXML-Editor is not running',
+            url: editor.getUrl(),
+            startHint: 'Start the VSCXML-Editor desktop application',
+            tools: EDITOR_TOOLS,
+        });
+    }
+    async function requireSession() {
+        const unavailable = await checkSimulator();
+        if (unavailable)
+            return unavailable;
+        if (!simulator.getSessionId()) {
+            return errorResult({
+                error: 'No active simulation session',
+                action: 'Call scxml_sim_start with your SCXML content first.',
+            });
+        }
+        return null;
+    }
+    function buildSummary(gen, sim, ed) {
+        const up = [gen && 'generator', sim && 'simulator', ed && 'editor'].filter(Boolean);
+        const down = [!gen && 'generator', !sim && 'simulator', !ed && 'editor'].filter(Boolean);
+        const parts = [];
+        if (up.length === 3) {
+            parts.push('All backends connected.');
+        }
+        else {
+            if (up.length > 0)
+                parts.push(`Connected: ${up.join(', ')}.`);
+            if (down.length > 0)
+                parts.push(`Not connected: ${down.join(', ')}.`);
+        }
+        if (!gen)
+            parts.push('Start the generator to use design and code-generation tools.');
+        if (!sim)
+            parts.push('Start the simulator to use simulation and trace tools.');
+        if (!ed)
+            parts.push('Start VSCXML-Editor to use visual editing and export tools.');
+        if (ed && sim)
+            parts.push('Tip: Use editor_connect_simulator to link the editor to the simulator for live state highlights.');
+        return parts.join(' ');
+    }
     // ═══════════════════════════════════════════════
     // Design Tools
     // ═══════════════════════════════════════════════
     server.tool('scxml_validate', 'Validate SCXML against the W3C spec. Returns errors/warnings, state count, transition count, and datamodel type.', { scxml: z.string().describe('SCXML XML content to validate') }, async ({ scxml }) => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const result = await generator.validate(scxml);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     });
     server.tool('scxml_inspect', 'Inspect an SCXML file and return its full structured model: states, transitions, events, guards, actions, data variables, and hierarchy. Use this to reason about a state machine without seeing a diagram.', { scxml: z.string().describe('SCXML XML content to inspect') }, async ({ scxml }) => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const result = await generator.inspect(scxml);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -68,6 +147,9 @@ export function createServer(config = {}) {
             type: z.string().optional(),
         })).optional().default([]).describe('Top-level data variables'),
     }, async ({ name, datamodel, binding, states, transitions, data }) => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const result = await generator.create({
             name, datamodel, binding, states, transitions, data,
         });
@@ -86,6 +168,9 @@ export function createServer(config = {}) {
             plcPlatform: z.string().optional(),
         }).optional().describe('Target-specific options'),
     }, async ({ scxml, target, options }) => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const result = await generator.generateProject(scxml, target, options);
         // Build helpful metadata
         const buildCommands = {
@@ -114,9 +199,9 @@ export function createServer(config = {}) {
     // Simulation Tools
     // ═══════════════════════════════════════════════
     server.tool('scxml_sim_start', 'Load SCXML into the simulator and start a session. Returns the initial active states, variables, and enabled events.', { scxml: z.string().describe('SCXML XML content to simulate') }, async ({ scxml }) => {
-        if (!simulator.isConnected()) {
-            await simulator.connect();
-        }
+        const unavailable = await checkSimulator();
+        if (unavailable)
+            return unavailable;
         await simulator.loadScxml(scxml);
         const state = await simulator.start();
         return {
@@ -127,9 +212,9 @@ export function createServer(config = {}) {
         event: z.string().describe('Event name to send'),
         data: z.unknown().optional().describe('Optional event data'),
     }, async ({ event, data }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const result = await simulator.sendEvent(event, data);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -146,9 +231,9 @@ export function createServer(config = {}) {
         ])).describe('Events to send in sequence'),
         stopOnError: z.boolean().optional().default(true).describe('Stop on first error (default: true)'),
     }, async ({ scxml, events, stopOnError }) => {
-        if (!simulator.isConnected()) {
-            await simulator.connect();
-        }
+        const unavailable = await checkSimulator();
+        if (unavailable)
+            return unavailable;
         // Start fresh session if SCXML provided
         if (scxml) {
             await simulator.loadScxml(scxml);
@@ -193,19 +278,81 @@ export function createServer(config = {}) {
                 }],
         };
     });
-    server.tool('scxml_sim_get_state', 'Get the current simulation state without sending an event. Returns active states, variables, enabled events, execution mode, and full trace history.', {}, async () => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
+    server.tool('scxml_sim_timed_scenario', 'Run events with real-time delays between them. Unlike scxml_sim_scenario (instant), this lets delayed sends (<send delay="500ms"/>) fire between events — perfect for demonstrating real-time behavior in the editor. Each event has a delay in ms before it is sent.', {
+        scxml: z.string().optional().describe('SCXML content (creates fresh session). Omit to use existing session.'),
+        events: z.array(z.object({
+            name: z.string().describe('Event name'),
+            delay: z.number().optional().default(0).describe('Delay in ms before sending this event (0 = immediate)'),
+            data: z.unknown().optional().describe('Optional event data'),
+        })).describe('Events with timing'),
+    }, async ({ scxml, events }) => {
+        const unavailable = await checkSimulator();
+        if (unavailable)
+            return unavailable;
+        // Start fresh session if SCXML provided
+        if (scxml) {
+            await simulator.loadScxml(scxml);
+            await simulator.start();
+        }
+        const perEvent = [];
+        for (const evt of events) {
+            // Wait the specified delay (real-time — delayed sends will fire)
+            if (evt.delay && evt.delay > 0) {
+                await new Promise(resolve => setTimeout(resolve, evt.delay));
+            }
+            try {
+                const result = await simulator.sendEvent(evt.name, evt.data);
+                perEvent.push({
+                    event: evt.name,
+                    delay: evt.delay || 0,
+                    activeStates: result.state.activeStates,
+                    variables: result.state.variables,
+                });
+                if (result.state.finished)
+                    break;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                perEvent.push({
+                    event: evt.name,
+                    delay: evt.delay || 0,
+                    activeStates: [],
+                    variables: {},
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ perEvent, error: msg }, null, 2),
+                        }],
+                };
+            }
         }
+        const finalState = await simulator.getState();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        perEvent,
+                        finalActiveStates: finalState.activeStates,
+                        finalVariables: finalState.variables,
+                        finished: finalState.finished,
+                    }, null, 2),
+                }],
+        };
+    });
+    server.tool('scxml_sim_get_state', 'Get the current simulation state without sending an event. Returns active states, variables, enabled events, execution mode, and full trace history.', {}, async () => {
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const state = await simulator.getState();
         return {
             content: [{ type: 'text', text: JSON.stringify(state, null, 2) }],
         };
     });
     server.tool('scxml_sim_reset', 'Reset the simulation session to its initial state.', {}, async () => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const state = await simulator.reset();
         return {
             content: [{ type: 'text', text: JSON.stringify(state, null, 2) }],
@@ -228,12 +375,18 @@ export function createServer(config = {}) {
             eventQueueDepth: z.number().optional(),
         }).optional().describe('Target-specific generation options'),
     }, async ({ scxml, target, options }) => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const result = await generator.generate(scxml, target, options);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     });
     server.tool('scxml_list_targets', 'List available code generation targets and their options.', {}, async () => {
+        const unavailable = await checkGenerator();
+        if (unavailable)
+            return unavailable;
         const targets = await generator.listTargets();
         return {
             content: [{ type: 'text', text: JSON.stringify({ targets }, null, 2) }],
@@ -256,9 +409,9 @@ export function createServer(config = {}) {
     // Trace Management Tools
     // ═══════════════════════════════════════════════
     server.tool('scxml_trace_list', 'List all embedded traces in the current SCXML document. Requires an active simulation session.', {}, async () => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const traces = await simulator.listTraces();
         return {
             content: [{ type: 'text', text: JSON.stringify({ traces }, null, 2) }],
@@ -269,9 +422,9 @@ export function createServer(config = {}) {
         description: z.string().optional().describe('Human-readable description of this trace'),
         content: z.string().optional().describe('Raw JSONL trace content to embed. If omitted, the current session execution history is used.'),
     }, async ({ name, description, content }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const result = await simulator.saveTrace(name, { description, content });
         return {
             content: [{
@@ -286,9 +439,9 @@ export function createServer(config = {}) {
     server.tool('scxml_trace_delete', 'Delete an embedded trace from the SCXML document by name.', {
         name: z.string().describe('Trace name to delete'),
     }, async ({ name }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         await simulator.deleteTrace(name);
         return {
             content: [{ type: 'text', text: JSON.stringify({ deleted: name }, null, 2) }],
@@ -297,9 +450,9 @@ export function createServer(config = {}) {
     server.tool('scxml_trace_get', 'Get an embedded trace by name. Returns the parsed trace entries for inspection, comparison, or export.', {
         name: z.string().describe('Trace name to retrieve'),
     }, async ({ name }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const result = await simulator.loadTrace(name);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -312,9 +465,9 @@ export function createServer(config = {}) {
         name: z.string().describe('Embedded trace name to play'),
         speed: z.number().optional().describe('Playback speed multiplier (1.0 = real-time, 2.0 = 2x speed). Default: 1.0'),
     }, async ({ name, speed }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const result = await simulator.playTrace(name, speed);
         return {
             content: [{
@@ -330,9 +483,9 @@ export function createServer(config = {}) {
     server.tool('scxml_trace_step', 'Step forward or backward through a loaded trace. Returns the current position and trace entry.', {
         delta: z.number().describe('Steps to move: positive = forward, negative = backward'),
     }, async ({ delta }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         const result = await simulator.stepTrace(delta);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -342,9 +495,9 @@ export function createServer(config = {}) {
         name: z.string().describe('Variable name'),
         value: z.unknown().describe('New value for the variable'),
     }, async ({ name, value }) => {
-        if (!simulator.isConnected()) {
-            throw new Error('No active simulation session. Use scxml_sim_start first.');
-        }
+        const unavailable = await requireSession();
+        if (unavailable)
+            return unavailable;
         await simulator.setVariable(name, value);
         return {
             content: [{ type: 'text', text: JSON.stringify({ set: name, value }, null, 2) }],
@@ -354,32 +507,18 @@ export function createServer(config = {}) {
     // Editor Interaction Tools
     // ═══════════════════════════════════════════════
     server.tool('editor_push_scxml', 'Push SCXML content to the VSCXML-Generator editor for the user to see and edit. The editor will update its SCXML input pane.', { scxml: z.string().describe('SCXML XML content to push to the editor') }, async ({ scxml }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected. Is VSCXML-Generator running?' }) }],
-                };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.pushScxml(scxml);
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
         };
     });
     server.tool('editor_get_scxml', 'Get the current SCXML content from the VSCXML-Generator editor (what the user is currently editing).', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected. Is VSCXML-Generator running?' }) }],
-                };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.getScxml();
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
@@ -390,16 +529,9 @@ export function createServer(config = {}) {
         severity: z.enum(['info', 'warning', 'error', 'success']).optional().default('info'),
         duration: z.number().optional().default(5000).describe('Duration in ms (0 = persistent)'),
     }, async ({ message, severity, duration }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }],
-                };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         await editor.showNotification(message, severity, duration);
         return {
             content: [{ type: 'text', text: JSON.stringify({ success: true }) }],
@@ -411,14 +543,9 @@ export function createServer(config = {}) {
         duration: z.number().optional().describe('Duration in ms (0 = persistent until cleared)'),
         clear: z.boolean().optional().describe('Clear existing highlights first'),
     }, async ({ states, color, duration, clear }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const resolvedColor = color ? (HIGHLIGHT_PRESETS[color.toLowerCase()] || color) : undefined;
         await editor.highlight(states, { color: resolvedColor, duration, clear });
         return { content: [{ type: 'text', text: JSON.stringify({ success: true }) }] };
@@ -429,28 +556,18 @@ export function createServer(config = {}) {
         color: z.string().optional().describe('Note background color (default: light blue)'),
         visibleWhen: z.array(z.string()).optional().describe('Only show when these state IDs are active'),
     }, async ({ content, attachedTo, color, visibleWhen }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.addNote(content, { attachedTo, color, visibleWhen });
         return { content: [{ type: 'text', text: JSON.stringify({ success: true, noteId: result.noteId }) }] };
     });
     server.tool('editor_remove_notes', 'Remove notes previously added by MCP from the editor canvas. Call with no noteIds to remove all MCP-added notes.', {
         noteIds: z.array(z.string()).optional().describe('Specific note IDs to remove (omit to remove all MCP notes)'),
     }, async ({ noteIds }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         await editor.removeNotes(noteIds);
         return { content: [{ type: 'text', text: JSON.stringify({ success: true }) }] };
     });
@@ -460,14 +577,9 @@ export function createServer(config = {}) {
         fitAll: z.boolean().optional().describe('Fit entire diagram in view'),
         zoom: z.number().optional().describe('Zoom level (default: 1.0)'),
     }, async ({ target, fitStates, fitAll, zoom }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         await editor.navigate({ target, fitStates, fitAll, zoom });
         return { content: [{ type: 'text', text: JSON.stringify({ success: true }) }] };
     });
@@ -475,14 +587,9 @@ export function createServer(config = {}) {
         filePath: z.string().describe('Absolute file path to save to'),
         content: z.string().optional().describe('SCXML content to save. If omitted, fetches current content from the editor.'),
     }, async ({ filePath, content }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         // If no content provided, get it from the editor
         let scxmlContent = content;
         if (!scxmlContent) {
@@ -495,14 +602,9 @@ export function createServer(config = {}) {
     server.tool('editor_load_file', 'Load an SCXML file from disk into the editor. The editor will display the loaded content.', {
         filePath: z.string().describe('Absolute file path to load'),
     }, async ({ filePath }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.loadFile(filePath);
         return {
             content: [{
@@ -516,14 +618,9 @@ export function createServer(config = {}) {
         };
     });
     server.tool('editor_screenshot', 'Capture a screenshot of the VSCXML-Generator editor window. Returns a base64-encoded PNG image.', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.screenshot();
         return {
             content: [{
@@ -536,26 +633,16 @@ export function createServer(config = {}) {
     server.tool('editor_connect_simulator', 'Connect the editor to the simulator backend so it shows live state highlights during MCP-driven simulation.', {
         port: z.number().optional().describe('Simulator WebSocket port (default: 48621)'),
     }, async ({ port }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.connectSimulator(port);
         return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     });
     server.tool('editor_get_selection', 'Get the current selection state in the editor — selected states, transitions, and MCP highlights (with colors). Also includes the latest buffered selection event from user clicks.', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.getSelection();
         const buffered = editor.getLastSelection();
         return {
@@ -566,14 +653,9 @@ export function createServer(config = {}) {
         };
     });
     server.tool('editor_get_viewport', 'Get the editor viewport: visible area, zoom level, pan offset. Also returns the latest buffered selection and document change events.', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const viewport = await editor.getViewport();
         return {
             content: [{
@@ -587,29 +669,79 @@ export function createServer(config = {}) {
         };
     });
     // ═══════════════════════════════════════════════
+    // Editor Layout & Editing Tools
+    // ═══════════════════════════════════════════════
+    server.tool('editor_auto_layout', 'Trigger automatic layout of the diagram in the editor. Rearranges states for clean visual presentation.', {
+        algorithm: z.enum(['hierarchical', 'grid']).optional().describe('Layout algorithm (default: hierarchical)'),
+        selectedOnly: z.boolean().optional().describe('Only layout selected states (default: false)'),
+    }, async ({ algorithm, selectedOnly }) => {
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
+        const result = await editor.autoLayout({ algorithm, selectedOnly });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('editor_add_state', 'Add a new state to the diagram at the given canvas coordinates.', {
+        x: z.number().describe('X position on canvas'),
+        y: z.number().describe('Y position on canvas'),
+        stateType: z.enum(['simple', 'compound', 'parallel', 'initial', 'final', 'history', 'history-deep']).optional().default('simple').describe('State type'),
+    }, async ({ x, y, stateType }) => {
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
+        const result = await editor.addState(x, y, stateType);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('editor_add_transition', 'Add a transition between two states in the editor.', {
+        source: z.string().describe('Source state ID'),
+        target: z.string().describe('Target state ID'),
+    }, async ({ source, target }) => {
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
+        const result = await editor.addTransition(source, target);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('editor_set_property', 'Set properties on a state or transition. For states: label, color, x, y, width, height, onentry, onexit. For transitions: event, cond, actions, type.', {
+        elementId: z.string().describe('State or transition ID'),
+        elementType: z.enum(['state', 'transition']).describe('Element type'),
+        properties: z.record(z.unknown()).describe('Properties to set (e.g. { "label": "Idle", "color": "#3b82f6" })'),
+    }, async ({ elementId, elementType, properties }) => {
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
+        const result = await editor.setProperty(elementId, elementType, properties);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('editor_add_image', 'Add an image to the editor canvas. Use for explanatory diagrams, icons, or annotations. The image data must be base64-encoded.', {
+        data: z.string().describe('Base64-encoded image data (no data: prefix)'),
+        mimeType: z.string().optional().default('image/png').describe('MIME type (image/png, image/jpeg, image/svg+xml)'),
+        x: z.number().optional().describe('X position on canvas'),
+        y: z.number().optional().describe('Y position on canvas'),
+        width: z.number().optional().describe('Display width (auto-scaled if omitted)'),
+        height: z.number().optional().describe('Display height (auto-scaled if omitted)'),
+        attachedTo: z.string().optional().describe('State ID to attach the image to'),
+    }, async ({ data, mimeType, x, y, width, height, attachedTo }) => {
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
+        const result = await editor.addImage(data, { mimeType, x, y, width, height, attachedTo });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    // ═══════════════════════════════════════════════
     // Export Tools
     // ═══════════════════════════════════════════════
     server.tool('editor_export_svg', 'Export the current diagram from the editor as a complete SVG. Returns parseable text the agent can read directly — contains state IDs, labels, positions, transitions, colors.', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.exportSvg();
         return { content: [{ type: 'text', text: result.svg }] };
     });
     server.tool('editor_export_png', 'Export the current diagram from the editor as a full PNG image at 2x resolution. Unlike editor_screenshot (viewport only), this renders the entire diagram.', {}, async () => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.exportPng();
         return {
             content: [{ type: 'image', data: result.data, mimeType: 'image/png' }],
@@ -621,14 +753,9 @@ export function createServer(config = {}) {
         selectedTraceIds: z.array(z.string()).optional()
             .describe('Trace IDs to include when exportMode is "traces" or "both"'),
     }, async ({ exportMode, selectedTraceIds }) => {
-        if (!editor.isConnected()) {
-            try {
-                await editor.connect();
-            }
-            catch {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Editor not connected' }) }] };
-            }
-        }
+        const unavailable = await checkEditor();
+        if (unavailable)
+            return unavailable;
         const result = await editor.exportPlayerHtml({ exportMode, selectedTraceIds });
         return { content: [{ type: 'text', text: result.html }] };
     });
@@ -641,21 +768,46 @@ export function createServer(config = {}) {
     // ═══════════════════════════════════════════════
     // Connection Status Tool
     // ═══════════════════════════════════════════════
-    server.tool('scxml_status', 'Check the connection status of VSCXML backends (generator, simulator, editor).', {}, async () => {
-        const [genAvail, simAvail, editorStatus] = await Promise.all([
+    server.tool('scxml_status', 'Check the connection status of VSCXML backends (generator, simulator, editor). Reports URLs, available tool groups, and how to start missing backends. Call this first to know which tools are available.', {}, async () => {
+        const [genAvail, simAvail, editorAvail] = await Promise.all([
             generator.isAvailable(),
             simulator.isAvailable(),
-            editor.getStatus(),
+            editor.isAvailable(),
         ]);
+        const editorStatus = editorAvail
+            ? await editor.getStatus()
+            : { connected: false, hasDocument: false, documentName: null };
+        // Scan discovery files for all known instances
+        const allGenerators = readDiscoveryFiles('generator');
+        const allSimulators = readDiscoveryFiles('simulator');
+        const allEditors = readDiscoveryFiles('editor');
+        const result = {
+            generator: {
+                connected: genAvail,
+                url: generator.getUrl(),
+                tools: GENERATOR_TOOLS,
+                instances: allGenerators,
+                startHint: genAvail ? undefined : 'Run: vscxml-generator-cli serve --port 48620 --cors',
+            },
+            simulator: {
+                connected: simAvail,
+                url: simulator.getUrl(),
+                sessionId: simulator.getSessionId(),
+                tools: SIMULATOR_TOOLS,
+                instances: allSimulators,
+                startHint: simAvail ? undefined : 'Start the simulator or open it from VSCXML-Editor',
+            },
+            editor: {
+                ...editorStatus,
+                url: editor.getUrl(),
+                tools: EDITOR_TOOLS,
+                instances: allEditors,
+                startHint: editorStatus.connected ? undefined : 'Start the VSCXML-Editor desktop application',
+            },
+            summary: buildSummary(genAvail, simAvail, editorStatus.connected),
+        };
         return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({
-                        generator: { connected: genAvail },
-                        simulator: { connected: simAvail, sessionId: simulator.getSessionId() },
-                        editor: editorStatus,
-                    }, null, 2),
-                }],
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     });
     return server;