@cmssy/mcp-server 0.5.0 → 0.7.1

package/dist/server.js

@@ -3,6 +3,7 @@ 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.
@@ -33,7 +34,8 @@ const jsonPreprocess = (val) => {
         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, } from "./queries.js";
+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",
@@ -232,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
@@ -256,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;
@@ -271,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({
@@ -300,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) {
@@ -347,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"),
@@ -373,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;
@@ -388,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 {
@@ -406,7 +393,9 @@ export function createServer(client) {
             };
         }
         const page = pageData.page;
-        if (page.published && !page.hasUnpublishedChanges) {
+        if (page.published &&
+            !page.hasUnpublishedContentChanges &&
+            !page.hasUnpublishedLayoutChanges) {
             return {
                 content: [
                     {
@@ -429,16 +418,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 {
@@ -454,16 +439,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 {
@@ -476,14 +457,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 });
@@ -499,7 +473,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()))
@@ -517,7 +491,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
@@ -568,17 +543,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
@@ -594,7 +562,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) {
@@ -654,14 +623,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
@@ -692,24 +665,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) {
@@ -775,14 +742,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, {
@@ -794,14 +765,7 @@ export function createServer(client) {
                     blocks: targetArray,
                 },
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(data.savePage, null, 2),
-                    },
-                ],
-            };
+            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.", {
@@ -898,19 +862,29 @@ export function createServer(client) {
                 isError: true,
             };
         }
+        // Compact JSON: patch_block_content is ack-only (no pretty-print
+        // needed), matching the compact shape used by minimal-mode returns.
+        const patched = data.patchBlockContent;
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(data.patchBlockContent, null, 2),
+                    text: JSON.stringify({
+                        id: patched.id,
+                        slug: patched.slug,
+                        hasUnpublishedChanges: Boolean(patched.hasUnpublishedContentChanges) ||
+                            Boolean(patched.hasUnpublishedLayoutChanges),
+                        updatedAt: patched.updatedAt,
+                    }),
                 },
             ],
         };
     });
-    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 {
@@ -931,27 +905,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: [
@@ -1007,7 +978,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"),
@@ -1090,7 +1061,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;
@@ -1099,16 +1071,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"),
@@ -1188,7 +1153,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;
@@ -1211,14 +1177,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"),
@@ -1311,6 +1270,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",