@dforge-core/dforge-mcp 0.2.28 → 0.2.29

package/README.md

@@ -1,6 +1,6 @@
 # @dforge-core/dforge-mcp
 
-MCP server for dForge module authoring. Exposes 34 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
+MCP server for dForge module authoring. Exposes 35 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
 
 Ships with **four Claude Skills** (`skills/`): a router plus one skill per lifecycle stage — design (Phase 0), build (Phases 1-5), and ship (Phase 6). The router directory carries 25 reference files (field types, flags, traits, formulas, DSL, security, etc.) and two annotated example modules.
 
@@ -74,7 +74,7 @@ claude mcp list
 # Should show: dforge — npx -y @dforge-core/dforge-mcp — connected
 ```
 
-Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 34 `dforge_*` tools should be listed.
+Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 35 `dforge_*` tools should be listed.
 
 ### Cursor / Zed
 
@@ -157,6 +157,7 @@ The field/entity tools validate against the `@dforge-core/metadata` registry: an
 | Tool | Behavior |
 |---|---|
 | `dforge_dependency_add` | Add a dep on another dForge module |
+| `dforge_diagram_add` | Create or extend a named entity diagram, `docs/diagrams/<code>.json` (design-time only) — one per functional area of a large module. Takes entity keys and/or `fromFolder` (a folder's entities plus its descendants'); appends only, keeping placed positions. Rejects a key that resolves to no own or dependency entity |
 | `dforge_dbml_import` | **DBML front-end** to `module_import` — parses DBML (Table blocks, typed columns, inline + top-level refs) into the table-spec, drops the source PK (identity provides `{entity}_id`), and imports. Pass `module` for a greenfield import |
 
 ### Writing files: preview vs `apply`
@@ -179,7 +180,7 @@ Served over MCP with descriptions and mime types, so the agent can tell what a U
 
 | URI pattern | Content |
 |---|---|
-| `dforge://schema/<name>` | JSON Schemas: `manifest`, `entity`, `domains`, `data-views`, `folders`, `menus`, `roles`, `jobs`, `seed-data`, `traits`, `webhooks`, `triggers`, `print-templates`, `settings`, `reports` |
+| `dforge://schema/<name>` | JSON Schemas: `manifest`, `entity`, `domains`, `data-views`, `folders`, `diagram`, `menus`, `roles`, `jobs`, `seed-data`, `traits`, `webhooks`, `triggers`, `print-templates`, `settings`, `reports` |
 | `dforge://reference/<name>` | 25 per-element authoring references — schema shape + worked example + common-mistakes list for one element type |
 | `dforge://example/<path>` | Files from the canonical `simple-todo` module (mandatory structure validators) |
 | `dforge://example/matrix-budget/<path>` | Files from the `matrix` (pivot) view example |

package/dist/server.js

@@ -31283,7 +31283,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.29/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.30/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -31296,9 +31296,9 @@ var AGG_TYPE_LIST = Object.values(AggType);
 var fieldTypes = [
   { cd: "text", name: "Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "avatar", name: "Avatar Name", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
-  { cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
-  { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
-  { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true, defParams: { pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" } },
+  { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true, defParams: { pattern: "^\\+?[0-9\\s\\-().]+$" } },
+  { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true, defParams: { pattern: "^https?://.+", patternFlags: "i" } },
   { cd: "textarea", name: "Multiline Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false },
@@ -31538,6 +31538,7 @@ function modulePaths(moduleDir) {
     translationsDir: path.join(root, "translations"),
     dataViews: path.join(root, "ui", "data_views.json"),
     folders: path.join(root, "ui", "folders.json"),
+    diagramsDir: path.join(root, "docs", "diagrams"),
     menus: path.join(root, "ui", "menus.json"),
     actions: path.join(root, "ui", "actions.json"),
     reports: path.join(root, "ui", "reports.json"),
@@ -31569,6 +31570,52 @@ function readJsonOrDefault(absPath, dflt) {
     throw new Error(`${absPath}: ${e.message}`);
   }
 }
+function diagramFiles(diagramsDir) {
+  if (!fs.existsSync(diagramsDir)) return [];
+  return fs.readdirSync(diagramsDir).filter((f) => f.endsWith(".json")).sort().map((f) => path.join(diagramsDir, f));
+}
+function isPlannedDiagramKey(key, entityMap) {
+  return !key.includes(".") && !Object.prototype.hasOwnProperty.call(entityMap, key);
+}
+function likelyMisspelledEntity(key, entityMap) {
+  let best;
+  for (const code2 of Object.keys(entityMap)) {
+    if (code2.includes(".")) continue;
+    const d = editDistance(key, code2);
+    if (d > 2 || d >= Math.min(key.length, code2.length) / 3) continue;
+    if (!best || d < best.d) best = { code: code2, d };
+  }
+  return best?.code;
+}
+function editDistance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+function diagramKeyProblem(key, entityMap, deps, root) {
+  if (Object.prototype.hasOwnProperty.call(entityMap, key)) return void 0;
+  const dep = [...deps].filter((d) => key.startsWith(`${d}.`) && key.length > d.length + 1).sort((a, b) => b.length - a.length)[0];
+  if (!dep) {
+    return key.includes(".") ? `'${key}' is not an entity of this module, and no declared dependency matches its module prefix. Declare the dependency, or drop the entity from the diagram.` : `'${key}' is not an entity in manifest.entities. Drop it from the diagram, or fix the code.`;
+  }
+  const contractPath = path.join(root, "deps", `${dep}.json`);
+  if (!fs.existsSync(contractPath)) return void 0;
+  let consumed;
+  try {
+    consumed = JSON.parse(fs.readFileSync(contractPath, "utf8"))?.entities;
+  } catch {
+    return void 0;
+  }
+  if (!consumed || typeof consumed !== "object") return void 0;
+  const entity = key.slice(dep.length + 1);
+  return Object.prototype.hasOwnProperty.call(consumed, entity) ? void 0 : `'${entity}' is not among the entities deps/${dep}.json consumes from '${dep}'. Add it to the contract if the module uses it, or drop it from the diagram.`;
+}
 function jsonText(obj) {
   return JSON.stringify(obj, null, "	") + "\n";
 }
@@ -34207,6 +34254,20 @@ function entityRename(args) {
   const entityMap = manifest.entities ?? {};
   if (!(oldE in entityMap)) throw new Error(`Entity '${oldE}' is not in the manifest.`);
   if (newE in entityMap) throw new Error(`Entity '${newE}' already exists in this module.`);
+  const collisions = diagramFiles(paths.diagramsDir).filter((fp) => {
+    let d;
+    try {
+      d = JSON.parse(fs6.readFileSync(fp, "utf8"));
+    } catch {
+      return false;
+    }
+    return !!d && typeof d === "object" && diagramMentions(d, oldE) && diagramMentions(d, newE);
+  }).map((fp) => `docs/diagrams/${path8.basename(fp)}`);
+  if (collisions.length > 0) {
+    throw new Error(
+      `${collisions.join(", ")} already draw${collisions.length === 1 ? "s" : ""} a '${newE}' alongside '${oldE}' \u2014 renaming would merge the two nodes. Remove or rename '${newE}' in the diagram first.`
+    );
+  }
   const files = {};
   const deletes = [];
   const changes = [];
@@ -34312,6 +34373,36 @@ function entityRename(args) {
     files[rel(paths.root, paths.folders)] = jsonText(folders);
     changes.push("folders.json (entity bindings)");
   }
+  for (const fp of diagramFiles(paths.diagramsDir)) {
+    let d;
+    try {
+      d = JSON.parse(fs6.readFileSync(fp, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!d || typeof d !== "object") continue;
+    const what = [];
+    const ents = d.entities;
+    if (ents && typeof ents === "object" && oldE in ents) {
+      d.entities = renameKey(ents, oldE, newE);
+      what.push("entity key");
+    }
+    let relTouched = false;
+    for (const r of diagramRelations(d)) {
+      if (r.from === oldE) {
+        r.from = newE;
+        relTouched = true;
+      }
+      if (r.to === oldE) {
+        r.to = newE;
+        relTouched = true;
+      }
+    }
+    if (relTouched) what.push("relations");
+    if (what.length === 0) continue;
+    files[rel(paths.root, fp)] = jsonText(d);
+    changes.push(`docs/diagrams/${path8.basename(fp)} (${what.join(", ")})`);
+  }
   if (fs6.existsSync(paths.seedDataDir)) {
     for (const file2 of fs6.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json"))) {
       const fp = path8.join(paths.seedDataDir, file2);
@@ -34338,6 +34429,17 @@ function entityRename(args) {
     deletes
   );
 }
+function diagramRelations(d) {
+  if (!Array.isArray(d.relations)) return [];
+  return d.relations.filter(
+    (r) => !!r && typeof r === "object" && !Array.isArray(r)
+  );
+}
+function diagramMentions(d, key) {
+  const ents = d.entities;
+  if (ents && typeof ents === "object" && Object.prototype.hasOwnProperty.call(ents, key)) return true;
+  return diagramRelations(d).some((r) => r.from === key || r.to === key);
+}
 var entityDeleteSchema = {
   moduleDir: external_exports.string().describe("Path to the module root."),
   entityName: code.describe("Entity code to delete.")
@@ -34405,6 +34507,29 @@ function entityDelete(args) {
     files[rel(paths.root, paths.folders)] = jsonText(folders);
     changes.push("folders.json (binding)");
   }
+  for (const fp of diagramFiles(paths.diagramsDir)) {
+    let d;
+    try {
+      d = JSON.parse(fs6.readFileSync(fp, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!d || typeof d !== "object") continue;
+    const what = [];
+    const ents = d.entities;
+    if (ents && typeof ents === "object" && target in ents) {
+      delete ents[target];
+      what.push("entity key");
+    }
+    const doomed = new Set(diagramRelations(d).filter((r) => r.from === target || r.to === target));
+    if (doomed.size > 0) {
+      d.relations = d.relations.filter((r) => !doomed.has(r));
+      what.push("relations");
+    }
+    if (what.length === 0) continue;
+    files[rel(paths.root, fp)] = jsonText(d);
+    changes.push(`docs/diagrams/${path8.basename(fp)} (${what.join(", ")})`);
+  }
   const views = readJsonOrDefault(paths.dataViews, {});
   let viewsTouched = false;
   const removedViews = [];
@@ -34465,7 +34590,7 @@ function entityDelete(args) {
 // src/tools/action-add.ts
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.29/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.30/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -36739,6 +36864,81 @@ function folderAdd(args) {
     }
   );
 }
+var diagramAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Diagram code \u2014 becomes the file name docs/diagrams/<code>.json."),
+  label: external_exports.string().optional().describe("Display name. Defaults to the fromFolder's label, else the code."),
+  description: external_exports.string().optional().describe("What part of the model the diagram covers."),
+  entities: external_exports.array(external_exports.string().min(1)).default([]).describe(
+    "Entity keys to draw: the manifest's own entity code ('invoice'), or 'module.entity' for an entity of a declared dependency ('parties.party') \u2014 the same form a field link's `entity` takes."
+  ),
+  fromFolder: external_exports.string().optional().describe(
+    "A folder code from ui/folders.json (anywhere in the tree). Adds the entities bound to that folder AND to all its descendants."
+  ),
+  showBoundary: external_exports.boolean().optional().describe(
+    "Also draw the entities outside the diagram that its entities reference or are referenced by, as header-only stubs. Default true."
+  )
+};
+function diagramAdd(args) {
+  if (!/^[a-z][a-z0-9_]*$/.test(args.code)) {
+    throw new Error(`Diagram code '${args.code}' must be snake_case (^[a-z][a-z0-9_]*$) \u2014 it becomes the file name.`);
+  }
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const entityMap = manifest.entities ?? {};
+  const deps = new Set(Object.keys(manifest.dependencies ?? {}));
+  const keys = [...args.entities];
+  let folderLabel;
+  if (args.fromFolder !== void 0) {
+    const root = readJsonOrDefault(paths.folders, {});
+    const folder = walkFolders(root).find((f) => f.code === args.fromFolder);
+    if (!folder) {
+      throw new Error(
+        `Folder '${args.fromFolder}' is not in ui/folders.json. Pass a sub-folder's code (codes are unique across the tree); for every entity in the module, list them in 'entities' instead.`
+      );
+    }
+    if (typeof folder.node.label === "string") folderLabel = folder.node.label;
+    for (const node of [folder.node, ...walkFolders(folder.node).map((f) => f.node)]) {
+      keys.push(...Object.keys(node.entities ?? {}));
+    }
+  }
+  const wanted = [...new Set(keys)];
+  const problems = wanted.map((k) => diagramKeyProblem(k, entityMap, deps, paths.root)).filter((p) => p !== void 0);
+  if (problems.length > 0) {
+    throw new Error(`Nothing written \u2014 ${problems.join(" ")}`);
+  }
+  const file2 = path13.join(paths.diagramsDir, `${args.code}.json`);
+  const exists = fs10.existsSync(file2);
+  let diagram;
+  if (exists) {
+    const existing = readJson(file2);
+    if (!existing || typeof existing !== "object" || Array.isArray(existing) || !existing.entities || typeof existing.entities !== "object" || Array.isArray(existing.entities)) {
+      throw new Error(
+        `${rel(paths.root, file2)} is not a diagram (an object with an 'entities' map) \u2014 fix or delete it first.`
+      );
+    }
+    diagram = existing;
+    if (args.label !== void 0) diagram.label = args.label;
+    if (args.description !== void 0) diagram.description = args.description;
+    if (args.showBoundary !== void 0) diagram.showBoundary = args.showBoundary;
+  } else {
+    diagram = { label: args.label ?? folderLabel ?? args.code };
+    if (args.description !== void 0) diagram.description = args.description;
+    diagram.entities = {};
+    if (args.showBoundary !== void 0) diagram.showBoundary = args.showBoundary;
+  }
+  const entities = diagram.entities;
+  const added = wanted.filter((k) => !Object.prototype.hasOwnProperty.call(entities, k));
+  for (const k of added) entities[k] = {};
+  const relPath = rel(paths.root, file2);
+  const present = wanted.length - added.length;
+  return makeResult(
+    exists ? `Updated diagram '${args.code}' (${relPath}): added ${added.length} entit${added.length === 1 ? "y" : "ies"}${present ? `, ${present} already drawn` : ""}.` : `Created diagram '${args.code}' (${relPath}) with ${added.length} entit${added.length === 1 ? "y" : "ies"}.`,
+    {
+      [relPath]: jsonText(diagram),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
 var SYSTEM_MODULES = /* @__PURE__ */ new Set(["admin", "metadata", "workspace"]);
 var dependencyAddSchema = {
   moduleDir: external_exports.string(),
@@ -36900,6 +37100,18 @@ function moduleInspect(args) {
   }));
   const foldersTree = readJsonOrDefault(paths.folders, {});
   const folderDepth = computeDepth(foldersTree);
+  const diagramSummaries = diagramFiles(paths.diagramsDir).map((fp) => {
+    let d = {};
+    try {
+      d = JSON.parse(fs11.readFileSync(fp, "utf8"));
+    } catch {
+    }
+    return {
+      code: path14.basename(fp, ".json"),
+      label: typeof d?.label === "string" ? d.label : void 0,
+      entities: Object.keys(d?.entities ?? {})
+    };
+  });
   const menus = readJsonOrDefault(paths.menus, {});
   const menuSummaries = Object.entries(menus).map(([code2, m]) => ({
     code: code2,
@@ -36967,6 +37179,7 @@ function moduleInspect(args) {
     entities: entitySummaries,
     views: viewSummaries,
     folders: { tree: foldersTree, depth: folderDepth },
+    diagrams: diagramSummaries,
     menus: menuSummaries,
     roles: roleSummaries,
     actions: actionSummaries,
@@ -37549,6 +37762,47 @@ function moduleValidate(args, cli) {
       }
     }
   }
+  for (const fp of diagramFiles(paths.diagramsDir)) {
+    const where = `docs/diagrams/${path15.basename(fp)}`;
+    let diagram;
+    try {
+      diagram = JSON.parse(fs12.readFileSync(fp, "utf8"));
+    } catch (ex) {
+      err(where, `invalid JSON: ${ex.message}`);
+      continue;
+    }
+    if (!diagram || typeof diagram !== "object" || Array.isArray(diagram)) {
+      warn(where, "must be an object \u2014 the diagram itself, with an 'entities' map.");
+      continue;
+    }
+    const diagramEntities = diagram.entities;
+    if (!diagramEntities || typeof diagramEntities !== "object" || Array.isArray(diagramEntities)) {
+      warn(where, "has no 'entities' object \u2014 list the entities the diagram draws, keyed by entity code.");
+      continue;
+    }
+    for (const [key, placement] of Object.entries(diagramEntities)) {
+      const at = `${where} \u2192 entities.${key}`;
+      if (isPlannedDiagramKey(key, entityMap)) {
+        const meant = likelyMisspelledEntity(key, entityMap);
+        if (meant) {
+          warn(
+            at,
+            `'${key}' is not built yet, so the diagram draws it as a planned entity. If you meant the existing '${meant}', fix the key.`
+          );
+        }
+      } else {
+        const unresolved = diagramKeyProblem(key, entityMap, deps, paths.root);
+        if (unresolved) warn(at, unresolved);
+      }
+      const p = placement && typeof placement === "object" ? placement : {};
+      if ("x" in p !== "y" in p) {
+        warn(
+          at,
+          `sets '${"x" in p ? "x" : "y"}' without '${"x" in p ? "y" : "x"}'. Give both to pin the entity, or neither to let the diagram place it.`
+        );
+      }
+    }
+  }
   for (const [rcode, rawReport] of Object.entries(reports)) {
     const report = rawReport ?? {};
     const where = `ui/reports.json \u2192 ${rcode}`;
@@ -38022,6 +38276,11 @@ var resources = [
     "Folders JSON schema",
     "JSON Schema for ui/folders.json \u2014 root folder tree with per-entity view bindings."
   ),
+  schema(
+    "diagram",
+    "Diagram JSON schema",
+    "JSON Schema for docs/diagrams/<code>.json \u2014 one entity diagram per file, the file name is its code (a subset of entities + optional x/y placement each). Design-time only: install ignores it."
+  ),
   schema(
     "menus",
     "Menus JSON schema",
@@ -38309,7 +38568,7 @@ server.registerTool(
   "dforge_entity_rename",
   {
     title: "Rename an entity (refactor-safe)",
-    description: "Refactor-safe rename of an entity code. Moves the entity file (old is listed in the response's `deletes` \u2014 delete it), renames the manifest key, cascades the identity PK {old}_id \u2192 {new}_id wherever an FK targets it, and repoints every reference: other entities' link.entity / references.to, view entityCode, role rights keys, action entity, folder bindings, and seed-data entityCode + PK keys. Reports/translations/menu labels/DSL are NOT rewritten (warned). Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
+    description: "Refactor-safe rename of an entity code. Moves the entity file (old is listed in the response's `deletes` \u2014 delete it), renames the manifest key, cascades the identity PK {old}_id \u2192 {new}_id wherever an FK targets it, and repoints every reference: other entities' link.entity / references.to, view entityCode, role rights keys, action entity, folder bindings, diagram entity keys (docs/diagrams/*.json), and seed-data entityCode + PK keys. Reports/translations/menu labels/DSL are NOT rewritten (warned). Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
     inputSchema: { ...entityRenameSchema, ...applyInput },
     annotations: DESTRUCTIVE
   },
@@ -38319,7 +38578,7 @@ server.registerTool(
   "dforge_entity_delete",
   {
     title: "Delete an entity (refactor-safe)",
-    description: "Refactor-safe deletion of an entity. Removes the entity file + its seed files (listed in `deletes`), drops the manifest entry, role rights key, folder binding, and data-view sources (deleting a view left with no source). Cross-entity FKs targeting it, actions on it, and menus pointing at removed views are surfaced as warnings \u2014 fix those by hand. Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
+    description: "Refactor-safe deletion of an entity. Removes the entity file + its seed files (listed in `deletes`), drops the manifest entry, role rights key, folder binding, diagram entries (docs/diagrams/*.json), and data-view sources (deleting a view left with no source). Cross-entity FKs targeting it, actions on it, and menus pointing at removed views are surfaced as warnings \u2014 fix those by hand. Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
     inputSchema: { ...entityDeleteSchema, ...applyInput },
     annotations: DESTRUCTIVE
   },
@@ -38534,6 +38793,15 @@ server.registerTool(
   },
   envelope(dependencyAdd)
 );
+server.registerTool(
+  "dforge_diagram_add",
+  {
+    title: "Add or extend an entity diagram",
+    description: "Create or extend a named entity diagram, docs/diagrams/<code>.json \u2014 one file per diagram, drawing a chosen subset of entities. Design-time only (install ignores it). Use it on a LARGE module to give each functional area its own readable diagram (e.g. 'billing', 'inventory'); a small module needs none. Pass `entities` (own code, or 'module.entity' for a declared dependency) and/or `fromFolder` to take a folder's entities plus all its descendants'. On an existing diagram it only appends missing entities \u2014 positions already set are kept and nothing is removed. Leave layout to the editor: new entities get no x/y. An entity key that resolves to nothing is rejected and nothing is written.",
+    inputSchema: { ...diagramAddSchema, ...applyInput }
+  },
+  envelope(diagramAdd)
+);
 server.registerTool(
   "dforge_dbml_import",
   {

package/docs/creating-modules.md

@@ -160,5 +160,5 @@ VS Code with the [dForge extension](https://github.com/dforge-core/dforge-editor
 - [dforge-module-design](../skills/dforge-module-design/SKILL.md) — Phase 0, including the intake guardrails and gap scans
 - [dforge-module-build](../skills/dforge-module-build/SKILL.md) — Phases 1-5, the loading-policy table, core-rules cheat sheet, and the deterministic backtrack protocol
 - [dforge-module-ship](../skills/dforge-module-ship/SKILL.md) — Phase 6 and the install-fix loop
-- [README.md](../README.md) — full tool reference (34 tools) + maintainer docs
+- [README.md](../README.md) — full tool reference (35 tools) + maintainer docs
 - [iash44/dForge-core](https://github.com/iash44/dForge-core) — the platform itself: source of truth for the schemas + DSL conventions

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.28",
-	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
+	"version": "0.2.29",
+	"description": "MCP server for dForge module authoring. Exposes 35 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
 	"packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
@@ -36,7 +36,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.22",
-		"@dforge-core/metadata": "^0.0.29",
+		"@dforge-core/metadata": "^0.0.30",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/diagram.schema.json

@@ -0,0 +1,101 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/diagram.schema.json",
+	"title": "dForge Diagram",
+	"description": "One named entity diagram of a dForge module: docs/diagrams/<code>.json, the file name being the diagram's code. A diagram draws a chosen subset of entities, so a large module can be read one area at a time. Design-time only: the platform installs the module without reading it.",
+	"type": "object",
+	"required": ["entities"],
+	"properties": {
+		"$schema": {
+			"type": "string"
+		},
+		"label": {
+			"type": "string",
+			"description": "Diagram display name. Defaults to the diagram code."
+		},
+		"description": {
+			"type": "string",
+			"description": "What part of the model the diagram covers."
+		},
+		"entities": {
+			"type": "object",
+			"description": "Entity key → placement. A key is the entity code as the module's manifest names it, or `module.entity` for an entity of a dependency — the same form a field link's `entity` takes. A key no entity has yet is a planned entity, drawn as a name only. An empty object places the entity automatically.",
+			"propertyNames": {
+				"minLength": 1
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/diagramEntity"
+			}
+		},
+		"showBoundary": {
+			"type": "boolean",
+			"description": "Also draw the entities outside the diagram that its entities reference or are referenced by, as header-only stubs, so relations leaving the diagram stay visible. Default: true."
+		},
+		"detail": {
+			"type": "string",
+			"enum": ["conceptual", "keys", "full"],
+			"description": "How much of each entity to draw: `conceptual` — the name only, relations drawn entity to entity; `keys` — primary and foreign key columns; `full` — every column. Default: full."
+		},
+		"relations": {
+			"type": "array",
+			"description": "Relations drawn by hand, for entities with no foreign key between them yet — a planned entity, or one not built that far. Where a real foreign key links the same two entities, the key is drawn and the relation is not.",
+			"items": {
+				"$ref": "#/$defs/diagramRelation"
+			}
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"diagramEntity": {
+			"type": "object",
+			"properties": {
+				"x": {
+					"type": "number",
+					"description": "Left edge of the entity node, in diagram units. Set together with `y`; both omitted means automatic placement."
+				},
+				"y": {
+					"type": "number",
+					"description": "Top edge of the entity node, in diagram units. Set together with `x`."
+				},
+				"label": {
+					"type": "string",
+					"description": "Display name of a planned entity. An existing entity shows its own label, and this is ignored."
+				},
+				"description": {
+					"type": "string",
+					"description": "What a planned entity will hold. An existing entity shows its own description, and this is ignored."
+				}
+			},
+			"dependencies": {
+				"x": ["y"],
+				"y": ["x"]
+			},
+			"additionalProperties": false
+		},
+		"diagramRelation": {
+			"type": "object",
+			"required": ["from", "to"],
+			"properties": {
+				"from": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Entity key of the many side — the entity that will carry the foreign key."
+				},
+				"to": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Entity key of the one side — the entity referenced."
+				},
+				"label": {
+					"type": "string",
+					"description": "Verb read from `from` to `to`, e.g. `placed by`."
+				},
+				"required": {
+					"type": "boolean",
+					"description": "Every `from` row must have a `to` row. Default: false."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/entity.schema.json

@@ -36,7 +36,7 @@
 			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
 		},
 		"toString": {
-			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\". Optional in extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
+			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\" — the caption of a record wherever it is referenced. Every `{placeholder}` must name a field of the entity (trait columns included) and not a set; pack and install fail otherwise. Omitted, the install generates one from the fields and warns. Not declared on extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
 		},
 		"comments": {
 			"type": "boolean",

package/skills/dforge-mcp-author/SKILL.md

@@ -68,7 +68,7 @@ Full descriptions are on the tools themselves — this is the map.
 | UI | `dforge_view_add`, `dforge_view_modify`, `dforge_menu_add`, `dforge_report_add` |
 | Polish | `dforge_setting_add`, `dforge_translation_sync`, `dforge_seed_add` |
 | Security | `dforge_role_add`, `dforge_role_right_set`, `dforge_folder_add` |
-| Cross-cutting | `dforge_dependency_add` |
+| Cross-cutting | `dforge_dependency_add`, `dforge_diagram_add` |
 
 **Composite tools first.** A relation, a roll-up, and a status column each span
 several coordinated keys, and hand-assembling them from `entity_field_add` is