@miadi/stateloom-mcp 0.2.2 → 0.2.4

package/dist/erd.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The ERD half of the MCP server (Spec 80).
+ *
+ * The loom weaves one active document at a time, and the document's type is
+ * its extension: `.smdf.json` is a state machine, `.erdf.json` an
+ * entity-relationship definition. The tools here act on the active document
+ * when it is an ERDF; `create_erd` is the one that also moves the active
+ * document, because naming an ERD is how its first version is written.
+ *
+ * An ERD travels to the live canvas as a whole document (`emitFull`) — the
+ * granular PatchOp vocabulary is SMDF's, and an ERD is small enough that the
+ * whole of it is a reasonable unit of change.
+ *
+ * Everything that touches the server's own state comes in through `ErdHost`,
+ * so a test can register these tools on a bare McpServer over a temp directory.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type EntityRelationshipDefinition } from "@miadi/stateloom-protocol";
+export interface ErdHost {
+    /** The active document's absolute path. */
+    projectFile(): string;
+    /** Re-point the active document under set_project_file's guards. Returns the refusal, if any. */
+    switchTo(path: string): string | undefined;
+    /** Mirror the whole document to the live bridge room. Best-effort. */
+    emitFull(def: EntityRelationshipDefinition): void;
+    /** The refusal for a path outside the permitted document root, if any. */
+    outsideRoot(path: string): string | undefined;
+}
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function readErd(path: string): EntityRelationshipDefinition | null;
+/** One line for set_project_file / get_project_file when the active document is an ERDF. */
+export declare function erdSummary(path: string): string;
+export declare function erdGetDefinition(host: ErdHost): ToolResult;
+export declare function erdLoadDefinition(host: ErdHost, json: string): ToolResult;
+export declare function erdRender(host: ErdHost, opts: {
+    format?: string;
+    path?: string;
+    stamp?: boolean;
+}): ToolResult;
+export declare function registerErdTools(server: McpServer, host: ErdHost): void;
+export {};

package/dist/erd.js

@@ -0,0 +1,239 @@
+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, 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 });
+export function readErd(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isErdDefinition(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeErd(path, def) {
+    writeFileSync(path, JSON.stringify(def, null, 2) + "\n", "utf8");
+}
+/** One line for set_project_file / get_project_file when the active document is an ERDF. */
+export function erdSummary(path) {
+    const def = readErd(path);
+    if (def) {
+        return `existing ERD '${def.settings?.name ?? ""}' (${def.entities.length} entities, ${(def.relationships ?? []).length} relationships)`;
+    }
+    return existsSync(path)
+        ? "file exists but is not a readable ERD definition"
+        : "no file yet — create_erd or load_definition will write it";
+}
+const NOT_ERD = (path) => `The active document ${path} is not an ERD. Use create_erd, or set_project_file to a .erdf.json document.`;
+/** Read the active ERD, apply `edit`, persist, mirror, and report. Errors become tool errors. */
+function mutate(host, edit, report) {
+    const path = host.projectFile();
+    if (!isErdfPath(path))
+        return fail(NOT_ERD(path));
+    const def = readErd(path);
+    if (!def)
+        return fail(`No ERD at ${path}. Use create_erd first.`);
+    try {
+        const next = edit(def);
+        writeErd(path, next);
+        host.emitFull(next);
+        return ok(report(next));
+    }
+    catch (e) {
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+}
+// ─── The tools that answer by extension (called from server.ts) ──────
+export function erdGetDefinition(host) {
+    const def = readErd(host.projectFile());
+    return def ? ok(JSON.stringify(def, null, 2)) : fail(`No ERD at ${host.projectFile()}.`);
+}
+export function erdLoadDefinition(host, json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        return fail(`Invalid JSON: ${e}`);
+    }
+    if (!isErdDefinition(parsed)) {
+        return fail(`The active document ${host.projectFile()} is an ERD, and this JSON is not one (it needs an "entities" array and no "state"). ` +
+            `To load a state machine, set_project_file to a .smdf.json document first.`);
+    }
+    const def = { ...parsed, relationships: parsed.relationships ?? [] };
+    writeErd(host.projectFile(), def);
+    host.emitFull(def);
+    const errors = validateErd(def);
+    return ok(`Loaded ERD → ${host.projectFile()}: ${def.settings?.name ?? ""} (${def.entities.length} entities, ${def.relationships.length} relationships)` +
+        (errors.length ? `\n${formatErrors(errors)}` : ""));
+}
+export function erdRender(host, opts) {
+    const doc = host.projectFile();
+    const def = readErd(doc);
+    if (!def)
+        return fail(`No ERD at ${doc}.`);
+    const format = opts.format ?? "mermaid";
+    if (format !== "mermaid") {
+        return fail(`An ERD renders as mermaid only (asked for ${format}); svg and png are not drawn for an ERD yet.`);
+    }
+    if (opts.path) {
+        const denial = host.outsideRoot(opts.path);
+        if (denial)
+            return fail(denial);
+    }
+    // `.erd.mmd`, so a machine and an ERD that share a basename never overwrite each other.
+    const out = opts.path
+        ? resolve(opts.path)
+        : opts.stamp
+            ? stampedOutputPath(doc, def.settings?.name, "mermaid", new Date())
+            : resolve(doc).replace(/\.erdf\.json$/i, "") + ".erd.mmd";
+    const text = renderMermaidEr(def);
+    writeFileSync(out, text + "\n", "utf8");
+    return {
+        content: [
+            { type: "text", text: `Rendered ERD '${def.settings?.name ?? ""}' → ${out} (${text.length} bytes)` },
+            { type: "text", text },
+        ],
+    };
+}
+const formatErrors = (errors) => errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
+function readSmdf(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+        return def && typeof def === "object" && def.state ? def : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Tool registration ───────────────────────────────────────────────
+export function registerErdTools(server, host) {
+    server.tool("create_erd", "Create a new entity-relationship definition (.erdf.json) and make it the active document. An ERD is the sibling of a state machine: it describes the data the machines act on, once, for every machine that touches it. Without `path` it lands next to the active document as <name>.erdf.json. Refuses to replace an ERD that already has entities unless overwrite is true.", {
+        namespace: z.string(),
+        name: z.string(),
+        description: z.string().optional(),
+        path: z.string().optional(),
+        overwrite: z.boolean().optional(),
+    }, async ({ namespace, name, description, path, overwrite }) => {
+        const active = host.projectFile();
+        const target = resolve(path ?? (isErdfPath(active) ? active : join(dirname(active), `${name}.erdf.json`)));
+        if (!isErdfPath(target))
+            return fail(`An ERD document ends in .erdf.json (got '${target}').`);
+        const existing = readErd(target);
+        if (existing && existing.entities.length > 0 && !overwrite) {
+            return fail(`${target} already holds ERD '${existing.settings?.name ?? ""}' with ${existing.entities.length} entities. ` +
+                `Pass overwrite: true to replace it, or set_project_file to it to keep working on it.`);
+        }
+        if (target !== active) {
+            const denial = host.switchTo(target);
+            if (denial)
+                return fail(denial);
+        }
+        const def = emptyErd(namespace, name, description);
+        writeErd(target, def);
+        host.emitFull(def);
+        return ok(`Created ERD '${name}' in namespace '${namespace}' → ${target}. It is now the active document. Add entities next.`);
+    });
+    server.tool("add_entity", "Add an entity to the active ERD", { name: z.string(), description: z.string().optional() }, async ({ name, description }) => mutate(host, (def) => addEntity(def, { name, description }), () => `Added entity '${name}'.`));
+    server.tool("add_attribute", "Add an attribute to an entity of the active ERD. `key` is pk or uk; a foreign key is stated by `references` ('Entity' or 'Entity.attribute'), so one attribute can be both. `stateOf` names the state machine(s) whose current state this attribute stores — the link between the two diagrams.", {
+        entity: z.string(),
+        name: z.string(),
+        type: z.string(),
+        key: z.enum(["pk", "uk"]).optional(),
+        references: z.string().optional(),
+        nullable: z.boolean().optional(),
+        stateOf: z.union([z.string(), z.array(z.string())]).optional(),
+        description: z.string().optional(),
+    }, async ({ entity, ...attribute }) => mutate(host, (def) => addAttribute(def, entity, attribute), () => `Added attribute '${entity}.${attribute.name}' (${attribute.type}).`));
+    server.tool("add_relationship", "Add a relationship between two entities of the active ERD. Cardinality reads left to right: one `from` has many `to` is 1:N.", {
+        from: z.string(),
+        to: z.string(),
+        cardinality: z.enum(ERD_CARDINALITIES),
+        label: z.string().optional(),
+        description: z.string().optional(),
+    }, async (rel) => mutate(host, (def) => addRelationship(def, rel), () => `Added relationship ${rel.from} ${rel.cardinality} ${rel.to}${rel.label ? ` : ${rel.label}` : ""}.`));
+    server.tool("remove_entity", "Remove an entity from the active ERD, with every relationship that touches it. Attributes elsewhere that reference it are left in place; validate_erd names them.", { name: z.string() }, async ({ name }) => mutate(host, (def) => removeEntity(def, name), () => `Removed entity '${name}' and its relationships.`));
+    server.tool("remove_attribute", "Remove an attribute from an entity of the active ERD", { entity: z.string(), name: z.string() }, async ({ entity, name }) => mutate(host, (def) => removeAttribute(def, entity, name), () => `Removed attribute '${entity}.${name}'.`));
+    server.tool("remove_relationship", "Remove the relationship(s) written from one entity to another in the active ERD — only the one carrying `label` when a label is given.", { from: z.string(), to: z.string(), label: z.string().optional() }, async ({ from, to, label }) => mutate(host, (def) => removeRelationship(def, from, to, label), () => `Removed relationship ${from} → ${to}${label ? ` : ${label}` : ""}.`));
+    server.tool("validate_erd", "Validate the active ERD against rules E001–E005 (unique names, relationship ends, cardinality, references) and list what it holds", {}, async () => {
+        const path = host.projectFile();
+        if (!isErdfPath(path))
+            return fail(NOT_ERD(path));
+        const def = readErd(path);
+        if (!def)
+            return fail(`No ERD at ${path}. Use create_erd first.`);
+        const errors = validateErd(def);
+        const body = summarizeErd(def) || "(empty)";
+        return errors.length
+            ? fail(`${errors.length} problem(s) in '${def.settings?.name ?? ""}':\n${formatErrors(errors)}\n\n${body}`)
+            : ok(`ERD '${def.settings?.name ?? ""}' is valid.\n${body}`);
+    });
+    server.tool("check_links", "Check the names a state machine uses for its data against an ERD (rules L001–L004): the class of each object a guard reads a field of must be an entity, each <instance>.<field> in a guard must be an attribute of it, and an attribute's stateOf must point at a machine built with that entity. With no arguments: when the active document is an ERD, every .smdf.json beside it is checked; when it is a state machine, pass erd_path.", { erd_path: z.string().optional(), smdf_paths: z.array(z.string()).optional() }, async ({ erd_path, smdf_paths }) => {
+        const active = host.projectFile();
+        const erdPath = erd_path ? resolve(erd_path) : isErdfPath(active) ? active : undefined;
+        if (!erdPath) {
+            return fail(`The active document ${active} is a state machine — pass erd_path, the .erdf.json to check it against.`);
+        }
+        // The single active machine is one of possibly several, so its ERD's other
+        // stateOf names are not held against it; any other set is "the machines at hand".
+        let machinesAreTheSet = true;
+        let smdfPaths;
+        if (smdf_paths?.length) {
+            smdfPaths = smdf_paths.map((p) => resolve(p));
+        }
+        else if (!isErdfPath(active)) {
+            smdfPaths = [active];
+            machinesAreTheSet = false;
+        }
+        else {
+            const dir = dirname(erdPath);
+            smdfPaths = readdirSync(dir)
+                .filter((f) => f.toLowerCase().endsWith(".smdf.json"))
+                .sort()
+                .map((f) => join(dir, f));
+            if (smdfPaths.length === 0)
+                return fail(`No .smdf.json beside ${erdPath} — pass smdf_paths.`);
+        }
+        for (const p of [erdPath, ...smdfPaths]) {
+            const denial = host.outsideRoot(p);
+            if (denial)
+                return fail(denial);
+        }
+        const erd = readErd(erdPath);
+        if (!erd)
+            return fail(`No readable ERD at ${erdPath}.`);
+        const lines = [];
+        const names = [];
+        let problems = 0;
+        for (const p of smdfPaths) {
+            const smdf = readSmdf(p);
+            if (!smdf) {
+                lines.push(`${p}: not a readable state machine`);
+                problems += 1;
+                continue;
+            }
+            const name = smdf.settings?.name ?? p;
+            names.push(name);
+            const errors = checkLinks(smdf, erd);
+            problems += errors.length;
+            lines.push(errors.length ? `${name} (${p}):\n${formatErrors(errors)}` : `${name}: every name resolves`);
+        }
+        if (machinesAreTheSet) {
+            const errors = checkStateOf(erd, names);
+            problems += errors.length;
+            if (errors.length)
+                lines.push(formatErrors(errors));
+        }
+        const head = `Checked ${smdfPaths.length} machine(s) against ERD '${erd.settings?.name ?? ""}' (${erdPath}): ${problems} problem(s).`;
+        const text = `${head}\n${lines.join("\n")}`;
+        return problems ? fail(text) : ok(text);
+    });
+}

package/dist/server.d.ts

@@ -18,9 +18,16 @@
  *   - load_definition: Load a definition from JSON
  *   - list_states: List all states in the current definition
  *   - list_events: List all events in the current definition
- *   - set_project_file: Choose which .smdf.json path is the active document
+ *   - set_project_file: Choose which document is active (.smdf.json or .erdf.json)
  *   - get_project_file: Report the active document path and bridge status
  *
+ * ERD tools (Spec 80, ./erd.ts) — the active document's type is its extension:
+ *   - create_erd, add_entity, add_attribute, add_relationship
+ *   - remove_entity, remove_attribute, remove_relationship
+ *   - validate_erd, check_links
+ *   get_definition, load_definition and render_diagram answer for an ERD when
+ *   the active document is one.
+ *
  * Resources:
  *   - smcraft://definition — Current state machine definition
  *

package/dist/server.js

@@ -18,9 +18,16 @@
  *   - load_definition: Load a definition from JSON
  *   - list_states: List all states in the current definition
  *   - list_events: List all events in the current definition
- *   - set_project_file: Choose which .smdf.json path is the active document
+ *   - set_project_file: Choose which document is active (.smdf.json or .erdf.json)
  *   - get_project_file: Report the active document path and bridge status
  *
+ * ERD tools (Spec 80, ./erd.ts) — the active document's type is its extension:
+ *   - create_erd, add_entity, add_attribute, add_relationship
+ *   - remove_entity, remove_attribute, remove_relationship
+ *   - validate_erd, check_links
+ *   get_definition, load_definition and render_diagram answer for an ERD when
+ *   the active document is one.
+ *
  * Resources:
  *   - smcraft://definition — Current state machine definition
  *
@@ -36,11 +43,13 @@ import { z } from "zod";
 import { execFileSync, spawn } from "child_process";
 import { writeFileSync, readFileSync, mkdtempSync, rmSync, existsSync, statSync, realpathSync, } from "fs";
 import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
-import { envAlias } from "@miadi/stateloom-protocol";
+import { 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";
 // 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.
@@ -61,6 +70,9 @@ const canvasLink = (path) => `${CANVAS_URL}/?doc=${encodeURIComponent(path)}`;
 // .smdf.json document mid-session (the hub keys live rooms by this path).
 let PROJECT_FILE = resolve(envAlias("PROJECT_FILE") ?? "./statemachine.smdf.json");
 function readDef() {
+    // An ERD is not a machine; the state-machine tools see no definition there.
+    if (isErdfPath(PROJECT_FILE))
+        return null;
     if (!existsSync(PROJECT_FILE))
         return null;
     try {
@@ -74,6 +86,11 @@ function readDef() {
     }
 }
 function writeDef(def) {
+    // Never write a machine over an ERD: create_state_machine and load_definition
+    // write without reading first, so this is the one place that can refuse.
+    if (isErdfPath(PROJECT_FILE)) {
+        throw new Error(`The active document ${PROJECT_FILE} is an ERD. Use the ERD tools on it, or set_project_file to a .smdf.json document for a state machine.`);
+    }
     writeFileSync(PROJECT_FILE, JSON.stringify({ stateMachine: def }, null, 2), "utf8");
 }
 // ─── Optional real-time design bridge (env-gated, best-effort) ───────
@@ -192,6 +209,22 @@ function bridgeEmitFull(def) {
         /* best-effort */
     }
 }
+// What ./erd.ts needs of this server's state. Called at tool time, after the
+// guards further down this file are initialised.
+const erdHost = {
+    projectFile: () => PROJECT_FILE,
+    switchTo: (path) => {
+        const denial = denyProjectSwitch(path);
+        if (denial)
+            return denial;
+        PROJECT_FILE = path;
+        bindBridge(PROJECT_FILE);
+        joinBridge();
+        return undefined;
+    },
+    emitFull: (def) => bridgeEmitFull(def),
+    outsideRoot: (path) => outsideRoot(path),
+};
 function createEmpty(namespace, name) {
     return {
         settings: { namespace, name, asynchronous: false },
@@ -598,10 +631,27 @@ function glyph(direction) {
  * Every tool closes over module-level state (PROJECT_FILE, the bridge client),
  * so instances are interchangeable — building one is registration, not state.
  */
+/**
+ * The version a client sees in `serverInfo`, read from the manifest that npm
+ * actually shipped rather than typed in beside it. The literal here said 0.2.0
+ * while the package on the registry was 0.2.2 — two releases during which every
+ * agent that asked this server who it was got a confident wrong answer, and no
+ * test could catch it because the two numbers had no relationship to compare.
+ * Reading the manifest gives them one.
+ */
+const PACKAGE_VERSION = (() => {
+    try {
+        const manifest = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        return String(JSON.parse(readFileSync(manifest, "utf8")).version);
+    }
+    catch {
+        return "0.0.0-unknown";
+    }
+})();
 function buildServer() {
     const server = new McpServer({
         name: "stateloom-mcp",
-        version: "0.2.0",
+        version: PACKAGE_VERSION,
     });
     // 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 }) => {
@@ -731,7 +781,9 @@ function buildServer() {
         const code = generateViaSmcg(def, language);
         return { content: [{ type: "text", text: code }] };
     });
-    server.tool("get_definition", "Get the current state machine definition as JSON", {}, async () => {
+    server.tool("get_definition", "Get the current definition as JSON — the state machine, or the ERD when the active document is a .erdf.json", {}, async () => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdGetDefinition(erdHost);
         const def = readDef();
         if (!def)
             return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
@@ -739,7 +791,9 @@ function buildServer() {
             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 }) => {
+    server.tool("load_definition", "Load a definition from JSON into the active document — a state machine, or an ERD when the active document is a .erdf.json", { json: z.string() }, async ({ json }) => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdLoadDefinition(erdHost, json);
         try {
             const parsed = JSON.parse(json);
             const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
@@ -787,7 +841,7 @@ function buildServer() {
             return { content: [{ type: "text", text: "No events defined yet." }] };
         return { content: [{ type: "text", text: events.join("\n") }] };
     });
-    server.tool("set_project_file", "Choose the active document the loom weaves — two modalities. STANDALONE: any .smdf.json path. RELATIONAL: a chronicle address `miadi-chronicle://<episode>/<diagram>` resolving over $MIADI_CHRONICLE_ROOT to <episode-dir>/diagrams/<diagram>.smdf.json — an ambiguous episode number is a hard error naming the candidates. Disk persistence AND the live bridge room both re-point. A missing file is legitimate — naming it is how an episode's first diagram is created.", { path: z.string() }, async ({ path }) => {
+    server.tool("set_project_file", "Choose the active document the loom weaves — two modalities. STANDALONE: any .smdf.json path (a state machine) or .erdf.json path (an ERD — the ERD tools act on it). RELATIONAL: a chronicle address `miadi-chronicle://<episode>/<diagram>` resolving over $MIADI_CHRONICLE_ROOT to <episode-dir>/diagrams/<diagram>.smdf.json — an ambiguous episode number is a hard error naming the candidates. Disk persistence AND the live bridge room both re-point. A missing file is legitimate — naming it is how an episode's first diagram is created.", { path: z.string() }, async ({ path }) => {
         try {
             const r = resolveProjectSwitch(path, PROJECT_FILE);
             const denial = denyProjectSwitch(r.path);
@@ -799,11 +853,13 @@ function buildServer() {
                 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 summary = isErdfPath(PROJECT_FILE)
+                ? erdSummary(PROJECT_FILE)
+                : 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"})`
@@ -827,11 +883,13 @@ function buildServer() {
     });
     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 summary = isErdfPath(PROJECT_FILE)
+            ? erdSummary(PROJECT_FILE)
+            : 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)";
@@ -879,6 +937,8 @@ function buildServer() {
         stamp: z.boolean().optional(),
         open: z.boolean().optional(),
     }, async ({ format, path, scale, theme, stamp, open }) => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdRender(erdHost, { format, path, stamp });
         const def = readDef();
         if (!def)
             return {
@@ -945,6 +1005,7 @@ function buildServer() {
             };
         }
     });
+    registerErdTools(server, erdHost);
     // Resources
     server.resource("definition", "smcraft://definition", async () => {
         const def = readDef();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
   "repository": {
     "type": "git",
@@ -38,9 +38,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@miadi/stateloom-cli": "^0.1.2",
-    "@miadi/stateloom-client": "^0.1.1",
-    "@miadi/stateloom-protocol": "^0.1.3",
+    "@miadi/stateloom-cli": "^0.1.3",
+    "@miadi/stateloom-client": "^0.1.2",
+    "@miadi/stateloom-protocol": "^0.1.6",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },