@miadi/stateloom-mcp 0.3.0 → 0.3.2

package/dist/erd.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, collectNotes, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, isSqdfPath, isSysdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, updateErdSettings, summarizeErd, validateErd, } from "@miadi/stateloom-protocol";
+import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, collectNotes, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, isSqdfPath, isSysdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, updateErdSettings, summarizeErd, validateErd, normalizeNotes } from "@miadi/stateloom-protocol";
 import { stampedOutputPath } from "@miadi/stateloom-cli/render";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
@@ -9,7 +9,7 @@ export function readErd(path) {
     if (!existsSync(path))
         return null;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = normalizeNotes(JSON.parse(readFileSync(path, "utf8")));
         return isErdDefinition(parsed) ? parsed : null;
     }
     catch {
@@ -123,7 +123,7 @@ function readSmdf(path) {
         return null;
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+        const def = normalizeNotes(parsed.stateMachine ?? parsed.StateMachine ?? parsed);
         return def && typeof def === "object" && def.state ? def : null;
     }
     catch {

package/dist/sequence.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { SQD_FRAGMENT_KINDS, addFragment, addFragmentMessage, addMessage, addParticipant, allMessages, docKindOfPath, emptySequence, isSequenceDefinition, isSqdfPath, moveMessage, moveParticipant, parseMessageRef, removeFragment, removeMessage, removeParticipant, renameParticipant, renderMermaidSequence, summarizeSequence, updateFragment, updateMessage, updateParticipant, updateSqdSettings, validateSequence, } from "@miadi/stateloom-protocol";
+import { SQD_FRAGMENT_KINDS, addFragment, addFragmentMessage, addMessage, addParticipant, allMessages, docKindOfPath, emptySequence, isSequenceDefinition, isSqdfPath, moveMessage, moveParticipant, parseMessageRef, removeFragment, removeMessage, removeParticipant, renameParticipant, renderMermaidSequence, summarizeSequence, updateFragment, updateMessage, updateParticipant, updateSqdSettings, validateSequence, normalizeNotes } from "@miadi/stateloom-protocol";
 import { stampedOutputPath } from "@miadi/stateloom-cli/render";
 import { formatNotes } from "./erd.js";
 import { writeFileAtomic } from "./atomicWrite.js";
@@ -13,7 +13,7 @@ export function readSequence(path) {
     if (!existsSync(path))
         return null;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = normalizeNotes(JSON.parse(readFileSync(path, "utf8")));
         return isSequenceDefinition(parsed) ? parsed : null;
     }
     catch {

package/dist/server.js

@@ -65,7 +65,7 @@ import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
-import { collectNotes, docKindOfPath, envAlias, isErdfPath, isSqdfPath, isSysdfPath, } from "@miadi/stateloom-protocol";
+import { collectNotes, docKindOfPath, envAlias, isErdfPath, isSqdfPath, isSysdfPath, normalizeNotes, } from "@miadi/stateloom-protocol";
 import { renderDiagramToFile, defaultOutputPath } from "@miadi/stateloom-cli/render";
 import { resolveProjectSwitch } from "./projectSwitch.js";
 import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdRender, erdGetNotes, erdSetNotes, formatNotes, } from "./erd.js";
@@ -108,7 +108,7 @@ function readDef() {
     try {
         const raw = readFileSync(PROJECT_FILE, "utf8");
         const parsed = JSON.parse(raw);
-        return parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+        return normalizeNotes(parsed.stateMachine ?? parsed.StateMachine ?? parsed);
     }
     catch (e) {
         console.error(`[smcraft-mcp] Failed to read ${PROJECT_FILE}:`, e);
@@ -120,7 +120,17 @@ function writeDef(def) {
     // and load_definition write without reading first, so this is the one place that can refuse.
     if (docKindOfPath(PROJECT_FILE) !== "machine")
         throw new Error(noMachine());
-    writeFileSync(PROJECT_FILE, JSON.stringify({ stateMachine: def }, null, 2), "utf8");
+    // Keep the file's own shape: a machine written bare stays bare, so one edit is
+    // a small diff and not the whole file re-indented under `stateMachine`.
+    let bare = false;
+    try {
+        const current = JSON.parse(readFileSync(PROJECT_FILE, "utf8"));
+        bare = !!current && typeof current === "object" && "state" in current && !("stateMachine" in current) && !("StateMachine" in current);
+    }
+    catch {
+        // A new or unreadable file is written in the loom's own shape.
+    }
+    writeFileSync(PROJECT_FILE, JSON.stringify(bare ? def : { stateMachine: def }, null, 2) + (bare ? "\n" : ""), "utf8");
 }
 // ─── Optional real-time design bridge (env-gated, best-effort) ───────
 // When STATELOOM_BRIDGE_URL (or legacy SMCRAFT_BRIDGE_URL) is set, each
@@ -657,6 +667,11 @@ function renderStateSpec(s, lines, depthLevel) {
     const indent = "  ".repeat(depthLevel);
     const kind = s.kind && s.kind !== "normal" ? ` *(${s.kind})*` : "";
     lines.push(`${indent}- **${s.name}**${kind}${s.description ? ` — ${s.description}` : ""}`);
+    if (s.prompt?.trim()) {
+        lines.push(`${indent}  - *the agent resolves here:*`);
+        for (const line of s.prompt.trim().split("\n"))
+            lines.push(`${indent}    > ${line}`);
+    }
     for (const t of s.transitions ?? []) {
         lines.push(`${indent}  - on \`${t.event}\` ${t.nextState ? `→ \`${t.nextState}\`` : "(internal)"}`);
     }
@@ -737,12 +752,13 @@ function buildServer() {
             ],
         };
     });
-    server.tool("add_state", "Add a state to the state machine. Parent defaults to Root.", {
+    server.tool("add_state", "Add a state to the state machine. Parent defaults to Root. `prompt` is what an agent is asked to resolve while the machine is in this state (see set_prompt).", {
         name: z.string(),
         parent: z.string().optional(),
         kind: z.enum(["normal", "final", "history"]).optional(),
         description: z.string().optional(),
-    }, async ({ name, parent, kind, description }) => {
+        prompt: z.string().optional(),
+    }, async ({ name, parent, kind, description, prompt }) => {
         const def = readDef();
         if (!def)
             return {
@@ -758,15 +774,33 @@ function buildServer() {
             };
         if (!parentState.states)
             parentState.states = [];
-        parentState.states.push({ name, kind: kind ?? "normal", description });
+        const added = { name, kind: kind ?? "normal", description, ...(prompt?.trim() ? { prompt } : {}) };
+        parentState.states.push(added);
         writeDef(def);
         bridgeEmitPatch([
-            { op: "state.add", parent: parentName, state: { name, kind: kind ?? "normal", description } },
+            { op: "state.add", parent: parentName, state: { name, kind: kind ?? "normal", description, ...(added.prompt ? { prompt: added.prompt } : {}) } },
         ]);
         return {
             content: [{ type: "text", text: `Added state '${name}' under '${parentName}' (${kind ?? "normal"}).` }],
         };
     });
+    server.tool("set_prompt", "Say what an agent is asked to resolve while the machine is in a state: the instruction it receives when the state is entered — an opening message, the frame of every later turn. `description` says what the state is and notes are the conversation about it; the prompt is what to do in it. The text replaces what was there; an empty string clears it. Engines and code generation ignore it; get_definition and generate_rispec show it.", { state: z.string(), prompt: z.string() }, async ({ state, prompt }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        const target = findState(def.state, state);
+        if (!target)
+            return { content: [{ type: "text", text: `State '${state}' not found.` }], isError: true };
+        if (prompt.trim())
+            target.prompt = prompt;
+        else
+            delete target.prompt;
+        writeDef(def);
+        bridgeEmitPatch([{ op: "state.update", name: state, patch: { prompt: prompt.trim() ? prompt : "" } }]);
+        return {
+            content: [{ type: "text", text: prompt.trim() ? `Prompt set on '${state}' (${prompt.length} characters).` : `Prompt cleared on '${state}'.` }],
+        };
+    });
     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)

package/dist/system.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { writeFileAtomic } from "./atomicWrite.js";
 import { basename, dirname, join, resolve } from "path";
-import { RECONCILE_MODES, SYSTEM_ACTOR_KINDS, addActor, addMember, checkSystem, docKindOfPath, emptySystem, formatReplay, isSqdfPath, isSysdfPath, isSystemDefinition, machineName, membersByKind, parseFocus, parseMessageRef, reconcileModeOf, reconcileSystem, relativeMemberPath, removeActor, removeMember, renderMermaid, renderMermaidEr, renderMermaidSequence, replayScenario, resolveMemberPath, setReconcileMode, stateOfList, summarizeReconcile, summarizeSystem, updateMember, updateSystemSettings, } from "@miadi/stateloom-protocol";
+import { RECONCILE_MODES, SYSTEM_ACTOR_KINDS, addActor, addMember, checkSystem, docKindOfPath, emptySystem, formatReplay, isSqdfPath, isSysdfPath, isSystemDefinition, machineName, membersByKind, parseFocus, parseMessageRef, reconcileModeOf, reconcileSystem, relativeMemberPath, removeActor, removeMember, renderMermaid, renderMermaidEr, renderMermaidSequence, replayScenario, resolveMemberPath, setReconcileMode, stateOfList, summarizeReconcile, summarizeSystem, updateMember, updateSystemSettings, normalizeNotes } from "@miadi/stateloom-protocol";
 import { stampedOutputPath } from "@miadi/stateloom-cli/render";
 import { formatNotes } from "./erd.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
@@ -14,7 +14,7 @@ export function readSystem(path) {
     if (!existsSync(path))
         return null;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = normalizeNotes(JSON.parse(readFileSync(path, "utf8")));
         return isSystemDefinition(parsed) ? parsed : null;
     }
     catch {
@@ -76,7 +76,7 @@ function loadMember(host, path, absolute) {
     catch {
         return { path, kind, def: null, error: "it is not valid JSON" };
     }
-    const def = kind === "machine" ? (parsed?.stateMachine ?? parsed?.StateMachine ?? parsed) : parsed;
+    const def = normalizeNotes(kind === "machine" ? (parsed?.stateMachine ?? parsed?.StateMachine ?? parsed) : parsed);
     return { path, kind, def };
 }
 /** One line for set_project_file / get_project_file when the active document is a system. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
   "dependencies": {
     "@miadi/stateloom-cli": "^0.1.3",
     "@miadi/stateloom-client": "^0.1.3",
-    "@miadi/stateloom-protocol": "^0.1.9",
+    "@miadi/stateloom-protocol": "^0.1.11",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },