@miadi/stateloom-mcp 0.2.5 → 0.2.6

package/README.md

@@ -116,8 +116,28 @@ outside the root. `generate_code` writes only to a temporary directory. Note tha
 | `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 |
+| `set_project_file` | Re-point the loom at another document mid-session — a `.smdf.json` or a `.erdf.json`; disk target and live room both move |
 | `get_project_file` | The active document path, whether it exists, and bridge status |
+| `get_notes` | Every note in the active document in one call — the diagram's own first, then each shape that has one |
+| `set_notes` | Save (or, with an empty string, clear) working notes on the diagram or on one state / entity. Kept in the document for whoever opens it next; ignored by engines and codegen |
+
+### Entity-relationship diagrams
+
+The same server designs the **data** beside the machines, in a sibling `.erdf.json`. The
+active document's type is its extension: while an ERD is active, `get_definition`,
+`load_definition` and `render_diagram` (mermaid `erDiagram`) answer for it, and the
+state-machine tools refuse to write a machine over it.
+
+| Tool | What it does |
+|---|---|
+| `create_erd` | Start an ERD beside the active document and make it the active one |
+| `add_entity` / `update_entity` / `remove_entity` | An entity, optionally `weak`; removing one takes its relationships with it |
+| `add_attribute` / `remove_attribute` | `type`, `key` (`pk` / `uk`), `references` (the foreign key), `nullable`, and `stateOf` — the state machine whose state this attribute stores |
+| `add_relationship` / `remove_relationship` | `1:1`, `1:N`, `N:1`, `N:M`, read left to right, with a verb as the label |
+| `validate_erd` | Rules E001–E005 |
+| `check_links` | Rules L001–L004: what a state machine names — an object's class, a field in a guard, a `stateOf` — that the ERD does not carry |
+
+Format and rules: [Spec 80 — ERDF](https://github.com/jgwill/smcraft/blob/main/rispecs/80-erdf-format.spec.md).
 
 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.
 

package/dist/erd.d.ts

@@ -43,5 +43,12 @@ export declare function erdRender(host: ErdHost, opts: {
     path?: string;
     stamp?: boolean;
 }): ToolResult;
+/** One block per note, the diagram's own first. What `get_notes` answers with for either document type. */
+export declare function formatNotes(name: string, path: string, entries: {
+    target: string | null;
+    notes: string;
+}[]): string;
+export declare function erdGetNotes(host: ErdHost): ToolResult;
+export declare function erdSetNotes(host: ErdHost, target: string | undefined, notes: string): ToolResult;
 export declare function registerErdTools(server: McpServer, host: ErdHost): void;
 export {};

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, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, summarizeErd, validateErd, } from "@miadi/stateloom-protocol";
+import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, collectNotes, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, updateErdSettings, summarizeErd, validateErd, } 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 });
@@ -101,6 +101,22 @@ export function erdRender(host, opts) {
         ],
     };
 }
+/** One block per note, the diagram's own first. What `get_notes` answers with for either document type. */
+export function formatNotes(name, path, entries) {
+    if (entries.length === 0)
+        return `No notes in '${name}' (${path}).`;
+    const blocks = entries.map((n) => `[${n.target ?? "diagram"}]\n${n.notes}`);
+    return `${entries.length} note(s) in '${name}' (${path}):\n\n${blocks.join("\n\n")}`;
+}
+export function erdGetNotes(host) {
+    const def = readErd(host.projectFile());
+    if (!def)
+        return fail(`No ERD at ${host.projectFile()}.`);
+    return ok(formatNotes(def.settings?.name ?? "", host.projectFile(), collectNotes(def)));
+}
+export function erdSetNotes(host, target, notes) {
+    return mutate(host, (def) => (target ? updateEntity(def, target, { notes }) : updateErdSettings(def, { notes })), () => `${notes.trim() ? "Saved" : "Cleared"} the notes on ${target ? `entity '${target}'` : "the diagram"}.`);
+}
 const formatErrors = (errors) => errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
 function readSmdf(path) {
     if (!existsSync(path))

package/dist/server.d.ts

@@ -25,6 +25,9 @@
  *   - create_erd, add_entity, update_entity, add_attribute, add_relationship
  *   - remove_entity, remove_attribute, remove_relationship
  *   - validate_erd, check_links
+ *
+ * Notes (either document type): set_notes, get_notes — what a person or an
+ * agent wrote down about the diagram or one of its shapes, saved in the file.
  *   get_definition, load_definition and render_diagram answer for an ERD when
  *   the active document is one.
  *

package/dist/server.js

@@ -25,6 +25,9 @@
  *   - create_erd, add_entity, update_entity, add_attribute, add_relationship
  *   - remove_entity, remove_attribute, remove_relationship
  *   - validate_erd, check_links
+ *
+ * Notes (either document type): set_notes, get_notes — what a person or an
+ * agent wrote down about the diagram or one of its shapes, saved in the file.
  *   get_definition, load_definition and render_diagram answer for an ERD when
  *   the active document is one.
  *
@@ -46,10 +49,10 @@ import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
-import { envAlias, isErdfPath, } from "@miadi/stateloom-protocol";
+import { collectNotes, envAlias, isErdfPath, } from "@miadi/stateloom-protocol";
 import { renderDiagramToFile, defaultOutputPath } from "@miadi/stateloom-cli/render";
 import { resolveProjectSwitch } from "./projectSwitch.js";
-import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdRender, } from "./erd.js";
+import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdRender, erdGetNotes, erdSetNotes, formatNotes, } from "./erd.js";
 // STATELOOM_* read first, SMCRAFT_* legacy twin honored — the live MCP
 // registration bakes SMCRAFT_PROJECT_FILE and must keep working (2026-07-27
 // rename brief). Resolved once at boot, like the direct reads they replace.
@@ -1006,6 +1009,42 @@ function buildServer() {
         }
     });
     registerErdTools(server, erdHost);
+    // Notes — the same two tools for either document type.
+    server.tool("set_notes", "Save working notes on the active diagram or on one of its shapes — what was said about it, an open question, a decision — so whoever opens the document next (a person or an agent) finds them. Omit `target` for the whole diagram; otherwise `target` is a state name (state machine) or an entity name (ERD). The text replaces what was there; an empty string clears it. Notes are kept in the document and are not part of the model: engines and code generation ignore them.", { target: z.string().optional(), notes: z.string() }, async ({ target, notes }) => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdSetNotes(erdHost, target, notes);
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const holder = target ? findState(def.state, target) : def.settings;
+        if (!holder)
+            return { content: [{ type: "text", text: `State '${target}' not found.` }], isError: true };
+        if (notes.trim())
+            holder.notes = notes;
+        else
+            delete holder.notes;
+        writeDef(def);
+        // "" is how an erased note travels; the far side removes the key.
+        const patch = { notes: notes.trim() ? notes : "" };
+        bridgeEmitPatch([target ? { op: "state.update", name: target, patch } : { op: "settings.update", patch }]);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${notes.trim() ? "Saved" : "Cleared"} the notes on ${target ? `state '${target}'` : "the diagram"}.`,
+                },
+            ],
+        };
+    });
+    server.tool("get_notes", "Read every note in the active document in one call — the diagram's own first, then each shape that has one. Read them before changing a diagram somebody else has been working on: they are where a person leaves what they were thinking.", {}, async () => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdGetNotes(erdHost);
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+        const entries = collectNotes(def);
+        return { content: [{ type: "text", text: formatNotes(def.settings.name, PROJECT_FILE, entries) }] };
+    });
     // Resources
     server.resource("definition", "smcraft://definition", async () => {
         const def = readDef();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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.2",
-    "@miadi/stateloom-protocol": "^0.1.7",
+    "@miadi/stateloom-protocol": "^0.1.8",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },