@miadi/stateloom-mcp 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guillaume Isabelle (jgwill)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @miadi/stateloom-mcp
+
+[![npm](https://img.shields.io/npm/v/%40miadi%2Fstateloom-mcp)](https://www.npmjs.com/package/@miadi/stateloom-mcp)
+
+MCP server for stateloom — an LLM agent designs a hierarchical state machine through conversation, and the diagram on your screen changes while it talks.
+
+## Install
+
+```bash
+npm install -g @miadi/stateloom-mcp
+# or let your MCP client fetch it:
+npx -y @miadi/stateloom-mcp
+```
+
+## What it is
+
+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.
+
+## Configure your MCP client
+
+```json
+{
+  "mcpServers": {
+    "stateloom": {
+      "command": "npx",
+      "args": ["-y", "@miadi/stateloom-mcp"],
+      "env": {
+        "STATELOOM_PROJECT_FILE": "/abs/path/to/statemachine.smdf.json",
+        "STATELOOM_BRIDGE_URL": "http://127.0.0.1:4599"
+      }
+    }
+  }
+}
+```
+
+| Environment variable | Default | Meaning |
+|---|---|---|
+| `STATELOOM_PROJECT_FILE` | `./statemachine.smdf.json` | The document read and written; also the live room key |
+| `STATELOOM_BRIDGE_URL` | — | Hub URL; without it the server persists to disk only |
+| `STATELOOM_AGENT_NAME` | — | Presence label shown to other people in the room |
+| `STATELOOM_BRIDGE_TOKEN` | — | Handshake token, when the hub requires one |
+
+The legacy `SMCRAFT_*` twin of each name is still honored. The package ships two bins — `stateloom-mcp` and, for existing registrations, `smcraft-mcp`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_state_machine` | Start a definition with a namespace and name |
+| `add_state` | Add a state; parent defaults to `Root` |
+| `add_event` | Add an event to an event source |
+| `add_transition` | Add a transition from a state, triggered by an event |
+| `remove_state` | Remove a state |
+| `get_definition` | Return the whole definition as JSON |
+| `load_definition` | Replace the definition from JSON |
+| `list_states` | Every state with its kind and transitions |
+| `list_events` | Every event |
+| `validate_definition` | Run the rule-coded validator |
+| `generate_code` | Emit Python or TypeScript from the definition |
+| `generate_rispec` | Emit a RISE rispec in markdown, folding in the source PDE's intent when the SMDF carries one |
+| `render_diagram` | Draw the machine as `png`, `svg`, `mermaid` or `ascii`, write it beside the document, and hand a `png` back inside the tool result so the agent sees what it designed |
+| `set_project_file` | Re-point the loom at another `.smdf.json` mid-session — disk target and live room both move |
+| `get_project_file` | The active document path, whether it exists, and bridge status |
+
+Also exposed: the resource `smcraft://definition` (the current definition), and the prompt `design-state-machine` — a guided conversation for building one from a domain description.
+
+## What a session looks like
+
+> **You:** design an order fulfillment workflow
+>
+> The agent calls `create_state_machine`, then `add_event` and `add_state` and `add_transition` a few times, then `validate_definition` to check its work, then `render_diagram` to look at it. Every one of those writes `/abs/path/to/statemachine.smdf.json` and pushes the change to the hub. Your canvas redraws as it goes.
+
+Because rooms are keyed by the document's absolute path, `set_project_file` is how one agent moves between machines in a session — point it at another episode's diagram and the next edit lands there instead.
+
+## Part of the stateloom stack
+
+| Package | Role |
+|---|---|
+| [`smcraft`](https://www.npmjs.com/package/smcraft) | 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 |
+| [`@miadi/stateloom-react`](https://www.npmjs.com/package/@miadi/stateloom-react) | React binding over the client |
+| [`@miadi/stateloom-cli`](https://www.npmjs.com/package/@miadi/stateloom-cli) | `smcx` — terminal design surface and renderers |
+| [`@miadi/stateloom-mcp`](https://www.npmjs.com/package/@miadi/stateloom-mcp) | MCP server so LLM agents can design machines — **this package** |
+
+## License
+
+MIT © Guillaume Isabelle

package/dist/server.d.ts

@@ -13,6 +13,7 @@
  *   - remove_state: Remove a state from the definition
  *   - validate_definition: Validate the current definition
  *   - generate_code: Generate Python or TypeScript code
+ *   - render_diagram: Draw the machine as an image on disk and return it
  *   - get_definition: Get the current definition as JSON
  *   - load_definition: Load a definition from JSON
  *   - list_states: List all states in the current definition

package/dist/server.js

@@ -13,6 +13,7 @@
  *   - remove_state: Remove a state from the definition
  *   - validate_definition: Validate the current definition
  *   - generate_code: Generate Python or TypeScript code
+ *   - render_diagram: Draw the machine as an image on disk and return it
  *   - get_definition: Get the current definition as JSON
  *   - load_definition: Load a definition from JSON
  *   - list_states: List all states in the current definition
@@ -29,12 +30,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { execFileSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { writeFileSync, readFileSync, mkdtempSync, rmSync, existsSync, statSync } from "fs";
 import { join, resolve } from "path";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
 import { envAlias } from "@miadi/stateloom-protocol";
+import { renderDiagramToFile, defaultOutputPath } from "@miadi/stateloom-cli/render";
 import { resolveProjectSwitch } from "./projectSwitch.js";
 // STATELOOM_* read first, SMCRAFT_* legacy twin honored — the live MCP
 // registration bakes SMCRAFT_PROJECT_FILE and must keep working (2026-07-27
@@ -576,8 +578,8 @@ function glyph(direction) {
 }
 // ─── MCP Server ──────────────────────────────────────────────────────
 const server = new McpServer({
-    name: "smcraft-mcp",
-    version: "0.1.0",
+    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 }) => {
@@ -821,6 +823,95 @@ server.tool("generate_rispec", "Generate a RISE rispec (markdown) from the curre
     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) {
+            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: `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,
+        };
+    }
+});
 // Resources
 server.resource("definition", "smcraft://definition", async () => {
     const def = readDef();

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/smcraft.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/jgwill/smcraft#readme",
+  "bugs": {
+    "url": "https://github.com/jgwill/smcraft/issues"
+  },
+  "author": "Guillaume Isabelle <jgi@jgwill.com>",
   "type": "module",
   "main": "dist/server.js",
+  "types": "dist/server.d.ts",
   "bin": {
     "stateloom-mcp": "dist/server.js",
     "smcraft-mcp": "dist/server.js"
@@ -13,14 +24,33 @@
     "start": "node dist/server.js",
     "test": "node --test dist/tests/*.test.js"
   },
+  "keywords": [
+    "state-machine",
+    "smdf",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "llm",
+    "stateloom"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@miadi/stateloom-client": "^0.1.0",
-    "@miadi/stateloom-protocol": "^0.1.1",
+    "@miadi/stateloom-cli": "^0.1.2",
+    "@miadi/stateloom-client": "^0.1.1",
+    "@miadi/stateloom-protocol": "^0.1.3",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.13",
     "typescript": "^5.7.0"
-  }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/tests/"
+  ]
 }

package/dist/tests/projectSwitch.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/projectSwitch.test.js

@@ -1,41 +0,0 @@
-/**
- * Path power (HANDOFF v2, Phase 2 deliverable 1): the pure logic behind the
- * `set_project_file` MCP tool. An agent may point the loom at any `.json`
- * document path; the switch must absolute-resolve the path, report whether a
- * file is already there (missing is legitimate — create_state_machine writes
- * it next), and refuse non-JSON paths outright.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { tmpdir } from "node:os";
-import { resolveProjectSwitch } from "../projectSwitch.js";
-test("projectSwitch: relative path resolves absolute and previous is carried", () => {
-    const r = resolveProjectSwitch("./some/machine.smdf.json", "/prev/doc.smdf.json");
-    assert.equal(r.path, resolve("./some/machine.smdf.json"));
-    assert.equal(r.previous, "/prev/doc.smdf.json");
-    assert.equal(r.exists, false);
-});
-test("projectSwitch: reports exists=true for a file already on disk", () => {
-    const dir = mkdtempSync(join(tmpdir(), "loom-switch-"));
-    const file = join(dir, "episode.smdf.json");
-    writeFileSync(file, JSON.stringify({ stateMachine: { settings: {}, events: [], state: { name: "Root" } } }));
-    try {
-        const r = resolveProjectSwitch(file, "/prev/doc.smdf.json");
-        assert.equal(r.path, file);
-        assert.equal(r.exists, true);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});
-test("projectSwitch: refuses a non-.json path", () => {
-    assert.throws(() => resolveProjectSwitch("/tmp/machine.yaml", "/prev/doc.smdf.json"), /\.json/);
-});
-test("projectSwitch: switching to the same path is allowed and reports it", () => {
-    const r = resolveProjectSwitch("/prev/doc.smdf.json", "/prev/doc.smdf.json");
-    assert.equal(r.path, "/prev/doc.smdf.json");
-    assert.equal(r.previous, "/prev/doc.smdf.json");
-    assert.equal(r.unchanged, true);
-});

package/src/projectSwitch.ts

@@ -1,32 +0,0 @@
-/**
- * Pure logic behind the `set_project_file` MCP tool (path power — the agent
- * chooses which `.smdf.json` document the loom weaves).
- */
-import { existsSync } from "fs";
-import { resolve } from "path";
-
-export interface SwitchResult {
-  /** Absolute path of the newly active document. */
-  path: string;
-  /** The previously active absolute path. */
-  previous: string;
-  /** Whether a file already exists at the new path (missing is fine). */
-  exists: boolean;
-  /** True when the new path equals the previous one. */
-  unchanged: boolean;
-}
-
-export function resolveProjectSwitch(next: string, previous: string): SwitchResult {
-  const path = resolve(next);
-  if (!path.endsWith(".json")) {
-    throw new Error(
-      `project file must be a .json document (got '${path}') — the loom weaves .smdf.json files`,
-    );
-  }
-  return {
-    path,
-    previous,
-    exists: existsSync(path),
-    unchanged: path === previous,
-  };
-}