db-diagram-tool-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,21 @@
 # db-diagram-tool-mcp
 
-A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server
-(stdio) that lets MCP clients — **Claude Code** and **OpenAI Codex** — read your
-[DB Diagram Tool](https://github.com/kai-exnodes) diagrams: list them, and fetch a
-diagram's schema as JSON, DBML, or SQL DDL.
+A [Model Context Protocol](https://modelcontextprotocol.io) server (stdio) that
+lets MCP clients — **Claude Code** and **OpenAI Codex** — **read** your
+[DB Diagram Tool](https://github.com/kai-exnodes) diagrams (list them; fetch a
+schema as JSON, DBML, or SQL DDL) and, with a **write-scoped** token, **create and
+update** them from DBML.
 
 It talks to the DB Diagram Tool backend over its normal REST API, authenticated
-with a **Personal Access Token (PAT)**. It performs **only GET requests** — it can
-never modify your diagrams.
+with a **Personal Access Token (PAT)**. A **`read`** PAT can only read; the write
+tools require a **`write`** PAT. Writes merge into the live document like a
+collaborator typing (concurrent editors are never clobbered), and **deletions are
+never applied without your explicit confirmation** (see below).
 
 ## Tools
 
+**Read** (a `read` or `write` PAT):
+
 | Tool | Args | Returns |
 |------|------|---------|
 | `list_diagrams` | — | The diagrams your token can access (id, name, role, visibility, updated time). |
@@ -18,23 +23,39 @@ never modify your diagrams.
 | `get_diagram_dbml` | `id` | The diagram rendered as [DBML](https://dbml.dbdiagram.io) (dbdiagram.io text format). |
 | `get_diagram_sql` | `id`, `dialect?` (`postgres` \| `mysql`, default `postgres`) | Server-generated `CREATE TABLE` SQL DDL. |
 
+**Write** (a `write` PAT):
+
+| Tool | Args | Returns |
+|------|------|---------|
+| `create_diagram` | `name`, `dbml` | Creates a new diagram from DBML (you own it); returns the new id + an editor URL. |
+| `update_diagram` | `id`, `dbml`, `confirmDeletions?` | Merges the DBML into the live diagram. Additions/changes apply at once; **table/column deletions are withheld** and returned as `pendingDeletions` until you re-call with `confirmDeletions: true`. |
+
+> **Delete safety (two-call handshake).** If your DBML drops a table or column,
+> `update_diagram` applies nothing destructive and lists what *would* be deleted.
+> The agent shows you those, and only after you approve does it call again with
+> `confirmDeletions: true`. A paste that forgets a table can't silently destroy it.
+
 ## Requirements
 
 - **Node.js ≥ 18** (uses the built-in `fetch`).
 - A **Personal Access Token** for your DB Diagram Tool account (create one in the
-  app's Settings → Personal Access Tokens). It looks like `ddt_pat_…`.
+  app's Settings → Personal Access Tokens). It looks like `ddt_pat_…`. Choose the
+  **`write`** scope if you want the create/update tools; **`read`** is enough (and
+  safer) for read-only use.
 - The backend **origin** URL (e.g. `http://localhost:8090` for local dev, or your
   hosted instance).
 
 ## Configuration
 
-The server reads two environment variables (set them in your MCP client's server
+The server reads these environment variables (set them in your MCP client's server
 config, below):
 
 | Variable | Required | Example | Notes |
 |----------|----------|---------|-------|
 | `DDT_BASE_URL` | yes | `http://localhost:8090` | Backend **origin** only — scheme + host[:port], **no** `/api/v1` path. |
 | `DDT_PAT` | yes | `ddt_pat_abc123…` | Your personal access token. Treat it like a password. |
+| `DDT_WS_URL` | no | `wss://relay.example.com` | Relay WS origin for write-back. Defaults to `DDT_BASE_URL` with `http→ws` / `https→wss` — only set it when the realtime relay is on a different host than the REST API. |
+| `DDT_APP_URL` | no | `https://app.example.com` | Web app origin, used for the editor URL `create_diagram` returns. Defaults to `DDT_BASE_URL`. |
 
 ## Build
 
@@ -119,15 +140,31 @@ Once configured, ask your agent things like:
 - "List my DB Diagram Tool diagrams."
 - "Show the DBML for the diagram named _Blog_."
 - "Give me the Postgres DDL for diagram `<id>`."
+- "Create a diagram called _Orders_ from this DBML: …" *(write PAT)*
+- "Add a `status` column to `orders` in diagram `<id>`." *(write PAT)*
 
 ## Security
 
-- **Read-only.** Only GET endpoints are ever called.
-- Your PAT grants read access to your diagrams — store it like a password, prefer
-  `${DDT_PAT}` env expansion (Claude Code) over inlining, and never commit it.
+- **Scoped tokens.** A `read` PAT reaches only the four diagram-read endpoints; a
+  `write` PAT additionally creates/updates diagrams. Neither can read member
+  emails or comments, or manage tokens. Prefer `read` unless you want write-back.
+- **The PAT never touches the relay.** For a live write, the server exchanges the
+  write PAT for a short-lived (~120s), single-diagram `aud:"ws"` token and uses
+  *that* for the realtime handshake — a leaked handshake token can't act as a REST
+  session or reach another diagram.
+- **Deletions need your confirmation.** `update_diagram` never drops a table or
+  column on the first call — it reports `pendingDeletions` and applies them only
+  when you re-call with `confirmDeletions: true`.
+- Store your PAT like a password — prefer `${DDT_PAT}` env expansion (Claude Code)
+  over inlining, and never commit it.
 
 ## Notes
 
 - `diagramToDbml.ts` is ported verbatim from the web app
   (`db-diagram-tool-fe/src/lib/dbml/diagramToDbml.ts`); keep the two in sync.
-- Built against `@modelcontextprotocol/sdk` v1.30.
+- `src/core/` **vendors** the web app's DBML↔diagram + Yjs bridge modules verbatim
+  (only import paths rewritten). A drift-guard test (`src/core/vendored.drift.test.ts`)
+  fails if they diverge from the FE source — re-vendor and re-run the golden when
+  the FE changes.
+- Built against `@modelcontextprotocol/sdk` v1.30; write-back builds to REST
+  contract **v1.7.0** (`/pats/ws-token`, write-scoped PATs).

package/dist/client.js

@@ -1,7 +1,8 @@
 /**
- * Read-only REST client for the DB Diagram Tool backend (frozen REST contract;
- * same endpoints the web app uses). All requests are `Authorization: Bearer <pat>`
- * and hit `${baseUrl}/api/v1<path>`. Only GETs — this package never writes.
+ * REST client for the DB Diagram Tool backend (frozen REST contract; same
+ * endpoints the web app uses). Every request is `Authorization: Bearer <pat>` and
+ * hits `${baseUrl}/api/v1<path>`. Reads accept a read or write PAT; the write
+ * methods (create / update / ws-token — REST v1.7.0) require a WRITE-scoped PAT.
  */
 const API_PREFIX = "/api/v1";
 /** A structured API error carrying the HTTP status + the backend's error message. */
@@ -15,21 +16,37 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
+/** A short remediation hint appended to an error message, by status / scope. */
+function hintFor(status, code) {
+    if (code === "insufficient_scope")
+        return " (this token can't do that — create / update needs a WRITE-scoped PAT)";
+    if (status === 401)
+        return " (check DDT_PAT — the token may be invalid or expired)";
+    if (status === 403)
+        return " (the token lacks access to this diagram)";
+    if (status === 404)
+        return " (no such diagram, or it isn't shared with this token)";
+    return "";
+}
 export class DdtClient {
     config;
     constructor(config) {
         this.config = config;
     }
-    async get(path) {
+    async request(method, path, body) {
         const url = `${this.config.baseUrl}${API_PREFIX}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.config.pat}`,
+            Accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
         let res;
         try {
-            res = await fetch(url, {
-                headers: {
-                    Authorization: `Bearer ${this.config.pat}`,
-                    Accept: "application/json",
-                },
-            });
+            res = await fetch(url, init);
         }
         catch (e) {
             throw new ApiError(0, `could not reach the backend at ${this.config.baseUrl} (${e.message}). Check DDT_BASE_URL and that the server is running.`);
@@ -37,21 +54,20 @@ export class DdtClient {
         const isJson = res.headers
             .get("content-type")
             ?.includes("application/json");
-        const payload = isJson ? await res.json().catch(() => undefined) : undefined;
+        const payload = isJson
+            ? await res.json().catch(() => undefined)
+            : undefined;
         if (!res.ok) {
             const env = payload;
+            const code = env?.error?.code;
             const message = env?.error?.message ?? env?.message ?? res.statusText ?? "request failed";
-            const hint = res.status === 401
-                ? " (check DDT_PAT — the token may be invalid or expired)"
-                : res.status === 403
-                    ? " (the token lacks access to this diagram)"
-                    : res.status === 404
-                        ? " (no such diagram, or it isn't shared with this token)"
-                        : "";
-            throw new ApiError(res.status, `${res.status} ${message}${hint}`, env?.error?.code);
+            throw new ApiError(res.status, `${res.status} ${message}${hintFor(res.status, code)}`, code);
         }
         return payload;
     }
+    get(path) {
+        return this.request("GET", path);
+    }
     /** GET /diagrams → the token's accessible diagrams. */
     listDiagrams() {
         return this.get("/diagrams");
@@ -68,4 +84,23 @@ export class DdtClient {
     getDdl(id, dialect) {
         return this.get(`/diagrams/${encodeURIComponent(id)}/export/ddl?dialect=${encodeURIComponent(dialect)}`);
     }
+    // --- writes (REST v1.7.0; require a WRITE-scoped PAT) ---
+    /** POST /diagrams { name } → the created diagram's metadata (owner = token owner). */
+    createDiagram(name) {
+        return this.request("POST", "/diagrams", { name });
+    }
+    /** PUT /diagrams/{id}/snapshot — durable save of the full Diagram JSON (editor+). */
+    putSnapshot(id, diagram) {
+        return this.request("PUT", `/diagrams/${encodeURIComponent(id)}/snapshot`, diagram);
+    }
+    /**
+     * POST /pats/ws-token { diagramId } → a short-lived `aud:"ws"` JWT bound to the
+     * diagram, for the relay handshake (editor+). The raw PAT is never sent to the
+     * relay; this scoped token is (§8 of the PAT contract).
+     */
+    mintWsToken(id) {
+        return this.request("POST", "/pats/ws-token", {
+            diagramId: id,
+        });
+    }
 }

package/dist/config.js

@@ -13,5 +13,11 @@ export function loadConfig(env = process.env) {
             missing.map((m) => `  - ${m}`).join("\n") +
             `\nSet them in your MCP client's server config (see the README).`);
     }
-    return { baseUrl, pat };
+    // WS origin: explicit override, else the REST origin with the scheme swapped
+    // (http→ws, https→wss) — same host/port in the common single-origin dev setup.
+    const wsOverride = (env.DDT_WS_URL ?? "").trim().replace(/\/+$/, "");
+    const wsUrl = wsOverride || baseUrl.replace(/^http(s?):\/\//, "ws$1://");
+    // App origin for the editor URL; defaults to the REST origin (same in dev).
+    const appUrl = (env.DDT_APP_URL ?? "").trim().replace(/\/+$/, "") || baseUrl;
+    return { baseUrl, wsUrl, appUrl, pat };
 }

package/dist/core/apply.js

@@ -0,0 +1,126 @@
+// --- canonical structural views (ignore ids + positions) ---
+function tableCanon(t) {
+    return JSON.stringify({
+        note: t.note ?? null,
+        columns: t.columns.map((c) => ({
+            name: c.name,
+            type: c.type,
+            pk: c.isPrimaryKey,
+            fk: c.isForeignKey,
+            nn: !c.isNullable,
+            uq: c.isUnique,
+            def: c.default ?? null,
+            note: c.note ?? null,
+        })),
+    });
+}
+/** Name-based relationship strings incident to each table (so a cardinality/FK
+ * edit shows the two touched tables as "changed"). */
+function incidentRels(d) {
+    const tName = new Map(d.tables.map((t) => [t.id, t.name]));
+    const cName = new Map(d.tables.flatMap((t) => t.columns.map((c) => [c.id, c.name])));
+    const out = new Map();
+    for (const r of d.relationships) {
+        const ft = tName.get(r.fromTableId);
+        const tt = tName.get(r.toTableId);
+        const s = `${ft}.${cName.get(r.fromColumnId)} ${r.cardinality} ${tt}.${cName.get(r.toColumnId)}`;
+        for (const n of [ft, tt]) {
+            if (!n)
+                continue;
+            const list = out.get(n) ?? [];
+            list.push(s);
+            out.set(n, list);
+        }
+    }
+    for (const list of out.values())
+        list.sort();
+    return out;
+}
+/**
+ * Structural diff between the current canvas and the parsed DBML, matched by table
+ * NAME. `removedTables` feeds the destructive-apply confirm; `unchanged` gates the
+ * Apply button.
+ */
+export function dbmlDiff(current, next) {
+    const curNames = new Set(current.tables.map((t) => t.name));
+    const nextNames = new Set(next.tables.map((t) => t.name));
+    const addedTables = [...nextNames].filter((n) => !curNames.has(n));
+    const removedTables = [...curNames].filter((n) => !nextNames.has(n));
+    const curCanon = new Map(current.tables.map((t) => [t.name, tableCanon(t)]));
+    const nextCanon = new Map(next.tables.map((t) => [t.name, tableCanon(t)]));
+    const curRels = incidentRels(current);
+    const nextRels = incidentRels(next);
+    const changedTables = [];
+    for (const name of curNames) {
+        if (!nextNames.has(name))
+            continue;
+        const structDiff = curCanon.get(name) !== nextCanon.get(name);
+        const relDiff = JSON.stringify(curRels.get(name) ?? []) !==
+            JSON.stringify(nextRels.get(name) ?? []);
+        if (structDiff || relDiff)
+            changedTables.push(name);
+    }
+    const unchanged = addedTables.length === 0 &&
+        removedTables.length === 0 &&
+        changedTables.length === 0;
+    return {
+        addedTables: addedTables.sort(),
+        removedTables: removedTables.sort(),
+        changedTables: changedTables.sort(),
+        unchanged,
+    };
+}
+// Rough table footprint for staging math (self-refines once React Flow measures).
+const EST_W = 240;
+const GUTTER = 64;
+const COL_GAP = 40;
+const ROW_GAP = 40;
+const estHeight = (t) => 44 + t.columns.length * 28;
+function bbox(tables) {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const t of tables) {
+        minX = Math.min(minX, t.position.x);
+        minY = Math.min(minY, t.position.y);
+        maxX = Math.max(maxX, t.position.x + EST_W);
+        maxY = Math.max(maxY, t.position.y + estHeight(t));
+    }
+    return { minX, minY, maxX, maxY, height: maxY - minY };
+}
+/** Stage new tables in a column past the preserved bounding box's right edge,
+ * stacking vertically (in DBML order) and wrapping into further columns when the
+ * stack grows taller than the box — guarantees no overlap with preserved OR among
+ * new tables. Mutates `newTables[].position`. */
+function stageNewTables(preserved, newTables) {
+    const box = bbox(preserved);
+    const startX = box.maxX + GUTTER;
+    let x = startX;
+    let y = box.minY;
+    for (const t of newTables) {
+        if (y > box.minY && y + estHeight(t) > box.minY + box.height) {
+            x += EST_W + COL_GAP; // wrap to the next staging column
+            y = box.minY;
+        }
+        t.position = { x, y };
+        y += estHeight(t) + ROW_GAP;
+    }
+}
+/**
+ * Build the apply plan: carry each table's position from the current canvas by
+ * NAME, stage new tables to the side, and flag the all-new case for the caller.
+ */
+export function planApply(next, current) {
+    const curPos = new Map(current.tables.map((t) => [t.name, t.position]));
+    const newTables = [];
+    for (const t of next.tables) {
+        const pos = curPos.get(t.name);
+        if (pos)
+            t.position = { ...pos };
+        else
+            newTables.push(t);
+    }
+    const preserved = next.tables.filter((t) => !newTables.includes(t));
+    const allNew = preserved.length === 0;
+    if (!allNew && newTables.length > 0)
+        stageNewTables(preserved, newTables);
+    return { diagram: next, newTableNames: newTables.map((t) => t.name), allNew };
+}

package/dist/core/ops.js

@@ -0,0 +1,99 @@
+import * as Y from "yjs";
+import { columnToY, relToY, tableToY } from "./snapshot.js";
+export function applyIncremental(doc, change) {
+    doc.transact(() => {
+        const tables = doc.getArray("tables");
+        const rels = doc.getArray("relationships");
+        const tableById = new Map();
+        for (let i = 0; i < tables.length; i++) {
+            const m = tables.get(i);
+            tableById.set(str(m.get("id")), m);
+        }
+        // 1. modify existing tables in place (patch fields + upsert columns).
+        for (const t of change.modify ?? []) {
+            const m = tableById.get(t.id);
+            if (!m)
+                continue; // gone in a merge race — nothing to patch
+            m.set("name", t.name);
+            setOrDelete(m, "note", nonEmpty(t.note) ? t.note : undefined);
+            upsertColumns(m, t);
+        }
+        // 2. append new tables + relationships.
+        if (change.add?.length)
+            tables.push(change.add.map(tableToY));
+        if (change.addRelationships?.length) {
+            rels.push(change.addRelationships.map(relToY));
+        }
+        // 3. confirmed removals (columns first, then tables, then relationships).
+        const rm = change.remove;
+        if (rm) {
+            for (const { tableId, columnId } of rm.columns ?? []) {
+                const m = tableById.get(tableId);
+                if (m)
+                    removeColumn(m, columnId);
+            }
+            if (rm.tables?.length)
+                deleteByIds(tables, new Set(rm.tables));
+            if (rm.relationships?.length) {
+                deleteByIds(rels, new Set(rm.relationships));
+            }
+        }
+    });
+}
+// --- helpers ---
+function upsertColumns(tableMap, table) {
+    let cols = tableMap.get("columns");
+    if (!cols) {
+        cols = new Y.Array();
+        tableMap.set("columns", cols);
+    }
+    const liveById = new Map();
+    for (let i = 0; i < cols.length; i++) {
+        const cm = cols.get(i);
+        liveById.set(str(cm.get("id")), cm);
+    }
+    for (const c of table.columns) {
+        const existing = liveById.get(c.id);
+        if (existing)
+            patchColumn(existing, c);
+        else
+            cols.push([columnToY(c)]);
+    }
+}
+function patchColumn(m, c) {
+    m.set("name", c.name);
+    m.set("type", c.type);
+    m.set("isPrimaryKey", c.isPrimaryKey);
+    m.set("isForeignKey", c.isForeignKey);
+    m.set("isNullable", c.isNullable);
+    m.set("isUnique", c.isUnique);
+    setOrDelete(m, "default", nonEmpty(c.default) ? c.default : undefined);
+    setOrDelete(m, "note", nonEmpty(c.note) ? c.note : undefined);
+}
+function removeColumn(tableMap, columnId) {
+    const cols = tableMap.get("columns");
+    if (!cols)
+        return;
+    for (let i = cols.length - 1; i >= 0; i--) {
+        if (str(cols.get(i).get("id")) === columnId)
+            cols.delete(i, 1);
+    }
+}
+function deleteByIds(arr, ids) {
+    for (let i = arr.length - 1; i >= 0; i--) {
+        if (ids.has(str(arr.get(i).get("id"))))
+            arr.delete(i, 1);
+    }
+}
+function setOrDelete(m, key, value) {
+    if (value !== undefined)
+        m.set(key, value);
+    else if (m.has(key))
+        m.delete(key);
+}
+function nonEmpty(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function str(v) {
+    return typeof v === "string" ? v : "";
+}

package/dist/core/seed.js

@@ -0,0 +1,58 @@
+import * as Y from "yjs";
+import { hydrate } from "./snapshot.js";
+/**
+ * Deterministic doc seeding (M6).
+ *
+ * The WebSocket relay is doc-less and never materializes CRDT content (contract
+ * 3 §5), so the FE — not the server — owns seeding a diagram's initial content
+ * from its REST snapshot. Naively hydrating a live doc on every client would
+ * UNION-duplicate tables, because each client's Y items get distinct
+ * `(clientID, clock)` ids.
+ *
+ * Fix: build the seed in a throwaway doc pinned to a RESERVED clientID, so any
+ * two clients seeding the SAME snapshot produce items with IDENTICAL ids →
+ * Yjs merge is idempotent and never duplicates, even on a concurrent cold-open
+ * or when the relay replays the seed from its log. Real edits afterward use the
+ * live doc's own (random) clientID and merge normally on top.
+ */
+/** Reserved clientID for the deterministic seed (see module doc). */
+export const SEED_CLIENT_ID = 0;
+/** A deterministic Yjs update that reproduces the snapshot's content. */
+export function seedUpdate(diagram) {
+    const seed = new Y.Doc();
+    seed.clientID = SEED_CLIENT_ID;
+    // Match the live doc containers so encoded items address the same shared types.
+    seed.getMap("meta");
+    seed.getArray("tables");
+    seed.getArray("relationships");
+    hydrate(seed, diagram);
+    return Y.encodeStateAsUpdate(seed);
+}
+/**
+ * Seed a live doc from the snapshot.
+ *
+ * The reserved-clientID trick makes this idempotent against ANOTHER deterministic
+ * seed. It does NOT protect against the relay's log when that log was produced by
+ * the doc's REAL edits (random clientID): the snapshot's tables and the relay's
+ * originals then have the same `id` field but distinct Yjs item identity, so
+ * merging both UNION-DUPLICATES every table. An already-collaborated diagram's
+ * relay carries exactly such random-clientID items — so DO NOT seed eagerly on
+ * open; gate on the relay being empty (see `seedIfEmpty` + useCollab).
+ */
+export function seedDiagram(doc, diagram) {
+    Y.applyUpdate(doc, seedUpdate(diagram));
+}
+/**
+ * Relay-empty seed gate. Seed from the snapshot ONLY when the doc still has no
+ * tables — i.e. the relay delivered no state (a brand-new diagram). For a doc the
+ * relay already populated, the relay is authoritative and seeding on top would
+ * union-duplicate every table (see `seedDiagram`). Returns whether it seeded.
+ * Call this AFTER the provider's first sync (or an offline-fallback timeout), not
+ * eagerly on open.
+ */
+export function seedIfEmpty(doc, diagram) {
+    if (doc.getArray("tables").length > 0)
+        return false;
+    seedDiagram(doc, diagram);
+    return true;
+}

package/dist/core/snapshot.js

@@ -0,0 +1,145 @@
+import * as Y from "yjs";
+import { SCHEMA_VERSION, } from "./types/diagram.js";
+/**
+ * Yjs ↔ snapshot bridge.
+ *
+ * The Y.Doc is the live collaborative editing document; the contract-1 Diagram
+ * is the durable snapshot. `materialize` produces a CLEAN field-by-field
+ * projection — only contract keys, columns in array order — so it passes BE's
+ * closed-object PUT validation and never leaks transient UI state (D5).
+ * `hydrate` rebuilds the doc from a snapshot (e.g. on open / import).
+ *
+ * Doc shape: meta (Y.Map: id, name) · tables (Y.Array<Y.Map>) ·
+ * relationships (Y.Array<Y.Map>). A table's position is a nested Y.Map {x,y}
+ * and its columns a Y.Array<Y.Map> (order preserved → composite-PK order, D6).
+ */
+// ---------------------------------------------------------------------------
+// hydrate: Diagram → Y.Doc
+// ---------------------------------------------------------------------------
+export function hydrate(doc, diagram) {
+    doc.transact(() => {
+        const meta = doc.getMap("meta");
+        meta.set("id", diagram.id);
+        meta.set("name", diagram.name);
+        const tables = doc.getArray("tables");
+        tables.delete(0, tables.length);
+        tables.push(diagram.tables.map(tableToY));
+        const rels = doc.getArray("relationships");
+        rels.delete(0, rels.length);
+        rels.push(diagram.relationships.map(relToY));
+    });
+}
+export function tableToY(t) {
+    const m = new Y.Map();
+    m.set("id", t.id);
+    m.set("name", t.name);
+    const pos = new Y.Map();
+    pos.set("x", t.position.x);
+    pos.set("y", t.position.y);
+    m.set("position", pos);
+    if (nonEmpty(t.note))
+        m.set("note", t.note);
+    const cols = new Y.Array();
+    cols.push(t.columns.map(columnToY));
+    m.set("columns", cols);
+    return m;
+}
+export function columnToY(c) {
+    const m = new Y.Map();
+    m.set("id", c.id);
+    m.set("name", c.name);
+    m.set("type", c.type);
+    m.set("isPrimaryKey", c.isPrimaryKey);
+    m.set("isForeignKey", c.isForeignKey);
+    m.set("isNullable", c.isNullable);
+    m.set("isUnique", c.isUnique);
+    if (nonEmpty(c.default))
+        m.set("default", c.default);
+    if (nonEmpty(c.note))
+        m.set("note", c.note);
+    return m;
+}
+export function relToY(r) {
+    const m = new Y.Map();
+    m.set("id", r.id);
+    m.set("fromTableId", r.fromTableId);
+    m.set("fromColumnId", r.fromColumnId);
+    m.set("toTableId", r.toTableId);
+    m.set("toColumnId", r.toColumnId);
+    m.set("cardinality", r.cardinality);
+    return m;
+}
+// ---------------------------------------------------------------------------
+// materialize: Y.Doc → Diagram (clean projection)
+// ---------------------------------------------------------------------------
+export function materialize(doc) {
+    const meta = doc.getMap("meta");
+    const tables = doc.getArray("tables");
+    const rels = doc.getArray("relationships");
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        id: str(meta.get("id")),
+        name: str(meta.get("name")),
+        tables: tables.map(yToTable),
+        relationships: rels.map(yToRelationship),
+    };
+}
+function yToTable(m) {
+    const cols = m.get("columns");
+    const table = {
+        id: str(m.get("id")),
+        name: str(m.get("name")),
+        position: yToPosition(m.get("position")),
+        columns: cols ? cols.map(yToColumn) : [],
+    };
+    const note = m.get("note");
+    if (nonEmpty(note))
+        table.note = note;
+    return table;
+}
+export function yToColumn(m) {
+    const col = {
+        id: str(m.get("id")),
+        name: str(m.get("name")),
+        type: str(m.get("type")),
+        isPrimaryKey: bool(m.get("isPrimaryKey")),
+        isForeignKey: bool(m.get("isForeignKey")),
+        isNullable: bool(m.get("isNullable")),
+        isUnique: bool(m.get("isUnique")),
+    };
+    const def = m.get("default");
+    if (nonEmpty(def))
+        col.default = def;
+    const note = m.get("note");
+    if (nonEmpty(note))
+        col.note = note;
+    return col;
+}
+function yToRelationship(m) {
+    return {
+        id: str(m.get("id")),
+        fromTableId: str(m.get("fromTableId")),
+        fromColumnId: str(m.get("fromColumnId")),
+        toTableId: str(m.get("toTableId")),
+        toColumnId: str(m.get("toColumnId")),
+        cardinality: m.get("cardinality") ?? "1:N",
+    };
+}
+function yToPosition(pos) {
+    return { x: num(pos?.get("x")), y: num(pos?.get("y")) };
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function nonEmpty(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function str(v) {
+    return typeof v === "string" ? v : "";
+}
+function bool(v) {
+    return v === true;
+}
+function num(v) {
+    return typeof v === "number" ? v : 0;
+}

package/dist/core/types/diagram.js

@@ -0,0 +1,9 @@
+/**
+ * Contract-1 typed models — the canonical Diagram document.
+ *
+ * Mirrors the FROZEN Diagram JSON schema v1.0.0
+ * (docs/contracts/diagram.schema.json @ a60549f). Every object is CLOSED in the
+ * contract (additionalProperties:false) — the materializer must emit ONLY these
+ * keys, or BE's snapshot PUT validation rejects the save.
+ */
+export const SCHEMA_VERSION = "1.0";

package/dist/core/uuid.js

@@ -0,0 +1,33 @@
+/**
+ * UUID v4 that works in ANY browser context.
+ *
+ * `crypto.randomUUID()` exists only in a SECURE context (HTTPS or localhost).
+ * When the app is opened from another device on the LAN over plain HTTP (e.g.
+ * `http://192.168.1.6:3000`), that origin is NOT a secure context, so
+ * `crypto.randomUUID` is `undefined` and calling it throws. `crypto.getRandomValues`,
+ * by contrast, IS available in non-secure contexts — so we fall back to building
+ * an RFC 4122 v4 UUID from it. This keeps table/column/guest id generation (and
+ * therefore the editor + realtime collab) working for LAN visitors.
+ */
+export function randomUUID() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function") {
+        return c.randomUUID();
+    }
+    const b = new Uint8Array(16);
+    c.getRandomValues(b);
+    b[6] = (b[6] & 0x0f) | 0x40; // version 4
+    b[8] = (b[8] & 0x3f) | 0x80; // variant 10xx
+    const hex = [];
+    for (let i = 0; i < 16; i++)
+        hex.push(b[i].toString(16).padStart(2, "0"));
+    return (hex.slice(0, 4).join("") +
+        "-" +
+        hex.slice(4, 6).join("") +
+        "-" +
+        hex.slice(6, 8).join("") +
+        "-" +
+        hex.slice(8, 10).join("") +
+        "-" +
+        hex.slice(10, 16).join(""));
+}

package/dist/index.js

@@ -5,16 +5,19 @@ import { z } from "zod";
 import { loadConfig } from "./config.js";
 import { ApiError, DdtClient } from "./client.js";
 import { diagramToDbml } from "./diagramToDbml.js";
+import { withRoom } from "./relayPeer.js";
+import { DbmlError, createDiagram as runCreateDiagram, updateDiagram as runUpdateDiagram, } from "./writeback.js";
 /**
- * db-diagram-tool-mcp — a read-only stdio MCP server exposing your DB Diagram Tool
- * diagrams to MCP clients (Claude Code, Codex). Four tools: list_diagrams,
- * get_diagram (schema JSON), get_diagram_dbml, get_diagram_sql. Auth is a PAT.
+ * db-diagram-tool-mcp — a stdio MCP server exposing your DB Diagram Tool diagrams
+ * to MCP clients (Claude Code, Codex). Read tools: list_diagrams, get_diagram
+ * (schema JSON), get_diagram_dbml, get_diagram_sql. Write tools (a WRITE-scoped
+ * PAT): create_diagram, update_diagram. Auth is a PAT.
  *
  * stdio protocol note: stdout is the JSON-RPC channel — NEVER write to stdout.
  * All diagnostics go to stderr.
  */
 const SERVER_NAME = "db-diagram-tool";
-const SERVER_VERSION = "0.1.0";
+const SERVER_VERSION = "0.2.0";
 /** A successful text result. */
 function text(body) {
     return { content: [{ type: "text", text: body }] };
@@ -22,19 +25,41 @@ function text(body) {
 /** A tool-level error result (isError so the client shows it as a failure, but the
  * server keeps running for the next call). */
 function errorResult(e) {
-    const msg = e instanceof ApiError
-        ? e.message
-        : e instanceof Error
-            ? e.message
-            : String(e);
+    let msg;
+    if (e instanceof DbmlError) {
+        const at = e.detail.line != null
+            ? ` at line ${e.detail.line}${e.detail.column != null ? `, column ${e.detail.column}` : ""}`
+            : "";
+        msg = `DBML parse error${at}: ${e.detail.message}`;
+    }
+    else if (e instanceof ApiError || e instanceof Error) {
+        msg = e.message;
+    }
+    else {
+        msg = String(e);
+    }
     return {
         content: [{ type: "text", text: `Error: ${msg}` }],
         isError: true,
     };
 }
-function buildServer(client) {
+function buildServer(client, config) {
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
     const readOnly = { readOnlyHint: true, openWorldHint: true };
+    // Write-back wiring (Approach C): create is REST-only; update mints a scoped
+    // ws-token and joins the relay room as a live peer to merge the edit.
+    const writeback = {
+        createDiagram: (name) => client.createDiagram(name),
+        getSnapshot: (id) => client.getSnapshot(id),
+        putSnapshot: (id, diagram) => client.putSnapshot(id, diagram),
+        mintWsToken: (id) => client.mintWsToken(id),
+        runInRoom: (id, wsToken, fn) => withRoom({
+            wsUrl: config.wsUrl,
+            getSnapshot: (i) => client.getSnapshot(i),
+            putSnapshot: (i, d) => client.putSnapshot(i, d),
+        }, id, wsToken, fn),
+        appUrl: config.appUrl,
+    };
     server.registerTool("list_diagrams", {
         title: "List diagrams",
         description: "List the DB Diagram Tool diagrams this token can access. Returns id, name, your role, visibility, and last-updated time for each. Use an id with the other tools.",
@@ -120,12 +145,84 @@ function buildServer(client) {
             return errorResult(e);
         }
     });
+    // --- write tools (require a WRITE-scoped PAT) ---
+    server.registerTool("create_diagram", {
+        title: "Create diagram (from DBML)",
+        description: "Create a NEW diagram from DBML (the dbdiagram.io text format: Table/Ref blocks). Parses the DBML, creates the diagram (you become its owner), lays the tables out on a simple grid, and saves the schema. Returns the new diagram id and an editor URL to open it. Requires a WRITE-scoped Personal Access Token. Unmodeled DBML features (enums, TableGroups, secondary indexes, referential actions) are ignored and reported as warnings — everything else (tables, columns with types/keys/nullability, and relationships) is created.",
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe("A name for the new diagram (shown in the dashboard)."),
+            dbml: z
+                .string()
+                .min(1)
+                .describe("The schema as DBML — Table blocks and Ref relationships."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async ({ name, dbml }) => {
+        try {
+            const res = await runCreateDiagram(writeback, { name, dbml });
+            const lines = [`Created diagram "${name}".`, `id: ${res.id}`, `Open: ${res.url}`];
+            if (res.warnings.length) {
+                lines.push("", "Warnings:", ...res.warnings.map((w) => `- ${w}`));
+            }
+            return text(lines.join("\n"));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.registerTool("update_diagram", {
+        title: "Update diagram (from DBML)",
+        description: "Update an existing diagram's schema from DBML by MERGING your changes into the live document — concurrent editors are preserved (nothing is clobbered). Additions and modifications (new tables, new/changed columns, new relationships) apply immediately. IMPORTANT — deletions are gated: if the DBML drops any table or column, the tool applies NOTHING destructive and returns them under `pendingDeletions`. You MUST show the user exactly what would be deleted and, ONLY after they explicitly approve, call update_diagram AGAIN with the SAME `dbml` and `confirmDeletions: true` to apply the deletions. Never pass confirmDeletions: true on the first call. Requires a WRITE-scoped Personal Access Token.",
+        inputSchema: {
+            id: z.string().min(1).describe("The diagram id to update (from list_diagrams)."),
+            dbml: z
+                .string()
+                .min(1)
+                .describe("The intended schema as DBML; diffed against the live diagram."),
+            confirmDeletions: z
+                .boolean()
+                .optional()
+                .describe("Set true ONLY on a second call, after the user approved the pendingDeletions from a prior call, to apply table/column removals."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, async ({ id, dbml, confirmDeletions }) => {
+        try {
+            const res = await runUpdateDiagram(writeback, { id, dbml, confirmDeletions });
+            const { addedTables, modifiedTables } = res.applied;
+            const lines = [];
+            if (addedTables.length)
+                lines.push(`Added tables: ${addedTables.join(", ")}`);
+            if (modifiedTables.length)
+                lines.push(`Modified tables: ${modifiedTables.join(", ")}`);
+            if (!lines.length && !res.pendingDeletions)
+                lines.push("No changes to apply.");
+            if (res.pendingDeletions) {
+                const { tables, columns } = res.pendingDeletions;
+                lines.push("", "⚠️ PENDING DELETIONS — NOT applied (awaiting your confirmation):");
+                if (tables.length)
+                    lines.push(`  tables: ${tables.join(", ")}`);
+                if (columns.length)
+                    lines.push(`  columns: ${columns.join(", ")}`);
+                lines.push("Show these to the user. If they approve, call update_diagram again with the SAME dbml and confirmDeletions: true.");
+            }
+            if (res.warnings.length) {
+                lines.push("", "Warnings:", ...res.warnings.map((w) => `- ${w}`));
+            }
+            return text(lines.join("\n"));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
     return server;
 }
 async function main() {
     const config = loadConfig(); // throws with a clear message if unset
     const client = new DdtClient(config);
-    const server = buildServer(client);
+    const server = buildServer(client, config);
     await server.connect(new StdioServerTransport());
     // stderr only — stdout carries the MCP protocol.
     process.stderr.write(`db-diagram-tool-mcp v${SERVER_VERSION} connected (backend: ${config.baseUrl})\n`);

package/dist/relayPeer.js

@@ -0,0 +1,99 @@
+import * as Y from "yjs";
+import { WebsocketProvider } from "y-websocket";
+import { WebSocket as NodeWebSocket } from "ws";
+import { materialize } from "./core/snapshot.js";
+import { seedIfEmpty } from "./core/seed.js";
+/**
+ * Headless relay peer for write-back (task 3.4, Approach C).
+ *
+ * `withRoom` briefly joins a diagram's live Yjs relay room as a peer, lets `fn`
+ * merge an edit into the shared doc, then persists via the durable snapshot save
+ * — exactly like a collaborator typing. It authenticates the handshake with the
+ * short-lived `aud:"ws"` token (never the PAT), as the `bearer.<jwt>` subprotocol
+ * the FE provider uses.
+ *
+ * ⚠️ The relay is DOC-LESS (it relays frames; it never materializes CRDT state).
+ * A lone first peer therefore never receives sync-step-2, so y-websocket's `sync`
+ * event NEVER fires — we must NOT await it. We wait on `wsconnected` + a settle
+ * window (for the relay to replay its log, if any), then reconcile against the
+ * durable REST snapshot: `seedIfEmpty` seeds only when the room was empty.
+ */
+/** Subprotocol version marker offered on the handshake (contract 3 §2.1). */
+export const WS_SUBPROTOCOL = "ddt.v1";
+const WS_PATH = "/api/v1/ws/diagrams";
+/** WS origin + the relay endpoint path (room id appended by WebsocketProvider). */
+export function wsServerUrl(wsUrl) {
+    return wsUrl.replace(/\/+$/, "") + WS_PATH;
+}
+const DEFAULT_SETTLE_MS = 750;
+const DEFAULT_FLUSH_MS = 300;
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * Join `diagramId`'s relay room, run `fn(doc)` to merge an edit, persist, and
+ * tear down. Returns the materialized (saved) Diagram. Throws if the relay never
+ * connects within the timeout.
+ */
+export async function withRoom(deps, diagramId, wsToken, fn) {
+    const doc = new Y.Doc();
+    const WsImpl = deps.WebSocketImpl ?? NodeWebSocket;
+    const provider = new WebsocketProvider(wsServerUrl(deps.wsUrl), diagramId, doc, {
+        disableBc: true,
+        protocols: [WS_SUBPROTOCOL, `bearer.${wsToken}`],
+        WebSocketPolyfill: WsImpl,
+    });
+    try {
+        await waitForConnected(provider, deps.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+        // Doc-less relay: `sync` never fires for a lone peer. Give the relay a moment
+        // to replay its log (if the room was live), then reconcile with the snapshot.
+        await sleep(deps.settleMs ?? DEFAULT_SETTLE_MS);
+        const snapshot = await deps.getSnapshot(diagramId);
+        seedIfEmpty(doc, snapshot);
+        await fn(doc);
+        // Let our update frame flush to the relay so live peers see it, then persist.
+        await sleep(deps.flushMs ?? DEFAULT_FLUSH_MS);
+        const result = materialize(doc);
+        await deps.putSnapshot(diagramId, result);
+        return result;
+    }
+    finally {
+        teardown(provider, doc);
+    }
+}
+function waitForConnected(provider, timeoutMs) {
+    if (provider.wsconnected)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onStatus = (e) => {
+            if (e.status === "connected") {
+                cleanup();
+                resolve();
+            }
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`relay connect timed out after ${timeoutMs}ms (${provider.url})`));
+        }, timeoutMs);
+        const cleanup = () => {
+            clearTimeout(timer);
+            provider.off("status", onStatus);
+        };
+        provider.on("status", onStatus);
+    });
+}
+function teardown(provider, doc) {
+    try {
+        provider.destroy(); // disconnects + clears timers/listeners
+    }
+    catch {
+        /* best-effort */
+    }
+    try {
+        doc.destroy();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/writeback.js

@@ -0,0 +1,233 @@
+import * as Y from "yjs";
+import { hydrate, materialize } from "./core/snapshot.js";
+import { planApply } from "./core/apply.js";
+import { applyIncremental } from "./core/ops.js";
+import { dbmlToDiagram } from "./core/dbmlToDiagram.js";
+import { SCHEMA_VERSION, } from "./core/types/diagram.js";
+/** A DBML parse failure — surfaced to the tool with line/column, never a create/update. */
+export class DbmlError extends Error {
+    detail;
+    constructor(detail) {
+        super(detail.message);
+        this.detail = detail;
+        this.name = "DbmlError";
+    }
+}
+// --- create ------------------------------------------------------------------
+export async function createDiagram(deps, input) {
+    const parsed = dbmlToDiagram(input.dbml);
+    if (parsed.error)
+        throw new DbmlError(parsed.error);
+    const { id } = await deps.createDiagram(input.name);
+    const built = {
+        schemaVersion: SCHEMA_VERSION,
+        id,
+        name: input.name,
+        tables: parsed.diagram.tables,
+        relationships: parsed.diagram.relationships,
+    };
+    layoutGrid(built.tables); // headless: no React Flow measurements — a simple grid
+    // Route through hydrate → materialize so the saved snapshot is the same CLEAN,
+    // contract-closed projection the editor's save produces.
+    const doc = new Y.Doc();
+    hydrate(doc, built);
+    await deps.putSnapshot(id, materialize(doc));
+    doc.destroy();
+    const base = deps.appUrl.replace(/\/+$/, "");
+    return { id, url: `${base}/editor/${id}`, warnings: parsed.warnings };
+}
+// --- update ------------------------------------------------------------------
+export async function updateDiagram(deps, input) {
+    const parsed = dbmlToDiagram(input.dbml);
+    if (parsed.error)
+        throw new DbmlError(parsed.error);
+    const next = parsed.diagram;
+    const confirm = input.confirmDeletions === true;
+    const { token } = await deps.mintWsToken(input.id);
+    let resolved;
+    await deps.runInRoom(input.id, token, (doc) => {
+        const current = materialize(doc);
+        // Carry positions over by table name; stage genuinely-new tables to the side.
+        const plan = planApply({ ...next, id: current.id, name: current.name }, current);
+        if (plan.allNew)
+            layoutGrid(plan.diagram.tables);
+        resolved = resolveOps(current, plan.diagram, confirm);
+        applyIncremental(doc, resolved.ops);
+    });
+    const result = {
+        applied: resolved.applied,
+        warnings: parsed.warnings,
+    };
+    if (resolved.pendingDeletions)
+        result.pendingDeletions = resolved.pendingDeletions;
+    return result;
+}
+/**
+ * Reconcile the intended `next` schema against the `current` live schema
+ * (matched by NAME) into id-keyed incremental ops. Additive changes (new tables,
+ * new/changed columns, new FK lines) are always applied; table/column deletions
+ * are applied only when `confirmDeletions`, else returned as `pendingDeletions`.
+ * Kept entities reuse their LIVE ids so the merge patches in place (stable for
+ * relationships + a concurrent human's cursor), and new entities keep fresh ids.
+ */
+export function resolveOps(current, next, confirmDeletions) {
+    const liveByName = new Map(current.tables.map((t) => [t.name, t]));
+    const nextByName = new Map(next.tables.map((t) => [t.name, t]));
+    const addTables = [];
+    const modifyTables = [];
+    const removeTableIds = [];
+    const removeColumns = [];
+    const addedTables = [];
+    const modifiedTables = [];
+    const pendingTables = [];
+    const pendingColumns = [];
+    const finalTableId = (name) => liveByName.get(name)?.id ?? nextByName.get(name)?.id ?? "";
+    const finalColumnId = (tableName, colName) => {
+        const lc = liveByName.get(tableName)?.columns.find((c) => c.name === colName);
+        if (lc)
+            return lc.id;
+        return nextByName.get(tableName)?.columns.find((c) => c.name === colName)?.id ?? "";
+    };
+    const markModified = (name) => {
+        if (!modifiedTables.includes(name))
+            modifiedTables.push(name);
+    };
+    // Added tables + kept-table column reconciliation.
+    for (const t of next.tables) {
+        const live = liveByName.get(t.name);
+        if (!live) {
+            addTables.push(t); // fresh ids + staged position (planApply set it)
+            addedTables.push(t.name);
+            continue;
+        }
+        const liveByCol = new Map(live.columns.map((c) => [c.name, c]));
+        const nextNames = new Set(t.columns.map((c) => c.name));
+        let additive = false;
+        const modifyCols = t.columns.map((c) => {
+            const lc = liveByCol.get(c.name);
+            if (!lc) {
+                additive = true; // a new column
+                return c;
+            }
+            if (!columnFieldsEqual(lc, c))
+                additive = true; // a changed column
+            return { ...c, id: lc.id }; // reuse the live id → patch in place
+        });
+        if (additive) {
+            modifyTables.push({ ...t, id: live.id, columns: modifyCols });
+            markModified(t.name);
+        }
+        for (const lc of live.columns) {
+            if (nextNames.has(lc.name))
+                continue; // kept
+            if (confirmDeletions) {
+                removeColumns.push({ tableId: live.id, columnId: lc.id });
+                markModified(t.name);
+            }
+            else {
+                pendingColumns.push(`${t.name}.${lc.name}`);
+            }
+        }
+    }
+    // Removed tables.
+    for (const t of current.tables) {
+        if (nextByName.has(t.name))
+            continue;
+        if (confirmDeletions)
+            removeTableIds.push(t.id);
+        else
+            pendingTables.push(t.name);
+    }
+    // Relationships (matched by endpoint NAME + cardinality; not gated, but a line
+    // touching a WITHHELD table drop is kept so nothing dangles mid-approval).
+    const curKeys = new Set(current.relationships.map((r) => relKey(r, current)));
+    const desiredKeys = new Set(next.relationships.map((r) => relKey(r, next)));
+    const withheld = confirmDeletions ? new Set() : new Set(pendingTables);
+    const addRelationships = [];
+    for (const r of next.relationships) {
+        if (curKeys.has(relKey(r, next)))
+            continue;
+        const [ft, fc, tt, tc] = relEndpointNames(r, next);
+        addRelationships.push({
+            id: r.id,
+            fromTableId: finalTableId(ft),
+            fromColumnId: finalColumnId(ft, fc),
+            toTableId: finalTableId(tt),
+            toColumnId: finalColumnId(tt, tc),
+            cardinality: r.cardinality,
+        });
+    }
+    const removeRelationshipIds = [];
+    for (const r of current.relationships) {
+        if (desiredKeys.has(relKey(r, current)))
+            continue;
+        const [ft, , tt] = relEndpointNames(r, current);
+        if (withheld.has(ft) || withheld.has(tt))
+            continue; // keep while the drop is pending
+        removeRelationshipIds.push(r.id);
+    }
+    const remove = removeTableIds.length || removeColumns.length || removeRelationshipIds.length
+        ? { tables: removeTableIds, columns: removeColumns, relationships: removeRelationshipIds }
+        : undefined;
+    const ops = {
+        add: addTables.length ? addTables : undefined,
+        modify: modifyTables.length ? modifyTables : undefined,
+        addRelationships: addRelationships.length ? addRelationships : undefined,
+        remove,
+    };
+    const pendingDeletions = pendingTables.length || pendingColumns.length
+        ? { tables: pendingTables, columns: pendingColumns }
+        : null;
+    return { ops, applied: { addedTables, modifiedTables }, pendingDeletions };
+}
+// --- helpers -----------------------------------------------------------------
+function columnFieldsEqual(a, b) {
+    return (a.type === b.type &&
+        a.isPrimaryKey === b.isPrimaryKey &&
+        a.isForeignKey === b.isForeignKey &&
+        a.isNullable === b.isNullable &&
+        a.isUnique === b.isUnique &&
+        (a.default ?? null) === (b.default ?? null) &&
+        (a.note ?? null) === (b.note ?? null));
+}
+function relEndpointNames(r, d) {
+    const tName = new Map(d.tables.map((t) => [t.id, t.name]));
+    const cName = new Map(d.tables.flatMap((t) => t.columns.map((c) => [c.id, c.name])));
+    return [
+        tName.get(r.fromTableId) ?? "",
+        cName.get(r.fromColumnId) ?? "",
+        tName.get(r.toTableId) ?? "",
+        cName.get(r.toColumnId) ?? "",
+    ];
+}
+function relKey(r, d) {
+    const [ft, fc, tt, tc] = relEndpointNames(r, d);
+    return `${ft}.${fc}>${tt}.${tc}#${r.cardinality}`;
+}
+// Rough table footprint (mirrors apply.ts) for a simple headless grid — the user
+// can auto-arrange in the editor; this just avoids stacking everything at (0,0).
+const CELL_W = 300;
+const GAP_X = 64;
+const GAP_Y = 48;
+const estHeight = (t) => 44 + t.columns.length * 28;
+function layoutGrid(tables) {
+    const perRow = Math.max(1, Math.ceil(Math.sqrt(tables.length)));
+    let x = 0;
+    let y = 0;
+    let rowHeight = 0;
+    let col = 0;
+    for (const t of tables) {
+        t.position = { x, y };
+        rowHeight = Math.max(rowHeight, estHeight(t));
+        col += 1;
+        if (col >= perRow) {
+            col = 0;
+            x = 0;
+            y += rowHeight + GAP_Y;
+            rowHeight = 0;
+        }
+        else {
+            x += CELL_W + GAP_X;
+        }
+    }
+}

package/package.json

@@ -1,28 +1,39 @@
 {
   "name": "db-diagram-tool-mcp",
-  "version": "0.1.0",
-  "description": "Read-only Model Context Protocol (stdio) server for DB Diagram Tool — lets Claude Code / Codex read your diagrams (list, schema JSON, DBML, SQL DDL).",
+  "version": "0.2.0",
+  "description": "Model Context Protocol (stdio) server for DB Diagram Tool — lets Claude Code / Codex read (list, schema JSON, DBML, SQL DDL) and, with a write-scoped token, create and update your diagrams from DBML.",
   "type": "module",
   "bin": {
     "db-diagram-tool-mcp": "dist/index.js"
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
+    "@dbml/core": "10.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.21.3",
+    "y-websocket": "^3.1.0",
+    "yjs": "^13.6.32",
     "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^22",
+    "@types/ws": "^8.18.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.7"
   }
 }