@cmssy/mcp-server 0.4.0 → 0.6.0

package/dist/server.js

@@ -1,16 +1,45 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { mediaTypeValues } from "@cmssy/types";
+// Read our own version from package.json so the MCP handshake
+// advertises what the user actually installed, instead of drifting
+// whenever we bump the package.
+const PACKAGE_VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(resolve(here, "../package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 /**
  * Preprocess helper: parse JSON string to object if needed.
  * MCP clients may serialize complex nested objects as JSON strings
  * instead of passing them as objects. This ensures they're parsed.
+ * Malformed JSON is passed through so Zod produces a validation error
+ * instead of crashing the handler.
  */
-const jsonPreprocess = (val) => typeof val === "string" ? JSON.parse(val) : val;
-import { PAGES_QUERY, PAGE_BY_ID_QUERY, WORKSPACE_BLOCKS_QUERY, WORKSPACE_BLOCK_BY_TYPE_QUERY, SITE_CONFIG_QUERY, CURRENT_WORKSPACE_QUERY, MEDIA_ASSETS_QUERY, SAVE_PAGE_MUTATION, UPDATE_PAGE_SETTINGS_MUTATION, TOGGLE_PUBLISH_MUTATION, PUBLISH_PAGE_MUTATION, REVERT_TO_PUBLISHED_MUTATION, REMOVE_PAGE_MUTATION, UPDATE_PAGE_LAYOUT_MUTATION, FORMS_QUERY, FORM_BY_ID_QUERY, FORM_SUBMISSIONS_QUERY, FORM_SUBMISSION_BY_ID_QUERY, CREATE_FORM_MUTATION, UPDATE_FORM_MUTATION, DELETE_FORM_MUTATION, UPDATE_FORM_SUBMISSION_STATUS_MUTATION, DELETE_FORM_SUBMISSION_MUTATION, } from "./queries.js";
+const jsonPreprocess = (val) => {
+    if (typeof val !== "string")
+        return val;
+    try {
+        return JSON.parse(val);
+    }
+    catch {
+        return val;
+    }
+};
+import { PAGES_QUERY, PAGE_BY_ID_QUERY, WORKSPACE_BLOCKS_QUERY, WORKSPACE_BLOCK_BY_TYPE_QUERY, SITE_CONFIG_QUERY, CURRENT_WORKSPACE_QUERY, MEDIA_ASSETS_QUERY, SAVE_PAGE_MUTATION, PATCH_BLOCK_CONTENT_MUTATION, UPDATE_PAGE_SETTINGS_MUTATION, TOGGLE_PUBLISH_MUTATION, PUBLISH_PAGE_MUTATION, REVERT_TO_PUBLISHED_MUTATION, REMOVE_PAGE_MUTATION, UPDATE_PAGE_LAYOUT_MUTATION, FORMS_QUERY, FORM_BY_ID_QUERY, FORM_SUBMISSIONS_QUERY, FORM_SUBMISSION_BY_ID_QUERY, CREATE_FORM_MUTATION, UPDATE_FORM_MUTATION, DELETE_FORM_MUTATION, UPDATE_FORM_SUBMISSION_STATUS_MUTATION, DELETE_FORM_SUBMISSION_MUTATION, MODEL_DEFINITIONS_QUERY, MODEL_DEFINITIONS_BY_SLUG_INDEX_QUERY, MODEL_DEFINITION_BY_ID_QUERY, MODEL_RECORDS_QUERY, MODEL_RECORD_BY_ID_QUERY, MODEL_TEMPLATES_QUERY, CREATE_MODEL_DEFINITION_MUTATION, UPDATE_MODEL_DEFINITION_MUTATION, DELETE_MODEL_DEFINITION_MUTATION, CREATE_MODEL_RECORD_MUTATION, UPDATE_MODEL_RECORD_MUTATION, UPDATE_MODEL_RECORD_STATUS_MUTATION, DELETE_MODEL_RECORD_MUTATION, IMPORT_MODEL_RECORDS_MUTATION, INSTALL_MODEL_TEMPLATE_MUTATION, } from "./queries.js";
+import { responseModeSchema, pageMinimal, pageBlockMinimal, formMinimal, modelMinimal, recordMinimal, jsonText, } from "./responses.js";
 export function createServer(client) {
     const server = new McpServer({
         name: "cmssy",
-        version: "0.1.0",
+        version: PACKAGE_VERSION,
     });
     // ─── Workspace Block Registry (cached with TTL) ──────────────
     let workspaceBlocksCache = null;
@@ -205,7 +234,7 @@ export function createServer(client) {
         };
     });
     // ─── Write Tools ─────────────────────────────────────────────
-    server.tool("create_page", "Create a new page. Returns the created page with its ID.", {
+    server.tool("create_page", "Create a new page. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
         name: z.string().describe("Internal page name"),
         slug: z.string().describe("URL slug (e.g. 'about', 'features')"),
         parentId: z
@@ -229,7 +258,8 @@ export function createServer(client) {
             .preprocess(jsonPreprocess, z.record(z.string(), z.string()))
             .optional()
             .describe("Multilingual SEO description"),
-    }, async ({ name, slug, parentId, pageType, displayName, seoTitle, seoDescription, }) => {
+        response: responseModeSchema,
+    }, async ({ name, slug, parentId, pageType, displayName, seoTitle, seoDescription, response, }) => {
         const input = { name, slug };
         if (parentId)
             input.parentId = parentId;
@@ -244,16 +274,9 @@ export function createServer(client) {
         const data = await client.query(SAVE_PAGE_MUTATION, {
             input,
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.savePage, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.savePage, pageMinimal);
     });
-    server.tool("update_page_blocks", "Set the full content blocks array on a page. Replaces all existing content blocks. Block types are validated against workspace config. Blocks with matching IDs preserve their existing content/settings when not explicitly provided.", {
+    server.tool("update_page_blocks", "Set the full content blocks array on a page. Replaces all existing content blocks. Block types are validated against workspace config. Blocks with matching IDs preserve their existing content/settings when not explicitly provided. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
         pageId: z.string().describe("Page ID"),
         blocks: z.preprocess(jsonPreprocess, z
             .array(z.object({
@@ -273,7 +296,8 @@ export function createServer(client) {
             blockVersion: z.string().optional(),
         }))
             .describe("Full array of content blocks to set on the page")),
-    }, async ({ pageId, blocks }) => {
+        response: responseModeSchema,
+    }, async ({ pageId, blocks, response }) => {
         // Validate all block types against workspace registry
         const validation = await validateBlockTypes(blocks.map((b) => b.type));
         if (!validation.valid) {
@@ -320,16 +344,9 @@ export function createServer(client) {
                 blocks: mergedBlocks,
             },
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.savePage, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.savePage, pageMinimal);
     });
-    server.tool("update_page_settings", "Update page metadata: name, slug, display name, SEO fields", {
+    server.tool("update_page_settings", "Update page metadata: name, slug, display name, SEO fields. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
         id: z.string().describe("Page ID"),
         name: z.string().optional().describe("Internal page name"),
         slug: z.string().optional().describe("URL slug"),
@@ -346,7 +363,8 @@ export function createServer(client) {
             .optional()
             .describe("Multilingual SEO description"),
         seoKeywords: z.array(z.string()).optional().describe("SEO keywords"),
-    }, async ({ id, name, slug, displayName, seoTitle, seoDescription, seoKeywords, }) => {
+        response: responseModeSchema,
+    }, async ({ id, name, slug, displayName, seoTitle, seoDescription, seoKeywords, response, }) => {
         const input = { id };
         if (name !== undefined)
             input.name = name;
@@ -361,16 +379,12 @@ export function createServer(client) {
         if (seoKeywords !== undefined)
             input.seoKeywords = seoKeywords;
         const data = await client.query(UPDATE_PAGE_SETTINGS_MUTATION, { input });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.updatePageSettings, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.updatePageSettings, pageMinimal);
     });
-    server.tool("publish_page", "Publish a page or re-publish with latest draft changes. Uses atomic publishPage mutation.", { pageId: z.string().describe("Page ID to publish") }, async ({ pageId }) => {
+    server.tool("publish_page", "Publish a page or re-publish with latest draft changes. Uses atomic publishPage mutation. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
+        pageId: z.string().describe("Page ID to publish"),
+        response: responseModeSchema,
+    }, async ({ pageId, response }) => {
         const pageData = await client.query(PAGE_BY_ID_QUERY, { pageId });
         if (!pageData.page) {
             return {
@@ -402,16 +416,12 @@ export function createServer(client) {
             blockVersion: b.blockVersion,
         }));
         const data = await client.query(PUBLISH_PAGE_MUTATION, { id: pageId, blocks });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.publishPage, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.publishPage, (p) => pageMinimal(p, { published: true }));
     });
-    server.tool("unpublish_page", "Unpublish a published page (toggles published state off).", { pageId: z.string().describe("Page ID to unpublish") }, async ({ pageId }) => {
+    server.tool("unpublish_page", "Unpublish a published page (toggles published state off). Returns a minimal ack by default; pass response='full' for the full mutation response.", {
+        pageId: z.string().describe("Page ID to unpublish"),
+        response: responseModeSchema,
+    }, async ({ pageId, response }) => {
         const pageData = await client.query(PAGE_BY_ID_QUERY, { pageId });
         if (!pageData.page) {
             return {
@@ -427,16 +437,12 @@ export function createServer(client) {
             };
         }
         const data = await client.query(TOGGLE_PUBLISH_MUTATION, { id: pageId });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.togglePublish, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.togglePublish, (p) => pageMinimal(p, { published: false }));
     });
-    server.tool("revert_to_published", "Discard all draft changes and revert a page to its last published version.", { pageId: z.string().describe("Page ID to revert") }, async ({ pageId }) => {
+    server.tool("revert_to_published", "Discard all draft changes and revert a page to its last published version. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
+        pageId: z.string().describe("Page ID to revert"),
+        response: responseModeSchema,
+    }, async ({ pageId, response }) => {
         const data = await client.query(REVERT_TO_PUBLISHED_MUTATION, { id: pageId });
         if (!data.revertToPublished) {
             return {
@@ -449,14 +455,7 @@ export function createServer(client) {
                 isError: true,
             };
         }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.revertToPublished, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.revertToPublished, pageMinimal);
     });
     server.tool("delete_page", "Permanently delete a page and all its descendants. Cannot delete the homepage.", { pageId: z.string().describe("Page ID to delete") }, async ({ pageId }) => {
         const data = await client.query(REMOVE_PAGE_MUTATION, { id: pageId });
@@ -472,7 +471,7 @@ export function createServer(client) {
         };
     });
     // ─── Layout Tools ──────────────────────────────────────────
-    server.tool("update_page_layout", "Update page-level layout settings: inheritance, overrides, or replace all layout blocks. Block types are validated against workspace config.", {
+    server.tool("update_page_layout", "Update page-level layout settings: inheritance, overrides, or replace all layout blocks. Block types are validated against workspace config. Returns a minimal ack by default; pass response='full' for the full mutation response.", {
         pageId: z.string().describe("Page ID"),
         layoutBlocks: z
             .array(z.record(z.string(), z.unknown()))
@@ -490,7 +489,8 @@ export function createServer(client) {
             .boolean()
             .optional()
             .describe("Whether this page inherits layout from parent"),
-    }, async ({ pageId, layoutBlocks, layoutOverrides, inheritsLayout }) => {
+        response: responseModeSchema,
+    }, async ({ pageId, layoutBlocks, layoutOverrides, inheritsLayout, response, }) => {
         // Validate block types against workspace registry
         if (layoutBlocks) {
             const types = layoutBlocks
@@ -541,17 +541,10 @@ export function createServer(client) {
                 isError: true,
             };
         }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.updatePageLayout, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.updatePageLayout, pageMinimal);
     });
     // ─── Block Helper Tools (read-modify-write) ─────────────────
-    server.tool("add_block_to_page", "Add a block to a page. Automatically detects layout vs content block from workspace config. Auto-generates UUID and translation status.", {
+    server.tool("add_block_to_page", "Add a block to a page. Automatically detects layout vs content block from workspace config. Auto-generates UUID and translation status. Returns a minimal ack by default ({pageId, blockId, hasUnpublishedChanges, updatedAt}); pass response='full' for the full mutation response.", {
         pageId: z.string().describe("Page ID"),
         block: z.preprocess(jsonPreprocess, z.object({
             type: z
@@ -567,7 +560,8 @@ export function createServer(client) {
             .number()
             .optional()
             .describe("0-based position to insert at (default: end)"),
-    }, async ({ pageId, block, position }) => {
+        response: responseModeSchema,
+    }, async ({ pageId, block, position, response }) => {
         // Validate block type against workspace registry
         const blockDef = await findBlockDef(block.type);
         if (!blockDef) {
@@ -627,14 +621,18 @@ export function createServer(client) {
             };
             const layoutBlocks = [...existingLayoutBlocks, newLayoutBlock];
             const data = await client.query(UPDATE_PAGE_LAYOUT_MUTATION, { input: { pageId, layoutBlocks } });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ blockId: newBlockId, page: data.updatePageLayout }, null, 2),
-                    },
-                ],
-            };
+            if (!data.updatePageLayout) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to update layout while adding block to page '${pageId}'`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return jsonText(response, { blockId: newBlockId, page: data.updatePageLayout }, () => pageBlockMinimal(data.updatePageLayout, newBlockId));
         }
         else {
             // Content block — add to blocks via savePage
@@ -665,24 +663,18 @@ export function createServer(client) {
                     blocks,
                 },
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ blockId: newBlockId, page: data.savePage }, null, 2),
-                    },
-                ],
-            };
+            return jsonText(response, { blockId: newBlockId, page: data.savePage }, () => pageBlockMinimal(data.savePage, newBlockId));
         }
     });
-    server.tool("update_block_content", "Update a specific block's content on a page. Merges with existing content. Works for both content and layout blocks.", {
+    server.tool("update_block_content", "Update a specific block's content on a page. Merges with existing content. Works for both content and layout blocks. Returns a minimal ack by default ({pageId, blockId, hasUnpublishedChanges, updatedAt}); pass response='full' for the full mutation response.", {
         pageId: z.string().describe("Page ID"),
         blockId: z.string().describe("Block instance ID (UUID) to update"),
         content: z
             .record(z.string(), z.unknown())
             .describe("Content to merge: { en: { title: 'New Title' } }"),
         settings: z.record(z.string(), z.unknown()).optional(),
-    }, async ({ pageId, blockId, content, settings }) => {
+        response: responseModeSchema,
+    }, async ({ pageId, blockId, content, settings, response }) => {
         // Fetch current page
         const pageData = await client.query(PAGE_BY_ID_QUERY, { pageId });
         if (!pageData.page) {
@@ -748,14 +740,18 @@ export function createServer(client) {
         targetArray[targetIndex] = existingBlock;
         if (isLayout) {
             const data = await client.query(UPDATE_PAGE_LAYOUT_MUTATION, { input: { pageId, layoutBlocks: targetArray } });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(data.updatePageLayout, null, 2),
-                    },
-                ],
-            };
+            if (!data.updatePageLayout) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to update layout while editing block '${blockId}' on page '${pageId}'`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return jsonText(response, data.updatePageLayout, (p) => pageBlockMinimal(p, blockId));
         }
         else {
             const data = await client.query(SAVE_PAGE_MUTATION, {
@@ -767,20 +763,119 @@ export function createServer(client) {
                     blocks: targetArray,
                 },
             });
+            return jsonText(response, data.savePage, (p) => pageBlockMinimal(p, blockId));
+        }
+    });
+    server.tool("patch_block_content", "Apply surgical HTML edits (insert_before/insert_after/replace_section) to a block's localized content string (e.g. a docs-article HTML body) without re-sending the full content. Use this for small edits where you have a unique anchor substring in the existing HTML - it's ~10x cheaper in tokens than update_block_content and rejects any op whose marker is missing or ambiguous. For replace_section: startMarker is inclusive, endMarker is exclusive.", {
+        pageId: z.string().describe("Page ID"),
+        blockId: z
+            .string()
+            .describe("Block instance ID (UUID) on the page. Layout blocks (header/footer) aren't supported - use update_block_content for those."),
+        locale: z
+            .string()
+            .describe("Language code matching the workspace's enabledLanguages (e.g. 'en', 'pl', 'zh'). Check get_site_config first if unsure."),
+        fieldPath: z
+            .string()
+            .optional()
+            .describe("Field inside content[locale] to patch (default: 'content', the HTML body of docs-article blocks). Must resolve to a string."),
+        // `jsonPreprocess` matches the other tools in this file that accept
+        // complex inputs - MCP clients sometimes JSON-serialize nested
+        // arrays/objects instead of passing raw JSON. Without the preprocess
+        // those clients fail validation before the handler ever runs.
+        operations: z.preprocess(jsonPreprocess, z
+            .array(
+        // Discriminated on `op` so clients can't pass e.g. `insert_before`
+        // with a `startMarker` - the backend would reject, but it's
+        // cleaner (and cheaper) to fail at MCP boundary.
+        z
+            .discriminatedUnion("op", [
+            z
+                .object({
+                op: z
+                    .literal("insert_before")
+                    .describe("Insert html immediately before `marker`"),
+                marker: z
+                    .string()
+                    .describe("Unique anchor substring. Must match exactly one location in the field (zero or multiple → error)."),
+                html: z.string().describe("HTML fragment to insert"),
+            })
+                .strict(),
+            z
+                .object({
+                op: z
+                    .literal("insert_after")
+                    .describe("Insert html immediately after `marker`"),
+                marker: z
+                    .string()
+                    .describe("Unique anchor substring. Must match exactly one location in the field (zero or multiple → error)."),
+                html: z.string().describe("HTML fragment to insert"),
+            })
+                .strict(),
+            z
+                .object({
+                op: z
+                    .literal("replace_section")
+                    .describe("Replace everything from startMarker (inclusive) up to endMarker (exclusive)"),
+                startMarker: z
+                    .string()
+                    .describe("Inclusive lower bound. Must match exactly one location."),
+                endMarker: z
+                    .string()
+                    .describe("Exclusive upper bound. Must appear exactly once after startMarker."),
+                html: z
+                    .string()
+                    .describe("HTML fragment to replace the section with"),
+            })
+                .strict(),
+        ])
+            .describe("A single patch op. Ops apply in order; any failure aborts the whole patch (no half-applied state)."))
+            .min(1)
+            .describe("Ordered list of patch operations. Apply smallest first - each op must still find its markers in the string after previous ops have applied.")),
+    }, async ({ pageId, blockId, locale, fieldPath, operations }) => {
+        // Zod's discriminatedUnion + .strict() already shapes each op
+        // exactly like the backend's PatchOperationInput (insert_*: op,
+        // marker, html; replace_section: op, startMarker, endMarker, html).
+        // Pass the array straight through - a manual map here is both
+        // redundant AND unsafe (a switch without an exhaustiveness check
+        // could return undefined on an unexpected op, which would then
+        // serialize as null in the mutation variables and blow up server-side
+        // with a hard-to-trace error).
+        const data = await client.query(PATCH_BLOCK_CONTENT_MUTATION, {
+            input: {
+                pageId,
+                blockId,
+                locale,
+                ...(fieldPath ? { fieldPath } : {}),
+                operations,
+            },
+        });
+        if (!data.patchBlockContent) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(data.savePage, null, 2),
+                        text: "Page not found or patch failed",
                     },
                 ],
+                isError: true,
             };
         }
+        // Compact JSON: patch_block_content is ack-only (no pretty-print
+        // needed), matching the compact shape used by minimal-mode returns.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.patchBlockContent),
+                },
+            ],
+        };
     });
-    server.tool("remove_block_from_page", "Remove a specific block from a page by its instance ID. Works for both content and layout blocks.", {
+    server.tool("remove_block_from_page", "Remove a specific block from a page by its instance ID. Works for both content and layout blocks. Returns a minimal ack by default ({pageId, blockId, hasUnpublishedChanges, updatedAt}); pass response='full' for the full mutation response.", {
         pageId: z.string().describe("Page ID"),
         blockId: z.string().describe("Block instance ID (UUID) to remove"),
-    }, async ({ pageId, blockId }) => {
+        response: responseModeSchema,
+    }, async ({ pageId, blockId, response }) => {
         const pageData = await client.query(PAGE_BY_ID_QUERY, { pageId });
         if (!pageData.page) {
             return {
@@ -801,27 +896,24 @@ export function createServer(client) {
                     blocks: contentBlocks,
                 },
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(data.savePage, null, 2),
-                    },
-                ],
-            };
+            return jsonText(response, data.savePage, (p) => pageBlockMinimal(p, blockId));
         }
         // Try layout blocks
         const layoutBlocks = (page.layoutBlocks || []).filter((b) => b.id !== blockId);
         if (layoutBlocks.length < (page.layoutBlocks || []).length) {
             const data = await client.query(UPDATE_PAGE_LAYOUT_MUTATION, { input: { pageId, layoutBlocks } });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(data.updatePageLayout, null, 2),
-                    },
-                ],
-            };
+            if (!data.updatePageLayout) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to update layout while removing block '${blockId}' from page '${pageId}'`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return jsonText(response, data.updatePageLayout, (p) => pageBlockMinimal(p, blockId));
         }
         return {
             content: [
@@ -877,7 +969,7 @@ export function createServer(client) {
             ],
         };
     });
-    server.tool("create_form", "Create a new form with fields and settings. Returns the created form.", {
+    server.tool("create_form", "Create a new form with fields and settings. Returns a minimal ack by default; pass response='full' for the full form.", {
         name: z.string().describe("Form name"),
         slug: z.string().describe("URL-friendly slug (must be unique)"),
         description: z.string().optional().describe("Form description"),
@@ -960,7 +1052,8 @@ export function createServer(client) {
         }))
             .optional()
             .describe("Form settings (action type, notifications, etc.)"),
-    }, async ({ name, slug, description, fields, settings }) => {
+        response: responseModeSchema,
+    }, async ({ name, slug, description, fields, settings, response }) => {
         const input = { name, slug };
         if (description)
             input.description = description;
@@ -969,16 +1062,9 @@ export function createServer(client) {
         if (settings)
             input.settings = settings;
         const data = await client.query(CREATE_FORM_MUTATION, { input });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.createForm, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.createForm, formMinimal);
     });
-    server.tool("update_form", "Update an existing form's name, slug, status, fields, or settings.", {
+    server.tool("update_form", "Update an existing form's name, slug, status, fields, or settings. Returns a minimal ack by default; pass response='full' for the full form.", {
         formId: z.string().describe("Form ID to update"),
         name: z.string().optional().describe("New form name"),
         slug: z.string().optional().describe("New slug"),
@@ -1058,7 +1144,8 @@ export function createServer(client) {
         }))
             .optional()
             .describe("Updated settings"),
-    }, async ({ formId, name, slug, description, status, fields, settings }) => {
+        response: responseModeSchema,
+    }, async ({ formId, name, slug, description, status, fields, settings, response, }) => {
         const input = {};
         if (name !== undefined)
             input.name = name;
@@ -1081,14 +1168,7 @@ export function createServer(client) {
                 isError: true,
             };
         }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(data.updateForm, null, 2),
-                },
-            ],
-        };
+        return jsonText(response, data.updateForm, formMinimal);
     });
     server.tool("delete_form", "Permanently delete a form and all its submissions.", {
         formId: z.string().describe("Form ID to delete"),
@@ -1181,6 +1261,468 @@ export function createServer(client) {
             ],
         };
     });
+    // ─── Model Tools (Custom Data Models) ────────────────────────
+    const propertyFieldTypes = [
+        "string",
+        "richtext",
+        "number",
+        "boolean",
+        "date",
+        "datetime",
+        "email",
+        "url",
+        "media",
+        "relation",
+        "select",
+        "multiselect",
+        "object",
+        "list",
+    ];
+    const relationTypes = ["hasOne", "hasMany", "manyToMany"];
+    const propertyFieldSchema = z.lazy(() => z.object({
+        key: z.string().describe("Field key (identifier in record data)"),
+        label: z.string().describe("Human-readable field label"),
+        type: z
+            .enum(propertyFieldTypes)
+            .describe("Field type — controls validation + UI"),
+        required: z.boolean().optional(),
+        description: z.string().optional(),
+        defaultValue: z.string().optional(),
+        options: z
+            .array(z.string())
+            .optional()
+            .describe("For select/multiselect: allowed values"),
+        fields: z
+            .array(propertyFieldSchema)
+            .optional()
+            .describe("For type=object: nested fields"),
+        itemType: z
+            .enum(propertyFieldTypes)
+            .optional()
+            .describe("For type=list: item type"),
+        itemFields: z
+            .array(propertyFieldSchema)
+            .optional()
+            .describe("For type=list of objects: nested field defs"),
+        relationTo: z
+            .string()
+            .optional()
+            .describe("For type=relation: target model slug"),
+        relationType: z.enum(relationTypes).optional(),
+        acceptedTypes: z
+            .array(z.enum(mediaTypeValues))
+            .optional()
+            .describe("For type=media: allowed media kinds (empty = all)"),
+        multiple: z
+            .boolean()
+            .optional()
+            .describe("For type=media: true = gallery, false = single"),
+        schemaProperty: z.string().optional(),
+        minLength: z.number().int().optional(),
+        maxLength: z.number().int().optional(),
+        minValue: z.number().optional(),
+        maxValue: z.number().optional(),
+        pattern: z.string().optional(),
+    }));
+    const statusFieldSchema = z.object({
+        enabled: z.boolean().optional(),
+        values: z
+            .array(z.string())
+            .optional()
+            .describe("Allowed status values (e.g. ['draft','active'])"),
+        defaultValue: z.string().optional(),
+        transitions: z
+            .array(z.object({
+            from: z.string(),
+            to: z.array(z.string()),
+        }))
+            .optional()
+            .describe("Allowed transitions: from one state to a set of states"),
+    });
+    const defaultSortSchema = z.object({
+        field: z.string(),
+        direction: z.enum(["asc", "desc"]),
+    });
+    const OBJECT_ID_RE = /^[a-f0-9]{24}$/i;
+    // Match backend: apps/backend/src/models/model-definition.ts
+    const SLUG_RE = /^[a-z][a-z0-9-]*$/;
+    const SLUG_MSG = "Slug must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens";
+    server.tool("list_models", "List all Custom Data Models (ModelDefinition) in the workspace.", {}, async () => {
+        const data = await client.query(MODEL_DEFINITIONS_QUERY);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.modelDefinitions, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("get_model", "Get a ModelDefinition by id (24-hex ObjectId) or by slug. Returns full definition including fields, statusField, and defaultSort.", {
+        idOrSlug: z.string().describe("Model id (ObjectId) or slug"),
+    }, async ({ idOrSlug }) => {
+        if (OBJECT_ID_RE.test(idOrSlug)) {
+            const data = await client.query(MODEL_DEFINITION_BY_ID_QUERY, { id: idOrSlug });
+            if (data.modelDefinition) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(data.modelDefinition, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        // Fallback: resolve slug → id via a lightweight list (id + slug only),
+        // then fetch the full definition for that single model. Avoids
+        // pulling every model's fields when only one is needed.
+        const index = await client.query(MODEL_DEFINITIONS_BY_SLUG_INDEX_QUERY);
+        const match = index.modelDefinitions.find((m) => m.slug === idOrSlug);
+        if (!match) {
+            return {
+                content: [
+                    { type: "text", text: `Model '${idOrSlug}' not found` },
+                ],
+                isError: true,
+            };
+        }
+        const full = await client.query(MODEL_DEFINITION_BY_ID_QUERY, { id: match.id });
+        if (!full.modelDefinition) {
+            return {
+                content: [
+                    { type: "text", text: `Model '${idOrSlug}' not found` },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(full.modelDefinition, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_model", "Create a new Custom Data Model (ModelDefinition). Returns a minimal ack by default; pass response='full' for the full model.", {
+        name: z.string().describe("Display name"),
+        slug: z
+            .string()
+            .trim()
+            .regex(SLUG_RE, SLUG_MSG)
+            .describe("URL-safe slug, lowercase (regex: ^[a-z][a-z0-9-]*$)"),
+        description: z.string().optional(),
+        icon: z
+            .string()
+            .optional()
+            .describe("Lucide icon name, defaults to 'database'"),
+        color: z.string().optional(),
+        displayField: z
+            .string()
+            .optional()
+            .describe("Field key used as the record's display label in UI"),
+        defaultSort: z.preprocess(jsonPreprocess, defaultSortSchema).optional(),
+        fields: z
+            .preprocess(jsonPreprocess, z.array(propertyFieldSchema))
+            .optional()
+            .describe("Field definitions. Validates record data on write."),
+        statusField: z
+            .preprocess(jsonPreprocess, statusFieldSchema)
+            .optional()
+            .describe("Enable record lifecycle states with allowed transitions"),
+        response: responseModeSchema,
+    }, async ({ name, slug, description, icon, color, displayField, defaultSort, fields, statusField, response, }) => {
+        const input = { name, slug };
+        if (description !== undefined)
+            input.description = description;
+        if (icon !== undefined)
+            input.icon = icon;
+        if (color !== undefined)
+            input.color = color;
+        if (displayField !== undefined)
+            input.displayField = displayField;
+        if (defaultSort !== undefined)
+            input.defaultSort = defaultSort;
+        if (fields !== undefined)
+            input.fields = fields;
+        if (statusField !== undefined)
+            input.statusField = statusField;
+        const data = await client.query(CREATE_MODEL_DEFINITION_MUTATION, { input });
+        return jsonText(response, data.createModelDefinition, modelMinimal);
+    });
+    server.tool("update_model", "Update any field of an existing ModelDefinition. Changing 'fields' migrates the schema - existing records are re-validated on next write. Returns a minimal ack by default; pass response='full' for the full model.", {
+        id: z.string().describe("Model id (ObjectId) to update"),
+        name: z.string().optional(),
+        slug: z.string().trim().regex(SLUG_RE, SLUG_MSG).optional(),
+        description: z.string().optional(),
+        icon: z.string().optional(),
+        color: z.string().optional(),
+        displayField: z.string().optional(),
+        defaultSort: z.preprocess(jsonPreprocess, defaultSortSchema).optional(),
+        fields: z
+            .preprocess(jsonPreprocess, z.array(propertyFieldSchema))
+            .optional(),
+        statusField: z.preprocess(jsonPreprocess, statusFieldSchema).optional(),
+        response: responseModeSchema,
+    }, async (args) => {
+        const input = { id: args.id };
+        for (const key of [
+            "name",
+            "slug",
+            "description",
+            "icon",
+            "color",
+            "displayField",
+            "defaultSort",
+            "fields",
+            "statusField",
+        ]) {
+            if (args[key] !== undefined)
+                input[key] = args[key];
+        }
+        const data = await client.query(UPDATE_MODEL_DEFINITION_MUTATION, { input });
+        if (!data.updateModelDefinition) {
+            return {
+                content: [{ type: "text", text: "Model not found" }],
+                isError: true,
+            };
+        }
+        return jsonText(args.response, data.updateModelDefinition, modelMinimal);
+    });
+    server.tool("delete_model", "Delete a ModelDefinition. WARNING: cascades - ALL records of this model are deleted.", {
+        id: z.string().describe("Model id (ObjectId) to delete"),
+    }, async ({ id }) => {
+        const data = await client.query(DELETE_MODEL_DEFINITION_MUTATION, { id });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: data.deleteModelDefinition
+                        ? "Model deleted (records cascaded)"
+                        : "Failed to delete model",
+                },
+            ],
+            isError: !data.deleteModelDefinition,
+        };
+    });
+    server.tool("list_records", "List records of a model with filter, sort, and pagination. Filter is a MongoDB-style plain object. Sort is a string (e.g. '-createdAt' for desc). Populate loads relations by field key.", {
+        modelId: z.string().describe("Target model id (ObjectId)"),
+        filter: z
+            .preprocess(jsonPreprocess, z.record(z.string(), z.unknown()))
+            .optional()
+            .describe("Plain object filter, e.g. {status: 'active'}"),
+        limit: z.number().int().optional().default(50),
+        offset: z.number().int().optional().default(0),
+        sort: z
+            .string()
+            .optional()
+            .describe("Sort expression, e.g. 'createdAt' or '-updatedAt'"),
+        populate: z
+            .array(z.string())
+            .optional()
+            .describe("Field keys of type=relation to populate"),
+    }, async ({ modelId, filter, limit, offset, sort, populate }) => {
+        const data = await client.query(MODEL_RECORDS_QUERY, {
+            modelId,
+            filter,
+            limit,
+            offset,
+            sort,
+            populate,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.modelRecords, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("get_record", "Get a single record by id.", {
+        id: z.string().describe("Record id (ObjectId)"),
+    }, async ({ id }) => {
+        const data = await client.query(MODEL_RECORD_BY_ID_QUERY, { id });
+        if (!data.modelRecord) {
+            return {
+                content: [{ type: "text", text: "Record not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.modelRecord, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_record", "Create a new record in a model. Data keys must match field keys of the model; backend validates against the ModelDefinition. Returns a minimal ack by default; pass response='full' for the full record.", {
+        modelId: z.string().describe("Target model id (ObjectId)"),
+        data: z
+            .preprocess(jsonPreprocess, z.record(z.string(), z.unknown()))
+            .describe("Record data keyed by model field keys"),
+        response: responseModeSchema,
+    }, async ({ modelId, data: recordData, response }) => {
+        const result = await client.query(CREATE_MODEL_RECORD_MUTATION, {
+            input: { modelId, data: recordData },
+        });
+        return jsonText(response, result.createModelRecord, recordMinimal);
+    });
+    server.tool("update_record", "Update a record. Pass 'data' for a full data replace. Pass 'status' to transition the record's status (validated against statusField.transitions). At least one of data/status is required. Returns a minimal ack by default; pass response='full' for the full record.", {
+        id: z.string().describe("Record id (ObjectId)"),
+        data: z
+            .preprocess(jsonPreprocess, z.record(z.string(), z.unknown()))
+            .optional()
+            .describe("New data (full replace)"),
+        status: z
+            .string()
+            .optional()
+            .describe("New status value (must be allowed by model.statusField)"),
+        response: responseModeSchema,
+    }, async ({ id, data: recordData, status, response }) => {
+        if (recordData === undefined && status === undefined) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide 'data' and/or 'status' to update",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        let dataResult = null;
+        let statusResult = null;
+        if (recordData !== undefined) {
+            const res = await client.query(UPDATE_MODEL_RECORD_MUTATION, {
+                input: { id, data: recordData },
+            });
+            dataResult = res.updateModelRecord;
+            if (!dataResult) {
+                return {
+                    content: [{ type: "text", text: "Record not found" }],
+                    isError: true,
+                };
+            }
+        }
+        if (status !== undefined) {
+            // Data update (if any) already committed. Wrap status call so a
+            // failed transition reports partial-success clearly instead of
+            // hiding the completed data write behind a bare throw.
+            try {
+                const res = await client.query(UPDATE_MODEL_RECORD_STATUS_MUTATION, {
+                    input: { id, status },
+                });
+                statusResult = res.updateModelRecordStatus;
+                if (!statusResult) {
+                    if (dataResult) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        partialSuccess: true,
+                                        message: "Data updated, but record not found when applying status.",
+                                        dataResult,
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: "Record not found" }],
+                        isError: true,
+                    };
+                }
+            }
+            catch (error) {
+                if (dataResult) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    partialSuccess: true,
+                                    message: "Data updated, but status transition failed. Retry status only.",
+                                    dataResult,
+                                    statusError: error instanceof Error ? error.message : String(error),
+                                }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                throw error;
+            }
+        }
+        const finalResult = (statusResult ?? dataResult);
+        return jsonText(response, finalResult, recordMinimal);
+    });
+    server.tool("delete_record", "Delete a record permanently.", {
+        id: z.string().describe("Record id (ObjectId) to delete"),
+    }, async ({ id }) => {
+        const data = await client.query(DELETE_MODEL_RECORD_MUTATION, { id });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: data.deleteModelRecord
+                        ? "Record deleted"
+                        : "Failed to delete record",
+                },
+            ],
+            isError: !data.deleteModelRecord,
+        };
+    });
+    server.tool("import_records", "Bulk import records into a model. Accepts up to 1000 rows as plain objects. Returns { importedCount, errors[{row, message}] } - same shape as CSV/XLSX import.", {
+        modelId: z.string().describe("Target model id (ObjectId)"),
+        rows: z
+            .preprocess(jsonPreprocess, z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1, "Provide at least 1 row")
+            .max(1000, "Maximum 1000 rows per import"))
+            .describe("Array of plain objects keyed by model field keys"),
+    }, async ({ modelId, rows }) => {
+        const data = await client.query(IMPORT_MODEL_RECORDS_MUTATION, { input: { modelId, rows } });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.importModelRecords, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("list_model_templates", "List available model templates (E-commerce, Blog, etc.). Each template installs one or more ModelDefinitions.", {}, async () => {
+        const data = await client.query(MODEL_TEMPLATES_QUERY);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.modelTemplates, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_model_from_template", "Install a model template into the workspace. Creates all models defined by the template; skips any whose slug already exists. Returns { templateId, installedCount, skippedSlugs }.", {
+        templateId: z
+            .string()
+            .describe("Template id (from list_model_templates)"),
+    }, async ({ templateId }) => {
+        const data = await client.query(INSTALL_MODEL_TEMPLATE_MUTATION, { templateId });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.installModelTemplate, null, 2),
+                },
+            ],
+        };
+    });
     // ─── Resources ───────────────────────────────────────────────
     server.resource("sitemap", "cmssy://sitemap", {
         description: "Full page tree as JSON — all pages with hierarchy",