@miadi/stateloom-mcp 0.1.4 → 0.2.1

package/README.md

@@ -16,7 +16,7 @@ npx -y @miadi/stateloom-mcp
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server over stdio that gives an agent fifteen tools for building a state machine: create it, add states and events and transitions, validate it, generate code or a RISE rispec from it, and draw it. Every mutation persists to a `.smdf.json` file on disk and — when a bridge URL is configured — emits to the live hub, so a human watching the web canvas or a terminal running `smcx watch` sees each edit as the agent makes it.
 
-It is not the state machine engine (`smcraft` runs the machines) and not the hub (`@miadi/stateloom` sequences the live document). This is the agent-facing surface, sitting beside the human-facing ones on the same file.
+It is not the state machine engine (`@miadi/stateloom-engine` runs the machines) and not the hub (`@miadi/stateloom` sequences the live document). This is the agent-facing surface, sitting beside the human-facing ones on the same file.
 
 ## Configure your MCP client
 
@@ -44,6 +44,61 @@ It is not the state machine engine (`smcraft` runs the machines) and not the hub
 
 The legacy `SMCRAFT_*` twin of each name is still honored. The package ships two bins — `stateloom-mcp` and, for existing registrations, `smcraft-mcp`.
 
+## Remote access (optional, 0.2.0+)
+
+By default this server speaks **stdio** and runs as a child process beside one agent,
+with that agent's trust. Setting a port switches it to Streamable HTTP so agents on
+other machines can reach the same loom. Nothing changes unless you set the port.
+
+```bash
+STATELOOM_MCP_HTTP_PORT=4790 \
+STATELOOM_MCP_TOKEN="$(openssl rand -hex 32)" \
+STATELOOM_MCP_ROOT=/srv/machines \
+  npx -y @miadi/stateloom-mcp
+# → stateloom-mcp on http://127.0.0.1:4790/mcp
+```
+
+| Environment variable | Default | Meaning |
+|---|---|---|
+| `STATELOOM_MCP_HTTP_PORT` | — | Bind this port and speak HTTP. **Unset means stdio**, unchanged. |
+| `STATELOOM_MCP_HTTP_HOST` | `127.0.0.1` | Interface. Loopback by default — put a TLS terminator in front before widening it. |
+| `STATELOOM_MCP_TOKEN` | — | **Required in HTTP mode.** `Authorization: Bearer <token>`, compared in constant time. |
+| `STATELOOM_MCP_ROOT` | — | Confine the active document to this directory; `set_project_file` refuses to leave it. |
+| `STATELOOM_MCP_LOCK_PROJECT` | — | `1`/`true` refuses `set_project_file` outright. |
+
+Endpoints: `POST /mcp` (the MCP endpoint) and `GET /health`.
+
+The server **refuses to start** in HTTP mode without a token. A reachable port here is a
+way to read and write files on the host, and a default-open one would be a mistake someone
+else pays for.
+
+### What remote mode is not
+
+**It is not multi-tenant.** The active document is process state, so every HTTP client
+shares one board. That is the loom's whole premise when a human and an agent work together,
+and a hazard between strangers — one caller's `set_project_file` moves the document for
+everyone. `STATELOOM_MCP_ROOT` bounds where it can move; `STATELOOM_MCP_LOCK_PROJECT` stops
+it moving at all. Run one server per document, or per team, rather than one for everybody.
+
+Each request gets its own server instance and transport (stateless Streamable HTTP), so
+clients may connect, disconnect and reconnect freely.
+
+**It does not serve concurrent clients fairly.** `generate_code` shells out to `smcg` and
+`render_diagram` shells out to a rasterizer, both synchronously — they block the event loop
+for as long as the subprocess runs. On stdio that is invisible, because there is one caller
+and it is waiting anyway. Over HTTP, one agent's slow codegen stalls every other request,
+and a subprocess outlasting Node's 5-second keep-alive timeout makes those requests fail
+outright rather than merely arrive late. Until those calls are made asynchronous, treat a
+remote server as serving one working agent at a time, not a pool.
+
+**What is confined and what is not.** With `STATELOOM_MCP_ROOT` set, both caller-supplied
+paths — `set_project_file`'s `path` and `render_diagram`'s `path` — are resolved through
+`realpath` and refused if they land outside the root, so a symlink inside the root cannot
+walk out of it. The server also refuses to start if `STATELOOM_PROJECT_FILE` is itself
+outside the root. `generate_code` writes only to a temporary directory. Note that
+`STATELOOM_MCP_ROOT` is read the same way every other setting is, so it constrains
+`set_project_file` on stdio too if you set it there.
+
 ## Tools
 
 | Tool | What it does |
@@ -78,7 +133,7 @@ Because rooms are keyed by the document's absolute path, `set_project_file` is h
 
 | Package | Role |
 |---|---|
-| [`smcraft`](https://www.npmjs.com/package/smcraft) | State machine engine: parser, validator, interpreter, code generators |
+| [`@miadi/stateloom-engine`](https://www.npmjs.com/package/@miadi/stateloom-engine) | State machine engine: parser, validator, interpreter, code generators |
 | [`@miadi/stateloom-protocol`](https://www.npmjs.com/package/@miadi/stateloom-protocol) | Patch ops, diff/apply, layout, renderers — zero runtime deps |
 | [`@miadi/stateloom`](https://www.npmjs.com/package/@miadi/stateloom) | socket.io hub holding the live document |
 | [`@miadi/stateloom-client`](https://www.npmjs.com/package/@miadi/stateloom-client) | Framework-agnostic client for the hub |

package/dist/server.js

@@ -29,10 +29,13 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer as createHttpServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
 import { z } from "zod";
 import { execFileSync, spawn } from "child_process";
-import { writeFileSync, readFileSync, mkdtempSync, rmSync, existsSync, statSync } from "fs";
-import { join, resolve } from "path";
+import { writeFileSync, readFileSync, mkdtempSync, rmSync, existsSync, statSync, realpathSync, } from "fs";
+import { basename, dirname, join, resolve } from "path";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
 import { envAlias } from "@miadi/stateloom-protocol";
@@ -44,6 +47,11 @@ import { resolveProjectSwitch } from "./projectSwitch.js";
 const BRIDGE_URL = envAlias("BRIDGE_URL");
 const AGENT_NAME = envAlias("AGENT_NAME");
 const BRIDGE_TOKEN = envAlias("BRIDGE_TOKEN");
+// The canvas address for a document (chart_1785683055671): when the agent
+// re-points the loom, the human gets a link to LOOK at the same document —
+// the `?doc=` parameter is resolved and allowlist-guarded by the web side.
+const CANVAS_URL = envAlias("CANVAS_URL") ?? `http://127.0.0.1:${envAlias("WEB_PORT") ?? "4598"}`;
+const canvasLink = (path) => `${CANVAS_URL}/?doc=${encodeURIComponent(path)}`;
 // ─── File-backed shared store ────────────────────────────────────────
 // Both web/ and mcp/ resolve the same path from STATELOOM_PROJECT_FILE
 // (legacy twin SMCRAFT_PROJECT_FILE still honored).
@@ -301,7 +309,7 @@ function generatePythonFallback(def) {
     const events = collectEventIds(def);
     lines.push(`"""Generated by SMCraft"""`);
     lines.push(`from enum import Enum, auto`);
-    lines.push(`from smcraft.runtime import Context, State, TransitionHelper`);
+    lines.push(`from stateloom.runtime import Context, State, TransitionHelper`);
     lines.push(``);
     lines.push(`class StateId(Enum):`);
     for (const s of collectStateNames(def.state)) {
@@ -577,364 +585,389 @@ function glyph(direction) {
     return { South: "🔥", East: "🌅", North: "❄️", West: "🌊" }[direction] ?? "•";
 }
 // ─── MCP Server ──────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "stateloom-mcp",
-    version: "0.1.3",
-});
-// Tools
-server.tool("create_state_machine", "Create a new state machine definition with namespace and name", { namespace: z.string(), name: z.string(), asynchronous: z.boolean().optional() }, async ({ namespace, name, asynchronous }) => {
-    const def = createEmpty(namespace, name);
-    if (asynchronous)
-        def.settings.asynchronous = true;
-    writeDef(def);
-    bridgeEmitFull(def);
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Created state machine '${name}' in namespace '${namespace}' → ${PROJECT_FILE}. Add states and events next.`,
-            },
-        ],
-    };
-});
-server.tool("add_state", "Add a state to the state machine. Parent defaults to Root.", {
-    name: z.string(),
-    parent: z.string().optional(),
-    kind: z.enum(["normal", "final", "history"]).optional(),
-    description: z.string().optional(),
-}, async ({ name, parent, kind, description }) => {
-    const def = readDef();
-    if (!def)
-        return {
-            content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}. Use create_state_machine first.` }],
-            isError: true,
-        };
-    const parentName = parent ?? "Root";
-    const parentState = findState(def.state, parentName);
-    if (!parentState)
-        return {
-            content: [{ type: "text", text: `Parent state '${parentName}' not found.` }],
-            isError: true,
-        };
-    if (!parentState.states)
-        parentState.states = [];
-    parentState.states.push({ name, kind: kind ?? "normal", description });
-    writeDef(def);
-    bridgeEmitPatch([
-        { op: "state.add", parent: parentName, state: { name, kind: kind ?? "normal", description } },
-    ]);
-    return {
-        content: [{ type: "text", text: `Added state '${name}' under '${parentName}' (${kind ?? "normal"}).` }],
-    };
-});
-server.tool("add_event", "Add an event to the state machine", { id: z.string(), description: z.string().optional() }, async ({ id, description }) => {
-    const def = readDef();
-    if (!def)
+/**
+ * Build a fully-registered server instance.
+ *
+ * A factory rather than a singleton because one `McpServer` can only be
+ * initialized once: a second client sending `initialize` to the same instance
+ * is refused, so a shared instance can serve exactly one caller for the life of
+ * the process. Stdio still builds exactly one and behaves as it always has;
+ * HTTP builds one per request, which is the SDK's stateless pattern and what
+ * lets more than one agent reach the same loom.
+ *
+ * Every tool closes over module-level state (PROJECT_FILE, the bridge client),
+ * so instances are interchangeable — building one is registration, not state.
+ */
+function buildServer() {
+    const server = new McpServer({
+        name: "stateloom-mcp",
+        version: "0.2.0",
+    });
+    // Tools
+    server.tool("create_state_machine", "Create a new state machine definition with namespace and name", { namespace: z.string(), name: z.string(), asynchronous: z.boolean().optional() }, async ({ namespace, name, asynchronous }) => {
+        const def = createEmpty(namespace, name);
+        if (asynchronous)
+            def.settings.asynchronous = true;
+        writeDef(def);
+        bridgeEmitFull(def);
         return {
-            content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
-            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Created state machine '${name}' in namespace '${namespace}' → ${PROJECT_FILE}. Add states and events next.`,
+                },
+            ],
         };
-    const source = def.events[0];
-    source.events.push({ id, description });
-    writeDef(def);
-    bridgeEmitPatch([{ op: "event.add", sourceIndex: 0, event: { id, description } }]);
-    return {
-        content: [{ type: "text", text: `Added event '${id}'.` }],
-    };
-});
-server.tool("add_transition", "Add a transition to a state, triggered by an event", {
-    state: z.string(),
-    event: z.string(),
-    nextState: z.string().optional(),
-    condition: z.string().optional(),
-    description: z.string().optional(),
-}, async ({ state, event, nextState, condition, description }) => {
-    const def = readDef();
-    if (!def)
+    });
+    server.tool("add_state", "Add a state to the state machine. Parent defaults to Root.", {
+        name: z.string(),
+        parent: z.string().optional(),
+        kind: z.enum(["normal", "final", "history"]).optional(),
+        description: z.string().optional(),
+    }, async ({ name, parent, kind, description }) => {
+        const def = readDef();
+        if (!def)
+            return {
+                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}. Use create_state_machine first.` }],
+                isError: true,
+            };
+        const parentName = parent ?? "Root";
+        const parentState = findState(def.state, parentName);
+        if (!parentState)
+            return {
+                content: [{ type: "text", text: `Parent state '${parentName}' not found.` }],
+                isError: true,
+            };
+        if (!parentState.states)
+            parentState.states = [];
+        parentState.states.push({ name, kind: kind ?? "normal", description });
+        writeDef(def);
+        bridgeEmitPatch([
+            { op: "state.add", parent: parentName, state: { name, kind: kind ?? "normal", description } },
+        ]);
         return {
-            content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
-            isError: true,
+            content: [{ type: "text", text: `Added state '${name}' under '${parentName}' (${kind ?? "normal"}).` }],
         };
-    const target = findState(def.state, state);
-    if (!target)
+    });
+    server.tool("add_event", "Add an event to the state machine", { id: z.string(), description: z.string().optional() }, async ({ id, description }) => {
+        const def = readDef();
+        if (!def)
+            return {
+                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                isError: true,
+            };
+        const source = def.events[0];
+        source.events.push({ id, description });
+        writeDef(def);
+        bridgeEmitPatch([{ op: "event.add", sourceIndex: 0, event: { id, description } }]);
         return {
-            content: [{ type: "text", text: `State '${state}' not found.` }],
-            isError: true,
+            content: [{ type: "text", text: `Added event '${id}'.` }],
         };
-    if (!target.transitions)
-        target.transitions = [];
-    target.transitions.push({ event, nextState, condition, description });
-    writeDef(def);
-    bridgeEmitPatch([
-        { op: "transition.add", state, transition: { event, nextState, condition, description } },
-    ]);
-    const desc = nextState ? `${state} --[${event}]--> ${nextState}` : `${state} --[${event}]--> (internal)`;
-    return { content: [{ type: "text", text: `Added transition: ${desc}` }] };
-});
-server.tool("remove_state", "Remove a state from the definition", { name: z.string() }, async ({ name }) => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    if (name === "Root")
-        return { content: [{ type: "text", text: "Cannot remove Root state." }], isError: true };
-    def.state = removeState(def.state, name);
-    writeDef(def);
-    bridgeEmitPatch([{ op: "state.remove", name }]);
-    return { content: [{ type: "text", text: `Removed state '${name}'.` }] };
-});
-server.tool("validate_definition", "Validate the current state machine definition against all rules", {}, async () => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    const errors = validate(def);
-    if (errors.length === 0)
-        return { content: [{ type: "text", text: "✓ Definition is valid. No errors found." }] };
-    const lines = errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
-    return {
-        content: [{ type: "text", text: `Found ${errors.length} validation error(s):\n${lines}` }],
-    };
-});
-server.tool("generate_code", "Generate Python or TypeScript code from the current definition", { language: z.enum(["python", "typescript"]) }, async ({ language }) => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    const errors = validate(def);
-    if (errors.length > 0) {
+    });
+    server.tool("add_transition", "Add a transition to a state, triggered by an event", {
+        state: z.string(),
+        event: z.string(),
+        nextState: z.string().optional(),
+        condition: z.string().optional(),
+        description: z.string().optional(),
+    }, async ({ state, event, nextState, condition, description }) => {
+        const def = readDef();
+        if (!def)
+            return {
+                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                isError: true,
+            };
+        const target = findState(def.state, state);
+        if (!target)
+            return {
+                content: [{ type: "text", text: `State '${state}' not found.` }],
+                isError: true,
+            };
+        if (!target.transitions)
+            target.transitions = [];
+        target.transitions.push({ event, nextState, condition, description });
+        writeDef(def);
+        bridgeEmitPatch([
+            { op: "transition.add", state, transition: { event, nextState, condition, description } },
+        ]);
+        const desc = nextState ? `${state} --[${event}]--> ${nextState}` : `${state} --[${event}]--> (internal)`;
+        return { content: [{ type: "text", text: `Added transition: ${desc}` }] };
+    });
+    server.tool("remove_state", "Remove a state from the definition", { name: z.string() }, async ({ name }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        if (name === "Root")
+            return { content: [{ type: "text", text: "Cannot remove Root state." }], isError: true };
+        def.state = removeState(def.state, name);
+        writeDef(def);
+        bridgeEmitPatch([{ op: "state.remove", name }]);
+        return { content: [{ type: "text", text: `Removed state '${name}'.` }] };
+    });
+    server.tool("validate_definition", "Validate the current state machine definition against all rules", {}, async () => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const errors = validate(def);
+        if (errors.length === 0)
+            return { content: [{ type: "text", text: "✓ Definition is valid. No errors found." }] };
         const lines = errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
         return {
-            content: [{ type: "text", text: `Fix validation errors first:\n${lines}` }],
-            isError: true,
+            content: [{ type: "text", text: `Found ${errors.length} validation error(s):\n${lines}` }],
         };
-    }
-    const code = generateViaSmcg(def, language);
-    return { content: [{ type: "text", text: code }] };
-});
-server.tool("get_definition", "Get the current state machine definition as JSON", {}, async () => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    return {
-        content: [{ type: "text", text: JSON.stringify({ stateMachine: def }, null, 2) }],
-    };
-});
-server.tool("load_definition", "Load a state machine definition from JSON", { json: z.string() }, async ({ json }) => {
-    try {
-        const parsed = JSON.parse(json);
-        const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
-        writeDef(def);
-        bridgeEmitFull(def);
-        const stateCount = collectStateNames(def.state).length;
-        const eventCount = collectEventIds(def).length;
+    });
+    server.tool("generate_code", "Generate Python or TypeScript code from the current definition", { language: z.enum(["python", "typescript"]) }, async ({ language }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const errors = validate(def);
+        if (errors.length > 0) {
+            const lines = errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
+            return {
+                content: [{ type: "text", text: `Fix validation errors first:\n${lines}` }],
+                isError: true,
+            };
+        }
+        const code = generateViaSmcg(def, language);
+        return { content: [{ type: "text", text: code }] };
+    });
+    server.tool("get_definition", "Get the current state machine definition as JSON", {}, async () => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
         return {
-            content: [
-                {
-                    type: "text",
-                    text: `Loaded definition → ${PROJECT_FILE}: ${def.settings.name} (${stateCount} states, ${eventCount} events)`,
-                },
-            ],
+            content: [{ type: "text", text: JSON.stringify({ stateMachine: def }, null, 2) }],
         };
-    }
-    catch (e) {
-        return { content: [{ type: "text", text: `Invalid JSON: ${e}` }], isError: true };
-    }
-});
-server.tool("list_states", "List all states in the current definition with their kind and transitions", {}, async () => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    const lines = [];
-    const walk = (state, depth) => {
-        const indent = "  ".repeat(depth);
-        const kind = state.kind ? ` (${state.kind})` : "";
-        const transCount = state.transitions?.length ?? 0;
-        lines.push(`${indent}${state.name}${kind} — ${transCount} transition(s)`);
-        for (const t of state.transitions ?? []) {
-            lines.push(`${indent}  → [${t.event}] → ${t.nextState ?? "(internal)"}`);
+    });
+    server.tool("load_definition", "Load a state machine definition from JSON", { json: z.string() }, async ({ json }) => {
+        try {
+            const parsed = JSON.parse(json);
+            const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+            writeDef(def);
+            bridgeEmitFull(def);
+            const stateCount = collectStateNames(def.state).length;
+            const eventCount = collectEventIds(def).length;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Loaded definition → ${PROJECT_FILE}: ${def.settings.name} (${stateCount} states, ${eventCount} events)`,
+                    },
+                ],
+            };
         }
-        (state.states ?? []).forEach((s) => walk(s, depth + 1));
-    };
-    walk(def.state, 0);
-    return { content: [{ type: "text", text: lines.join("\n") }] };
-});
-server.tool("list_events", "List all events in the current definition", {}, async () => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    const events = def.events.flatMap((src) => src.events.map((e) => `${e.id}${e.description ? ` — ${e.description}` : ""}`));
-    if (events.length === 0)
-        return { content: [{ type: "text", text: "No events defined yet." }] };
-    return { content: [{ type: "text", text: events.join("\n") }] };
-});
-server.tool("set_project_file", "Choose which .smdf.json path is the active document the loom weaves. Disk persistence AND the live bridge room (the hub keys rooms by this path) both re-point to it. A missing file is legitimate — create_state_machine or load_definition writes it next. Path must end in .json; convention is *.smdf.json.", { path: z.string() }, async ({ path }) => {
-    try {
-        const r = resolveProjectSwitch(path, PROJECT_FILE);
-        PROJECT_FILE = r.path;
-        if (!r.unchanged) {
-            bindBridge(PROJECT_FILE);
-            joinBridge();
+        catch (e) {
+            return { content: [{ type: "text", text: `Invalid JSON: ${e}` }], isError: true };
         }
-        const def = r.exists ? readDef() : null;
+    });
+    server.tool("list_states", "List all states in the current definition with their kind and transitions", {}, async () => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const lines = [];
+        const walk = (state, depth) => {
+            const indent = "  ".repeat(depth);
+            const kind = state.kind ? ` (${state.kind})` : "";
+            const transCount = state.transitions?.length ?? 0;
+            lines.push(`${indent}${state.name}${kind} — ${transCount} transition(s)`);
+            for (const t of state.transitions ?? []) {
+                lines.push(`${indent}  → [${t.event}] → ${t.nextState ?? "(internal)"}`);
+            }
+            (state.states ?? []).forEach((s) => walk(s, depth + 1));
+        };
+        walk(def.state, 0);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.tool("list_events", "List all events in the current definition", {}, async () => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const events = def.events.flatMap((src) => src.events.map((e) => `${e.id}${e.description ? ` — ${e.description}` : ""}`));
+        if (events.length === 0)
+            return { content: [{ type: "text", text: "No events defined yet." }] };
+        return { content: [{ type: "text", text: events.join("\n") }] };
+    });
+    server.tool("set_project_file", "Choose which .smdf.json path is the active document the loom weaves. Disk persistence AND the live bridge room (the hub keys rooms by this path) both re-point to it. A missing file is legitimate — create_state_machine or load_definition writes it next. Path must end in .json; convention is *.smdf.json.", { path: z.string() }, async ({ path }) => {
+        try {
+            const r = resolveProjectSwitch(path, PROJECT_FILE);
+            const denial = denyProjectSwitch(r.path);
+            if (denial)
+                return { content: [{ type: "text", text: denial }], isError: true };
+            PROJECT_FILE = r.path;
+            if (!r.unchanged) {
+                bindBridge(PROJECT_FILE);
+                joinBridge();
+            }
+            const def = r.exists ? readDef() : null;
+            const summary = def
+                ? `existing machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
+                : r.exists
+                    ? "file exists but is not a readable definition"
+                    : "no file yet — create_state_machine or load_definition will write it";
+            const bridgeNote = BRIDGE_URL
+                ? r.unchanged
+                    ? `bridge unchanged (${bridge?.status ?? "not configured"})`
+                    : `bridge re-joining room '${r.path}'`
+                : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Active document: ${r.path}\nPrevious: ${r.previous}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(r.path)}`,
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_project_file", "Report the active .smdf.json document path, whether it exists on disk, and live-bridge status", {}, async () => {
+        const def = readDef();
         const summary = def
-            ? `existing machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
-            : r.exists
+            ? `machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
+            : existsSync(PROJECT_FILE)
                 ? "file exists but is not a readable definition"
-                : "no file yet — create_state_machine or load_definition will write it";
+                : "file does not exist yet";
         const bridgeNote = BRIDGE_URL
-            ? r.unchanged
-                ? `bridge unchanged (${bridge?.status ?? "not configured"})`
-                : `bridge re-joining room '${r.path}'`
+            ? `bridge: ${bridge?.status ?? "not initialized"} → ${BRIDGE_URL}`
             : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
         return {
             content: [
-                {
-                    type: "text",
-                    text: `Active document: ${r.path}\nPrevious: ${r.previous}\n${summary}\n${bridgeNote}`,
-                },
+                { type: "text", text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(PROJECT_FILE)}` },
             ],
         };
+    });
+    server.tool("generate_rispec", "Generate a RISE rispec (markdown) from the current state machine. If the SMDF was sourced from a PDE (settings._source.pdeId/pdeFolder), the PDE's intent, directions, and ambiguities are folded in. Pass `intent` to override the desired outcome.", { intent: z.string().optional() }, async ({ intent }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const md = generateRispec(def, intent);
+        return { content: [{ type: "text", text: md }] };
+    });
+    /**
+     * How large a PNG may be and still ride back inside the tool result. Past this
+     * the agent gets the path alone — a multi-megabyte base64 blob would crowd out
+     * the conversation it was meant to illustrate.
+     */
+    const INLINE_IMAGE_LIMIT = 1_500_000;
+    /** Hand a rendered file to the platform viewer. Never fatal — a server has none. */
+    function openOnDesktop(path) {
+        const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        try {
+            const child = spawn(opener, [path], {
+                stdio: "ignore",
+                detached: true,
+                shell: process.platform === "win32",
+            });
+            child.on("error", () => { });
+            child.unref();
+            return `opened with ${opener}`;
+        }
+        catch {
+            return "no desktop opener available";
+        }
     }
-    catch (e) {
-        return {
-            content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
-            isError: true,
-        };
-    }
-});
-server.tool("get_project_file", "Report the active .smdf.json document path, whether it exists on disk, and live-bridge status", {}, async () => {
-    const def = readDef();
-    const summary = def
-        ? `machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
-        : existsSync(PROJECT_FILE)
-            ? "file exists but is not a readable definition"
-            : "file does not exist yet";
-    const bridgeNote = BRIDGE_URL
-        ? `bridge: ${bridge?.status ?? "not initialized"} → ${BRIDGE_URL}`
-        : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
-    return {
-        content: [
-            { type: "text", text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}` },
-        ],
-    };
-});
-server.tool("generate_rispec", "Generate a RISE rispec (markdown) from the current state machine. If the SMDF was sourced from a PDE (settings._source.pdeId/pdeFolder), the PDE's intent, directions, and ambiguities are folded in. Pass `intent` to override the desired outcome.", { intent: z.string().optional() }, async ({ intent }) => {
-    const def = readDef();
-    if (!def)
-        return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
-    const md = generateRispec(def, intent);
-    return { content: [{ type: "text", text: md }] };
-});
-/**
- * How large a PNG may be and still ride back inside the tool result. Past this
- * the agent gets the path alone — a multi-megabyte base64 blob would crowd out
- * the conversation it was meant to illustrate.
- */
-const INLINE_IMAGE_LIMIT = 1_500_000;
-/** Hand a rendered file to the platform viewer. Never fatal — a server has none. */
-function openOnDesktop(path) {
-    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    try {
-        const child = spawn(opener, [path], {
-            stdio: "ignore",
-            detached: true,
-            shell: process.platform === "win32",
-        });
-        child.on("error", () => { });
-        child.unref();
-        return `opened with ${opener}`;
-    }
-    catch {
-        return "no desktop opener available";
-    }
-}
-server.tool("render_diagram", "Draw the current state machine as a picture. Writes the file next to the project document (or at `path`) and returns its absolute path — plus the image itself for png, so it can be looked at without leaving the conversation. Formats: png (raster, needs librsvg/Inkscape/ImageMagick/Chrome on the host), svg (needs nothing), mermaid, ascii. Pass stamp:true to keep every render instead of overwriting one file.", {
-    format: z.enum(["png", "svg", "mermaid", "ascii"]).optional(),
-    path: z.string().optional(),
-    scale: z.number().optional(),
-    theme: z.enum(["dark", "light"]).optional(),
-    stamp: z.boolean().optional(),
-    open: z.boolean().optional(),
-}, async ({ format, path, scale, theme, stamp, open }) => {
-    const def = readDef();
-    if (!def)
-        return {
-            content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
-            isError: true,
-        };
-    const chosen = format ?? "png";
-    try {
-        const result = await renderDiagramToFile(def, {
-            format: chosen,
-            out: path,
-            doc: PROJECT_FILE,
-            scale,
-            theme,
-            stamp,
-        });
-        const size = result.width && result.height ? `, ${result.width}×${result.height}` : "";
-        const how = result.backend ? `, drawn by ${result.backend}` : "";
-        const opened = open ? ` — ${openOnDesktop(result.path)}` : "";
-        const note = `Rendered '${def.settings.name}' → ${result.path} (${result.bytes} bytes${size}${how})${opened}`;
-        // png and svg come back as pictures; the text formats are already text.
-        if (chosen === "png" && result.bytes <= INLINE_IMAGE_LIMIT) {
+    server.tool("render_diagram", "Draw the current state machine as a picture. Writes the file next to the project document (or at `path`) and returns its absolute path — plus the image itself for png, so it can be looked at without leaving the conversation. Formats: png (raster, needs librsvg/Inkscape/ImageMagick/Chrome on the host), svg (needs nothing), mermaid, ascii. Pass stamp:true to keep every render instead of overwriting one file.", {
+        format: z.enum(["png", "svg", "mermaid", "ascii"]).optional(),
+        path: z.string().optional(),
+        scale: z.number().optional(),
+        theme: z.enum(["dark", "light"]).optional(),
+        stamp: z.boolean().optional(),
+        open: z.boolean().optional(),
+    }, async ({ format, path, scale, theme, stamp, open }) => {
+        const def = readDef();
+        if (!def)
             return {
-                content: [
-                    { type: "text", text: note },
-                    {
-                        type: "image",
-                        data: readFileSync(result.path).toString("base64"),
-                        mimeType: "image/png",
-                    },
-                ],
+                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                isError: true,
             };
+        const chosen = format ?? "png";
+        if (path) {
+            // A render writes state names — free text the caller chose — into a file
+            // the caller named. Under a document root that is exactly the write that
+            // has to stay inside it.
+            const denial = outsideRoot(path);
+            if (denial)
+                return { content: [{ type: "text", text: denial }], isError: true };
         }
-        if (chosen === "mermaid" || chosen === "ascii") {
+        try {
+            const result = await renderDiagramToFile(def, {
+                format: chosen,
+                out: path,
+                doc: PROJECT_FILE,
+                scale,
+                theme,
+                stamp,
+            });
+            const size = result.width && result.height ? `, ${result.width}×${result.height}` : "";
+            const how = result.backend ? `, drawn by ${result.backend}` : "";
+            const opened = open ? ` — ${openOnDesktop(result.path)}` : "";
+            const note = `Rendered '${def.settings.name}' → ${result.path} (${result.bytes} bytes${size}${how})${opened}`;
+            // png and svg come back as pictures; the text formats are already text.
+            if (chosen === "png" && result.bytes <= INLINE_IMAGE_LIMIT) {
+                return {
+                    content: [
+                        { type: "text", text: note },
+                        {
+                            type: "image",
+                            data: readFileSync(result.path).toString("base64"),
+                            mimeType: "image/png",
+                        },
+                    ],
+                };
+            }
+            if (chosen === "mermaid" || chosen === "ascii") {
+                return {
+                    content: [
+                        { type: "text", text: note },
+                        { type: "text", text: readFileSync(result.path, "utf8") },
+                    ],
+                };
+            }
+            return { content: [{ type: "text", text: note }] };
+        }
+        catch (e) {
+            const why = e instanceof Error ? e.message : String(e);
             return {
                 content: [
-                    { type: "text", text: note },
-                    { type: "text", text: readFileSync(result.path, "utf8") },
+                    {
+                        type: "text",
+                        text: `render_diagram (${chosen}) failed: ${why}\n` +
+                            `An SVG needs no rasterizer — retry with format "svg" ` +
+                            `(it would land at ${defaultOutputPath(PROJECT_FILE, "svg")}).`,
+                    },
                 ],
+                isError: true,
             };
         }
-        return { content: [{ type: "text", text: note }] };
-    }
-    catch (e) {
-        const why = e instanceof Error ? e.message : String(e);
+    });
+    // Resources
+    server.resource("definition", "smcraft://definition", async () => {
+        const def = readDef();
         return {
-            content: [
+            contents: [
                 {
-                    type: "text",
-                    text: `render_diagram (${chosen}) failed: ${why}\n` +
-                        `An SVG needs no rasterizer — retry with format "svg" ` +
-                        `(it would land at ${defaultOutputPath(PROJECT_FILE, "svg")}).`,
+                    uri: "smcraft://definition",
+                    mimeType: "application/json",
+                    text: def
+                        ? JSON.stringify({ stateMachine: def }, null, 2)
+                        : `{"error": "No definition at ${PROJECT_FILE}"}`,
                 },
             ],
-            isError: true,
         };
-    }
-});
-// Resources
-server.resource("definition", "smcraft://definition", async () => {
-    const def = readDef();
-    return {
-        contents: [
+    });
+    // Prompts
+    server.prompt("design-state-machine", "Guided conversation to design a state machine step by step", { domain: z.string().optional(), name: z.string().optional() }, ({ domain, name }) => ({
+        messages: [
             {
-                uri: "smcraft://definition",
-                mimeType: "application/json",
-                text: def
-                    ? JSON.stringify({ stateMachine: def }, null, 2)
-                    : `{"error": "No definition at ${PROJECT_FILE}"}`,
-            },
-        ],
-    };
-});
-// Prompts
-server.prompt("design-state-machine", "Guided conversation to design a state machine step by step", { domain: z.string().optional(), name: z.string().optional() }, ({ domain, name }) => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: `I want to design a state machine${name ? ` called "${name}"` : ""}${domain ? ` for the "${domain}" domain` : ""}. Guide me through:
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I want to design a state machine${name ? ` called "${name}"` : ""}${domain ? ` for the "${domain}" domain` : ""}. Guide me through:
 1. First, create the state machine with create_state_machine
 2. Help me identify the key states and add them with add_state
 3. Define the events that trigger transitions with add_event
@@ -943,15 +976,278 @@ server.prompt("design-state-machine", "Guided conversation to design a state mac
 6. Generate code with generate_code
 
 Start by asking me about the states and events I need.`,
+                },
             },
-        },
-    ],
-}));
-// Start
+        ],
+    }));
+    return server;
+}
+// ─── Transports ──────────────────────────────────────────────────────
+//
+// Stdio is the default and is unchanged: no new environment variable, no new
+// flag, and this server still boots as a child process beside one agent with
+// the parent's trust. Everything below only runs when someone explicitly asks
+// for a port, so an existing registration cannot fall into HTTP by accident.
+//
+// The remote mode is deliberately narrow about what it will do, because the
+// two things stdio got for free — one client, and the caller's own filesystem
+// trust — are exactly what a port gives away:
+//
+//   STATELOOM_MCP_HTTP_PORT   the port to bind; unset means stdio (default)
+//   STATELOOM_MCP_HTTP_HOST   interface, default 127.0.0.1 — loopback, not 0.0.0.0
+//   STATELOOM_MCP_TOKEN       required bearer token; without one, a reachable
+//                             port is an unauthenticated write primitive on the
+//                             host, so HTTP mode refuses to start
+//   STATELOOM_MCP_ROOT        confine every document to this directory
+//   STATELOOM_MCP_LOCK_PROJECT  refuse set_project_file outright
+//
+// What this mode is NOT: multi-tenant. The active document is process state,
+// so every HTTP client shares one board — which is the loom's whole premise
+// for humans and agents together, and a hazard between strangers. Per-session
+// documents need a server instance per session; that is a real change and is
+// not pretended at here.
+const HTTP_PORT = envAlias("MCP_HTTP_PORT");
+const HTTP_HOST = envAlias("MCP_HTTP_HOST") ?? "127.0.0.1";
+const HTTP_TOKEN = envAlias("MCP_TOKEN");
+const DOC_ROOT = (() => {
+    const raw = envAlias("MCP_ROOT");
+    if (!raw)
+        return undefined;
+    // realpath the root too: comparing a real path against a symlinked root
+    // would refuse every legitimate document inside it.
+    try {
+        return realpathSync(resolve(raw));
+    }
+    catch {
+        return resolve(raw);
+    }
+})();
+const LOCK_PROJECT = /^(1|true|yes)$/i.test(envAlias("MCP_LOCK_PROJECT") ?? "");
+/**
+ * Guard for `set_project_file`. Returns a refusal string, or undefined to allow.
+ *
+ * Unset environment means unset behaviour: with neither a root nor a lock this
+ * returns undefined every time, so the stdio path a thousand agents already run
+ * behaves exactly as it did.
+ */
+function denyProjectSwitch(target) {
+    if (LOCK_PROJECT) {
+        return `set_project_file is locked on this server (STATELOOM_MCP_LOCK_PROJECT). Active document stays ${PROJECT_FILE}.`;
+    }
+    return outsideRoot(target);
+}
+/**
+ * Resolve a path the way the filesystem will, not the way the string looks.
+ *
+ * A lexical `startsWith(root + "/")` refuses `..` and prefix siblings, and is
+ * still wrong: `root/link -> /elsewhere` passes the string test and lands
+ * outside. So the deepest part of the path that actually exists is put through
+ * `realpathSync` — which follows every symlink in it — and the not-yet-created
+ * tail is rejoined onto that. A file the caller is about to create inside a
+ * symlinked directory is judged by where the directory really is.
+ */
+function trueResolve(target) {
+    let existing = resolve(target);
+    const tail = [];
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing)
+            return resolve(target); // reached the filesystem root
+        tail.unshift(basename(existing));
+        existing = parent;
+    }
+    try {
+        return join(realpathSync(existing), ...tail);
+    }
+    catch {
+        return resolve(target);
+    }
+}
+/**
+ * Refusal string when `target` falls outside `STATELOOM_MCP_ROOT`, else undefined.
+ *
+ * Every caller-supplied path goes through here, not just `set_project_file`:
+ * `render_diagram` takes a `path` and writes state names into it, which is a
+ * file write with attacker-chosen content and was the hole a confined server
+ * most needed closed. With no root configured this returns undefined always, so
+ * the stdio path is unaffected.
+ */
+function outsideRoot(target) {
+    if (!DOC_ROOT)
+        return undefined;
+    const real = trueResolve(target);
+    if (real === DOC_ROOT || real.startsWith(DOC_ROOT + "/"))
+        return undefined;
+    return `Refused: ${target} resolves to ${real}, outside the permitted document root ${DOC_ROOT} (STATELOOM_MCP_ROOT).`;
+}
+/** Constant-time bearer check — a fast string compare leaks the token by timing. */
+function authorized(req) {
+    if (!HTTP_TOKEN)
+        return false;
+    const header = req.headers.authorization ?? "";
+    const offered = header.startsWith("Bearer ") ? header.slice(7) : "";
+    const a = Buffer.from(offered);
+    const b = Buffer.from(HTTP_TOKEN);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Largest body accepted; the biggest legitimate one is a whole definition. */
+const BODY_LIMIT = 8 * 1024 * 1024;
+function readBody(req) {
+    return new Promise((ok, fail) => {
+        const chunks = [];
+        let size = 0;
+        let oversize = false;
+        req.on("data", (c) => {
+            size += c.length;
+            // A body cap keeps an unauthenticated probe from being a memory attack;
+            // the largest legitimate payload here is a whole definition.
+            if (size > BODY_LIMIT) {
+                oversize = true;
+                fail(new Error(`request body over ${BODY_LIMIT} bytes`));
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => {
+            if (oversize)
+                return;
+            const raw = Buffer.concat(chunks).toString("utf8");
+            if (!raw)
+                return ok(undefined);
+            try {
+                ok(JSON.parse(raw));
+            }
+            catch {
+                fail(new Error("body is not JSON"));
+            }
+        });
+        req.on("error", fail);
+    });
+}
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(text);
+}
+async function startHttp(port) {
+    if (!HTTP_TOKEN) {
+        console.error("Refusing to start HTTP mode without STATELOOM_MCP_TOKEN.\n" +
+            "An open port on this server is an unauthenticated way to read and write\n" +
+            "files on the host. Set a token, or drop the port and use stdio.");
+        process.exit(1);
+    }
+    // A root that does not contain the document it starts on confines nothing:
+    // every write tool would land outside it from the first request. Refuse at
+    // boot, where it is a config error, rather than at the first surprise.
+    const bootDenial = outsideRoot(PROJECT_FILE);
+    if (bootDenial) {
+        console.error(`Refusing to start: STATELOOM_PROJECT_FILE is outside STATELOOM_MCP_ROOT.\n  ${bootDenial}`);
+        process.exit(1);
+    }
+    // Stateless, deliberately, and a fresh server+transport per request. The
+    // stateful mode binds a session id to one transport and one server instance,
+    // and an `McpServer` refuses a second `initialize` — so anything shared here
+    // serves exactly one client for the life of the process, which is not what a
+    // port is for. Sessions would only earn that cost if they partitioned state,
+    // and they do not: the active document is process-global either way.
+    const http = createHttpServer((req, res) => {
+        const path = (req.url ?? "/").split("?")[0];
+        if (path === "/health") {
+            // Deliberately says nothing about the document. /health is the one
+            // unauthenticated route, and the active path is host filesystem layout.
+            sendJson(res, 200, { ok: true, transport: "http" });
+            return;
+        }
+        if (path !== "/mcp") {
+            sendJson(res, 404, { error: "not found — the MCP endpoint is /mcp" });
+            return;
+        }
+        if (req.method !== "POST") {
+            // GET on the MCP endpoint opens a server-push stream this server never
+            // has anything to push on: it stays open, pinning a socket and its
+            // buffers, and nothing ever closes it. The documented surface is POST.
+            res.setHeader("allow", "POST");
+            sendJson(res, 405, { error: "method not allowed — POST /mcp" });
+            return;
+        }
+        if (!authorized(req)) {
+            res.setHeader("www-authenticate", 'Bearer realm="stateloom-mcp"');
+            sendJson(res, 401, { error: "unauthorized" });
+            return;
+        }
+        readBody(req)
+            .then(async (body) => {
+            const instance = buildServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            // Tear down with the response, not before it: closing the transport
+            // while the reply is still streaming truncates it.
+            res.on("close", () => {
+                void transport.close().catch(() => { });
+                void instance.close().catch(() => { });
+            });
+            await instance.connect(transport);
+            await transport.handleRequest(req, res, body);
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error("[stateloom-mcp] request failed:", message);
+            if (res.headersSent)
+                return;
+            const tooBig = message.includes("request body over");
+            sendJson(res, tooBig ? 413 : 400, { error: message });
+            req.destroy();
+        });
+    });
+    await new Promise((ok, fail) => {
+        http.once("error", fail);
+        http.listen(port, HTTP_HOST, () => {
+            http.removeListener("error", fail);
+            ok();
+        });
+    }).catch((err) => {
+        const why = err.code === "EADDRINUSE"
+            ? `port ${port} is already in use on ${HTTP_HOST}`
+            : err.code === "EACCES"
+                ? `not allowed to bind ${HTTP_HOST}:${port}`
+                : (err.message ?? String(err));
+        console.error(`stateloom-mcp could not start: ${why}`);
+        process.exit(1);
+    });
+    console.error(`stateloom-mcp on http://${HTTP_HOST}:${port}/mcp (project file: ${PROJECT_FILE})` +
+        (DOC_ROOT ? `\n  documents confined to ${DOC_ROOT}` : "") +
+        (LOCK_PROJECT ? `\n  set_project_file locked` : "") +
+        (HTTP_HOST === "0.0.0.0"
+            ? `\n  WARNING: bound to every interface — put a TLS terminator in front of this.`
+            : ""));
+    const close = () => {
+        http.close();
+        bridge?.disconnect();
+        process.exit(0);
+    };
+    process.on("SIGINT", close);
+    process.on("SIGTERM", close);
+}
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`SMCraft MCP server running on stdio (project file: ${PROJECT_FILE})`);
+    if (HTTP_PORT) {
+        // Whole-string match: parseInt("8080abc") is 8080, which would bind a port
+        // nobody asked for. Zero is rejected too — the OS would pick an ephemeral
+        // port while the banner printed ":0", leaving a server nobody can reach.
+        if (!/^[0-9]{1,5}$/.test(HTTP_PORT.trim())) {
+            console.error(`STATELOOM_MCP_HTTP_PORT is not a port number: ${HTTP_PORT}`);
+            process.exit(1);
+        }
+        const port = Number.parseInt(HTTP_PORT.trim(), 10);
+        if (port < 1 || port > 65535) {
+            console.error(`STATELOOM_MCP_HTTP_PORT out of range (1-65535): ${HTTP_PORT}`);
+            process.exit(1);
+        }
+        await startHttp(port);
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await buildServer().connect(transport);
+        console.error(`stateloom-mcp running on stdio (project file: ${PROJECT_FILE})`);
+    }
     joinBridge();
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
   "repository": {
     "type": "git",