@miadi/stateloom-mcp 0.1.2 → 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.js

@@ -578,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 }) => {

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.1.2",
+  "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,15 +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-cli": "^0.1.1",
-    "@miadi/stateloom-client": "^0.1.0",
-    "@miadi/stateloom-protocol": "^0.1.2",
+    "@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,
-  };
-}