@cmssy/mcp-server 0.10.0 → 0.16.0

package/dist/server.js

@@ -3,7 +3,9 @@ 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";
+import { createRecordTool, createDiscountTool, createPageTool, createFormTool, createModelTool, updateModelTool, updateRecordTool, } from "@cmssy/ai-tools";
+import { createMcpWorkspaceOps } from "./ai-tools-ops.js";
+import { bindSharedTool } from "./ai-tools-binder.js";
 // 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.
@@ -34,13 +36,14 @@ const jsonPreprocess = (val) => {
         return val;
     }
 };
-import { PAGES_QUERY, PAGE_BY_ID_QUERY, SITE_CONFIG_QUERY, CURRENT_WORKSPACE_QUERY, MEDIA_ASSETS_QUERY, SAVE_PAGE_MUTATION, PATCH_BLOCK_CONTENT_MUTATION, UPDATE_PAGE_SETTINGS_MUTATION, PAGE_TYPES_QUERY, CREATE_PAGE_TYPE_MUTATION, TOGGLE_PUBLISH_MUTATION, PUBLISH_PAGE_CONTENT_MUTATION, PUBLISH_PAGE_LAYOUT_MUTATION, REVERT_CONTENT_TO_PUBLISHED_MUTATION, REVERT_LAYOUT_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, 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, } from "./queries.js";
-import { responseModeSchema, pageMinimal, pageBlockMinimal, formMinimal, modelMinimal, recordMinimal, jsonText, } from "./responses.js";
+import { PAGES_QUERY, PAGE_BY_ID_QUERY, SITE_CONFIG_QUERY, CURRENT_WORKSPACE_QUERY, MEDIA_ASSETS_QUERY, SAVE_PAGE_MUTATION, PATCH_BLOCK_CONTENT_MUTATION, UPDATE_PAGE_SETTINGS_MUTATION, PAGE_TYPES_QUERY, CREATE_PAGE_TYPE_MUTATION, TOGGLE_PUBLISH_MUTATION, PUBLISH_PAGE_CONTENT_MUTATION, PUBLISH_PAGE_LAYOUT_MUTATION, REVERT_CONTENT_TO_PUBLISHED_MUTATION, REVERT_LAYOUT_TO_PUBLISHED_MUTATION, REMOVE_PAGE_MUTATION, UPDATE_PAGE_LAYOUT_MUTATION, FORMS_QUERY, FORM_BY_ID_QUERY, FORM_SUBMISSIONS_QUERY, FORM_SUBMISSION_BY_ID_QUERY, 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, DELETE_MODEL_DEFINITION_MUTATION, DELETE_MODEL_RECORD_MUTATION, IMPORT_MODEL_RECORDS_MUTATION, ORDERS_QUERY, ORDER_BY_ID_QUERY, ORDER_PIPELINE_QUERY, CREATE_MANUAL_ORDER_MUTATION, EDIT_ORDER_MUTATION, UPDATE_ORDER_DETAILS_MUTATION, MARK_ORDER_PAID_MUTATION, RECORD_ORDER_PAYMENT_MUTATION, REFUND_ORDER_MUTATION, CANCEL_ORDER_MUTATION, TRANSITION_ORDER_FULFILLMENT_MUTATION, SET_ORDER_PIPELINE_STAGE_MUTATION, RECORD_ORDER_INVOICE_MUTATION, ADMIN_CARTS_QUERY, DISCOUNTS_QUERY, DISCOUNT_BY_ID_QUERY, UPDATE_DISCOUNT_MUTATION, SET_DISCOUNT_ENABLED_MUTATION, WEBHOOK_ENDPOINTS_QUERY, WEBHOOK_DELIVERIES_QUERY, WEBHOOK_EVENT_TYPES_QUERY, CREATE_WEBHOOK_ENDPOINT_MUTATION, UPDATE_WEBHOOK_ENDPOINT_MUTATION, ROTATE_WEBHOOK_SECRET_MUTATION, DELETE_WEBHOOK_ENDPOINT_MUTATION, PRODUCT_CATALOG_QUERY, BULK_UPDATE_PRODUCT_RECORDS_MUTATION, BULK_DELETE_PRODUCT_RECORDS_MUTATION, } from "./queries.js";
+import { responseModeSchema, pageMinimal, pageBlockMinimal, formMinimal, orderMinimal, discountMinimal, jsonText, } from "./responses.js";
 export function createServer(client) {
     const server = new McpServer({
         name: "cmssy",
         version: PACKAGE_VERSION,
     });
+    const sharedOps = createMcpWorkspaceOps(client);
     /** Check if value is null, undefined, or empty object */
     const isEmpty = (obj) => obj == null ||
         (typeof obj === "object" && Object.keys(obj).length === 0);
@@ -165,54 +168,7 @@ export function createServer(client) {
         };
     });
     // ─── Write Tools ─────────────────────────────────────────────
-    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
-            .string()
-            .optional()
-            .describe("Parent page ID for nested pages"),
-        pageType: z
-            .string()
-            .optional()
-            .default("page")
-            .describe("Page type (default: 'page')"),
-        displayName: z
-            .preprocess(jsonPreprocess, z.record(z.string(), z.string()))
-            .optional()
-            .describe("Multilingual display name, e.g. { en: 'About', pl: 'O nas' }"),
-        seoTitle: z
-            .preprocess(jsonPreprocess, z.record(z.string(), z.string()))
-            .optional()
-            .describe("Multilingual SEO title"),
-        seoDescription: z
-            .preprocess(jsonPreprocess, z.record(z.string(), z.string()))
-            .optional()
-            .describe("Multilingual SEO description"),
-        customFields: z
-            .preprocess(jsonPreprocess, z.array(z.object({ fieldKey: z.string(), value: z.unknown() })))
-            .optional()
-            .describe("Custom field values for the page type's schema: [{ fieldKey, value }]. value is JSON."),
-        response: responseModeSchema,
-    }, async ({ name, slug, parentId, pageType, displayName, seoTitle, seoDescription, customFields, response, }) => {
-        const input = { name, slug };
-        if (parentId)
-            input.parentId = parentId;
-        if (pageType)
-            input.pageType = pageType;
-        if (displayName)
-            input.displayName = displayName;
-        if (seoTitle)
-            input.seoTitle = seoTitle;
-        if (seoDescription)
-            input.seoDescription = seoDescription;
-        if (customFields !== undefined)
-            input.customFields = customFields;
-        const data = await client.query(SAVE_PAGE_MUTATION, {
-            input,
-        });
-        return jsonText(response, data.savePage, pageMinimal);
-    });
+    bindSharedTool(server, createPageTool, sharedOps);
     server.tool("update_page_blocks", "Set the full content blocks array on a page. Replaces all existing content blocks. Block types are validated server-side on save. 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
@@ -341,7 +297,9 @@ export function createServer(client) {
         allowChildren: z.boolean().optional(),
         fields: z
             .preprocess(jsonPreprocess, z.array(z.object({
-            key: z.string().describe("Field key (identifier in customFields)"),
+            key: z
+                .string()
+                .describe("Field key (identifier in customFields)"),
             label: z.string().describe("Human-readable label"),
             type: z
                 .enum([
@@ -1047,101 +1005,7 @@ export function createServer(client) {
             ],
         };
     });
-    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"),
-        fields: z
-            .preprocess(jsonPreprocess, z.array(z.object({
-            id: z.string().describe("Unique field ID"),
-            name: z.string().describe("Field name (used as form data key)"),
-            fieldType: z
-                .enum([
-                "text",
-                "email",
-                "password",
-                "textarea",
-                "number",
-                "phone",
-                "url",
-                "date",
-                "datetime",
-                "select",
-                "multiselect",
-                "checkbox",
-                "radio",
-                "file",
-                "hidden",
-            ])
-                .optional()
-                .default("text"),
-            label: z
-                .record(z.string(), z.unknown())
-                .optional()
-                .describe("i18n labels: { en: 'Name', pl: 'Imię' }"),
-            placeholder: z.record(z.string(), z.unknown()).optional(),
-            helpText: z.record(z.string(), z.unknown()).optional(),
-            defaultValue: z.string().optional(),
-            validation: z
-                .object({
-                required: z.boolean().optional(),
-                minLength: z.number().optional(),
-                maxLength: z.number().optional(),
-                minValue: z.number().optional(),
-                maxValue: z.number().optional(),
-                pattern: z.string().optional(),
-                customMessage: z.string().optional(),
-            })
-                .optional(),
-            options: z
-                .array(z.object({
-                value: z.string(),
-                label: z.record(z.string(), z.unknown()).optional(),
-                disabled: z.boolean().optional(),
-            }))
-                .optional(),
-            width: z
-                .enum(["full", "half", "third"])
-                .optional()
-                .default("full"),
-            order: z.number().optional().default(0),
-            showIf: z.record(z.string(), z.unknown()).optional(),
-        })))
-            .optional()
-            .describe("Form field definitions"),
-        settings: z
-            .preprocess(jsonPreprocess, z.object({
-            actionType: z
-                .enum(["login", "register", "newsletter", "contact", "custom"])
-                .optional()
-                .default("contact"),
-            webhookUrl: z.string().optional(),
-            emailRecipients: z.array(z.string()).optional(),
-            newsletterListId: z.string().optional(),
-            submitButtonLabel: z.record(z.string(), z.unknown()).optional(),
-            successMessage: z.record(z.string(), z.unknown()).optional(),
-            errorMessage: z.record(z.string(), z.unknown()).optional(),
-            redirectUrl: z.string().optional(),
-            enableCaptcha: z.boolean().optional(),
-            requireLogin: z.boolean().optional(),
-            saveSubmissions: z.boolean().optional(),
-            sendEmailNotification: z.boolean().optional(),
-            emailConfigurationId: z.string().optional(),
-        }))
-            .optional()
-            .describe("Form settings (action type, notifications, etc.)"),
-        response: responseModeSchema,
-    }, async ({ name, slug, description, fields, settings, response }) => {
-        const input = { name, slug };
-        if (description)
-            input.description = description;
-        if (fields)
-            input.fields = fields;
-        if (settings)
-            input.settings = settings;
-        const data = await client.query(CREATE_FORM_MUTATION, { input });
-        return jsonText(response, data.createForm, formMinimal);
-    });
+    bindSharedTool(server, createFormTool, sharedOps);
     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"),
@@ -1340,91 +1204,7 @@ 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 {
@@ -1483,91 +1263,8 @@ export function createServer(client) {
             ],
         };
     });
-    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);
-    });
+    bindSharedTool(server, createModelTool, sharedOps);
+    bindSharedTool(server, updateModelTool, sharedOps);
     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 }) => {
@@ -1637,142 +1334,630 @@ export function createServer(client) {
             ],
         };
     });
-    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.", {
+    bindSharedTool(server, createRecordTool, sharedOps);
+    bindSharedTool(server, updateRecordTool, sharedOps);
+    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)"),
-        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);
+        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("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
+    // ─── Commerce: Orders ────────────────────────────────────────
+    //
+    // workspaceId is required by every commerce resolver and cross-checked
+    // against the token's workspace context, so it always comes from the
+    // client (the same value sent in the x-workspace-id header) - it is not
+    // a caller-supplied arg. All money fields are integer minor units (cents).
+    const PAYMENT_STATUS = [
+        "unpaid",
+        "partially_paid",
+        "authorized",
+        "paid",
+        "partially_refunded",
+        "refunded",
+    ];
+    const FULFILLMENT_STATUS = [
+        "unfulfilled",
+        "partially_fulfilled",
+        "fulfilled",
+        "returned",
+    ];
+    const CART_STATUS = [
+        "active",
+        "saved",
+        "quote_requested",
+        "merged",
+        "expired",
+        "abandoned",
+        "ordered",
+    ];
+    const DISCOUNT_TYPE = ["percentage", "fixed", "free_shipping"];
+    const orderItemSchema = z
+        .object({
+        recordId: z
+            .string()
+            .optional()
+            .describe("Product record id (ObjectId) the line refers to"),
+        quantity: z.number().int().positive(),
+        variantSelections: z
             .preprocess(jsonPreprocess, z.record(z.string(), z.unknown()))
             .optional()
-            .describe("New data (full replace)"),
-        status: z
+            .describe("Selected variant options, e.g. {size: 'M', color: 'red'}"),
+        name: z.string().optional().describe("Custom line name (ad-hoc item)"),
+        price: z
+            .number()
+            .int()
+            .optional()
+            .describe("Custom unit price in minor units (ad-hoc item)"),
+    })
+        .refine((item) => item.recordId != null || (item.name != null && item.price != null), {
+        message: "Each item needs a recordId, or both name and price for an ad-hoc line",
+    });
+    server.tool("list_orders", "List orders with optional filters and pagination. Money fields are integer minor units (cents). Pass pipelineStageId='__unassigned__' to list orders with no pipeline stage.", {
+        paymentStatus: z.enum(PAYMENT_STATUS).optional(),
+        fulfillmentStatus: z.enum(FULFILLMENT_STATUS).optional(),
+        customerId: z.string().optional(),
+        search: z.string().optional(),
+        pipelineStageId: z.string().optional(),
+        dateFrom: z
             .string()
             .optional()
-            .describe("New status value (must be allowed by model.statusField)"),
+            .describe("ISO date-time lower bound (inclusive)"),
+        dateTo: z
+            .string()
+            .optional()
+            .describe("ISO date-time upper bound (inclusive)"),
+        skip: z.number().int().optional().default(0),
+        limit: z.number().int().optional().default(20),
+    }, async (args) => {
+        const data = await client.query(ORDERS_QUERY, { workspaceId: client.workspaceId, ...args });
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data.orders, null, 2) },
+            ],
+        };
+    });
+    server.tool("get_order", "Get a single order by id, including items, payments, and tax summary.", {
+        id: z.string().describe("Order id"),
+    }, async ({ id }) => {
+        const data = await client.query(ORDER_BY_ID_QUERY, { workspaceId: client.workspaceId, id });
+        if (!data.order) {
+            return {
+                content: [{ type: "text", text: "Order not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data.order, null, 2) },
+            ],
+        };
+    });
+    server.tool("get_order_pipeline", "Get the workspace order pipeline (the configurable stages orders move through).", {}, async () => {
+        const data = await client.query(ORDER_PIPELINE_QUERY, { workspaceId: client.workspaceId });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.orderPipeline, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_manual_order", "Create a manual (admin-entered) order. Each item references a product recordId or is an ad-hoc line with name+price (minor units). Returns a minimal ack by default; pass response='full' for the full order.", {
+        customerEmail: z.string().describe("Customer email for the order"),
+        customerId: z.string().optional(),
+        items: z.array(orderItemSchema).min(1, "Provide at least 1 item"),
+        response: responseModeSchema,
+    }, async ({ customerEmail, customerId, items, response }) => {
+        const result = await client.query(CREATE_MANUAL_ORDER_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                customerEmail,
+                customerId,
+                items,
+            },
+        });
+        return jsonText(response, result.createManualOrder, orderMinimal);
+    });
+    server.tool("edit_order", "Replace an order's line items (full replace of the items array). Recomputes totals. Returns a minimal ack by default; pass response='full' for the full order.", {
+        orderId: z.string(),
+        items: z.array(orderItemSchema).min(1, "Provide at least 1 item"),
+        response: responseModeSchema,
+    }, async ({ orderId, items, response }) => {
+        const result = await client.query(EDIT_ORDER_MUTATION, { input: { workspaceId: client.workspaceId, orderId, items } });
+        return jsonText(response, result.editOrder, orderMinimal);
+    });
+    server.tool("update_order_details", "Update order metadata: customer email, internal notes, and shipment tracking. Only provided fields change.", {
+        orderId: z.string(),
+        customerEmail: z.string().optional(),
+        notes: z.string().optional(),
+        trackingNumber: z.string().optional(),
+        trackingCarrier: z.string().optional(),
+        response: responseModeSchema,
+    }, async ({ orderId, response, ...fields }) => {
+        if (Object.keys(fields).length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide at least one field to update",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const result = await client.query(UPDATE_ORDER_DETAILS_MUTATION, { input: { workspaceId: client.workspaceId, orderId, ...fields } });
+        return jsonText(response, result.updateOrderDetails, orderMinimal);
+    });
+    server.tool("mark_order_paid", "Record a full payment for an order (does NOT verify with a payment provider - admin/manual reconciliation). amount is in minor units.", {
+        orderId: z.string(),
+        amount: z.number().int().describe("Amount in minor units (cents)"),
+        reference: z.string().describe("Payment reference / receipt id"),
+        provider: z.string().describe("Payment provider label, e.g. 'manual'"),
+        response: responseModeSchema,
+    }, async ({ orderId, amount, reference, provider, response }) => {
+        const result = await client.query(MARK_ORDER_PAID_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                orderId,
+                amount,
+                reference,
+                provider,
+            },
+        });
+        return jsonText(response, result.markOrderPaid, orderMinimal);
+    });
+    server.tool("record_order_payment", "Record a (possibly partial) payment against an order's outstanding balance. amount is in minor units and capped at the balance due.", {
+        orderId: z.string(),
+        amount: z.number().int().describe("Amount in minor units (cents)"),
+        reference: z.string().describe("Payment reference / receipt id"),
+        provider: z.string().optional(),
+        response: responseModeSchema,
+    }, async ({ orderId, amount, reference, provider, response }) => {
+        const result = await client.query(RECORD_ORDER_PAYMENT_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                orderId,
+                amount,
+                reference,
+                provider,
+            },
+        });
+        return jsonText(response, result.recordOrderPayment, orderMinimal);
+    });
+    server.tool("refund_order", "Refund an order. Omit amount for a full refund; pass amount (minor units) for a partial refund.", {
+        orderId: z.string(),
+        reference: z.string().describe("Refund reference / receipt id"),
+        amount: z
+            .number()
+            .int()
+            .optional()
+            .describe("Partial refund amount in minor units; omit for full refund"),
+        response: responseModeSchema,
+    }, async ({ orderId, reference, amount, response }) => {
+        const result = await client.query(REFUND_ORDER_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                orderId,
+                reference,
+                amount,
+            },
+        });
+        return jsonText(response, result.refundOrder, orderMinimal);
+    });
+    server.tool("cancel_order", "Cancel an order.", {
+        orderId: z.string(),
+        response: responseModeSchema,
+    }, async ({ orderId, response }) => {
+        const result = await client.query(CANCEL_ORDER_MUTATION, { input: { workspaceId: client.workspaceId, orderId } });
+        return jsonText(response, result.cancelOrder, orderMinimal);
+    });
+    server.tool("transition_order_fulfillment", "Move an order to a new fulfillment status. Optionally attach tracking when marking fulfilled.", {
+        orderId: z.string(),
+        status: z.enum(FULFILLMENT_STATUS),
+        trackingNumber: z.string().optional(),
+        trackingCarrier: z.string().optional(),
+        response: responseModeSchema,
+    }, async ({ orderId, status, trackingNumber, trackingCarrier, response }) => {
+        const result = await client.query(TRANSITION_ORDER_FULFILLMENT_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                orderId,
+                status,
+                trackingNumber,
+                trackingCarrier,
+            },
+        });
+        return jsonText(response, result.transitionOrderFulfillment, orderMinimal);
+    });
+    server.tool("set_order_pipeline_stage", "Move an order to a pipeline stage (use get_order_pipeline for valid stage ids).", {
+        orderId: z.string(),
+        stageId: z.string(),
+        response: responseModeSchema,
+    }, async ({ orderId, stageId, response }) => {
+        const result = await client.query(SET_ORDER_PIPELINE_STAGE_MUTATION, { input: { workspaceId: client.workspaceId, orderId, stageId } });
+        return jsonText(response, result.setOrderPipelineStage, orderMinimal);
+    });
+    server.tool("record_order_invoice", "Attach an invoice (number, optional URL and provider) to an order.", {
+        orderId: z.string(),
+        number: z.string().describe("Invoice number"),
+        url: z.string().optional(),
+        provider: z.string().optional(),
+        response: responseModeSchema,
+    }, async ({ orderId, number, url, provider, response }) => {
+        const result = await client.query(RECORD_ORDER_INVOICE_MUTATION, {
+            input: {
+                workspaceId: client.workspaceId,
+                orderId,
+                number,
+                url,
+                provider,
+            },
+        });
+        return jsonText(response, result.recordOrderInvoice, orderMinimal);
+    });
+    // ─── Commerce: Carts ─────────────────────────────────────────
+    server.tool("list_carts", "List shopping carts (admin view) with optional status filter and pagination. totalValue is in minor units.", {
+        status: z.enum(CART_STATUS).optional(),
+        skip: z.number().int().optional().default(0),
+        limit: z.number().int().optional().default(20),
+    }, async (args) => {
+        const data = await client.query(ADMIN_CARTS_QUERY, { workspaceId: client.workspaceId, ...args });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.adminCarts, null, 2),
+                },
+            ],
+        };
+    });
+    // ─── Commerce: Discounts ─────────────────────────────────────
+    server.tool("list_discounts", "List discount codes with optional filters and pagination.", {
+        enabled: z.boolean().optional(),
+        type: z.enum(DISCOUNT_TYPE).optional(),
+        search: z.string().optional().describe("Substring match on code"),
+        limit: z.number().int().optional().default(25),
+        offset: z.number().int().optional().default(0),
+    }, async (args) => {
+        const data = await client.query(DISCOUNTS_QUERY, { workspaceId: client.workspaceId, ...args });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.discounts, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("get_discount", "Get a single discount by id.", {
+        id: z.string(),
+    }, async ({ id }) => {
+        const data = await client.query(DISCOUNT_BY_ID_QUERY, { workspaceId: client.workspaceId, id });
+        if (!data.discount) {
+            return {
+                content: [{ type: "text", text: "Discount not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.discount, null, 2),
+                },
+            ],
+        };
+    });
+    bindSharedTool(server, createDiscountTool, sharedOps);
+    server.tool("update_discount", "Update a discount (partial - only provided fields change). code/type/currency become immutable once the discount has been used at least once.", {
+        id: z.string(),
+        code: z.string().optional(),
+        type: z.enum(DISCOUNT_TYPE).optional(),
+        value: z.number().optional(),
+        currency: z.string().optional(),
+        minSubtotal: z.number().optional(),
+        maxUses: z.number().int().optional(),
+        maxUsesPerUser: z.number().int().optional(),
+        startsAt: z.string().optional().describe("ISO date-time"),
+        endsAt: z.string().optional().describe("ISO date-time"),
+        enabled: z.boolean().optional(),
         response: responseModeSchema,
-    }, async ({ id, data: recordData, status, response }) => {
-        if (recordData === undefined && status === undefined) {
+    }, async ({ id, response, ...input }) => {
+        if (Object.keys(input).length === 0) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: "Provide 'data' and/or 'status' to update",
+                        text: "Provide at least one field 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,
-                };
-            }
+        const result = await client.query(UPDATE_DISCOUNT_MUTATION, { workspaceId: client.workspaceId, id, input });
+        return jsonText(response, result.updateDiscount, discountMinimal);
+    });
+    server.tool("set_discount_enabled", "Enable or disable a discount code.", {
+        id: z.string(),
+        enabled: z.boolean(),
+        response: responseModeSchema,
+    }, async ({ id, enabled, response }) => {
+        const result = await client.query(SET_DISCOUNT_ENABLED_MUTATION, { workspaceId: client.workspaceId, id, enabled });
+        return jsonText(response, result.setDiscountEnabled, discountMinimal);
+    });
+    // ─── Commerce: Products (catalog over model records) ─────────
+    //
+    // Products are stored as records of a Custom Data Model. These tools add
+    // product-aware reads/writes (stock + variants) on top of the generic
+    // record tools. Money fields are integer minor units (cents).
+    const productFilterSchema = z.object({
+        search: z.string().optional(),
+        status: z.string().optional(),
+        stockState: z
+            .enum(["in", "low", "out"])
+            .optional()
+            .describe("in stock / low stock / out of stock"),
+        priceMin: z.number().optional(),
+        priceMax: z.number().optional(),
+        hasVariants: z.boolean().optional(),
+    });
+    server.tool("list_products", "List a product model's catalog with stock and variant info. modelId is the Custom Data Model holding the products. Returns CatalogItem rows (onHand/reserved/available + per-variant stock) plus the workspace lowStockThreshold.", {
+        modelId: z.string().describe("Product model id (ObjectId)"),
+        filter: productFilterSchema.optional(),
+        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'"),
+    }, async ({ modelId, filter, limit, offset, sort }) => {
+        const data = await client.query(PRODUCT_CATALOG_QUERY, { modelId, filter, limit, offset, sort });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.productCatalog, null, 2),
+                },
+            ],
+        };
+    });
+    // Selection model shared by the bulk product mutations: target an explicit
+    // list of ids, OR everything matching a filter (allMatching=true). One of
+    // the two is required by the backend.
+    const productSelectionSchema = z
+        .object({
+        ids: z
+            .array(z.string())
+            .optional()
+            .describe("Explicit record ids to target"),
+        allMatching: z
+            .boolean()
+            .optional()
+            .describe("Target every record matching filter (ignores ids)"),
+        filter: productFilterSchema.optional(),
+    })
+        .refine((s) => (s.ids?.length ?? 0) > 0 || s.allMatching === true, {
+        message: "Provide a non-empty 'ids' array or set 'allMatching: true'",
+    })
+        .describe("Provide non-empty 'ids' OR 'allMatching: true'");
+    server.tool("bulk_update_products", "Bulk-update selected product records with a single patch applied uniformly (status, set/adjust stock, set/adjust price). Stock fields are units; price fields are minor units. Returns the number of records updated.", {
+        modelId: z.string().describe("Product model id (ObjectId)"),
+        selection: productSelectionSchema,
+        patch: z
+            .object({
+            status: z.string().optional(),
+            setStock: z.number().int().optional().describe("Set absolute stock"),
+            adjustStock: z
+                .number()
+                .int()
+                .optional()
+                .describe("Delta to stock (+/-)"),
+            setPrice: z
+                .number()
+                .int()
+                .optional()
+                .describe("Set absolute price (minor units)"),
+            adjustPrice: z
+                .number()
+                .int()
+                .optional()
+                .describe("Delta to price (minor units, +/-)"),
+        })
+            .describe("Single patch applied to every selected record"),
+    }, async ({ modelId, selection, patch }) => {
+        if (Object.keys(patch).length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide at least one patch field (status, set/adjust stock or price)",
+                    },
+                ],
+                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 data = await client.query(BULK_UPDATE_PRODUCT_RECORDS_MUTATION, { modelId, selection, patch });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ updated: data.bulkUpdateProductRecords }),
+                },
+            ],
+        };
+    });
+    server.tool("bulk_delete_products", "Bulk-delete selected product records permanently. Returns the number of records deleted.", {
+        modelId: z.string().describe("Product model id (ObjectId)"),
+        selection: productSelectionSchema,
+    }, async ({ modelId, selection }) => {
+        const data = await client.query(BULK_DELETE_PRODUCT_RECORDS_MUTATION, { modelId, selection });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ deleted: data.bulkDeleteProductRecords }),
+                },
+            ],
+        };
+    });
+    // ─── Webhooks ────────────────────────────────────────────────
+    //
+    // Outbound event webhooks. Like commerce, workspaceId is required by every
+    // resolver and sourced from the client. createWebhookEndpoint and
+    // rotateWebhookSecret return the signing secret ONCE - it is surfaced in
+    // full and cannot be retrieved again.
+    server.tool("list_webhooks", "List the workspace's webhook endpoints (signing secrets are never returned here).", {}, async () => {
+        const data = await client.query(WEBHOOK_ENDPOINTS_QUERY, { workspaceId: client.workspaceId });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.webhookEndpoints, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("list_webhook_deliveries", "List recent webhook delivery attempts (status: pending/success/failed) for debugging.", {
+        limit: z.number().int().optional().default(50),
+    }, async ({ limit }) => {
+        const data = await client.query(WEBHOOK_DELIVERIES_QUERY, { workspaceId: client.workspaceId, limit });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.webhookDeliveries, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("list_webhook_event_types", "List the event types a webhook can subscribe to (the authoritative allowlist).", {}, async () => {
+        const data = await client.query(WEBHOOK_EVENT_TYPES_QUERY, { workspaceId: client.workspaceId });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.webhookEventTypes, null, 2),
+                },
+            ],
+        };
+    });
+    // The backend validates events against its allowlist; list_webhook_event_types
+    // is authoritative. These are the known values at time of writing.
+    const WEBHOOK_EVENTS_HINT = "Event names, e.g. order.created, order.paid, order.refunded, order.canceled, order.fulfilled, order.returned, order.edited, order.pipeline_changed. Use list_webhook_event_types for the authoritative list.";
+    server.tool("create_webhook", "Create a webhook endpoint subscribed to one or more events. The URL must be a public https endpoint. Returns the endpoint AND its signing secret - the secret is shown only once.", {
+        url: z.string().describe("Public https endpoint URL"),
+        events: z
+            .array(z.string())
+            .min(1, "Subscribe to at least 1 event")
+            .describe(WEBHOOK_EVENTS_HINT),
+        description: z.string().optional(),
+    }, async ({ url, events, description }) => {
+        const data = await client.query(CREATE_WEBHOOK_ENDPOINT_MUTATION, {
+            input: { workspaceId: client.workspaceId, url, events, description },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.createWebhookEndpoint, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("update_webhook", "Update a webhook endpoint (partial - only provided fields change). Pass enabled to enable/disable. Pass description=null to clear it. The signing secret is not returned.", {
+        id: z.string(),
+        url: z.string().optional(),
+        events: z
+            .array(z.string())
+            .min(1)
+            .optional()
+            .describe(WEBHOOK_EVENTS_HINT),
+        enabled: z.boolean().optional(),
+        description: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New description; null clears it"),
+    }, async ({ id, ...fields }) => {
+        if (Object.keys(fields).length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide at least one field to update",
+                    },
+                ],
+                isError: true,
+            };
         }
-        const finalResult = (statusResult ?? dataResult);
-        return jsonText(response, finalResult, recordMinimal);
+        const data = await client.query(UPDATE_WEBHOOK_ENDPOINT_MUTATION, { input: { workspaceId: client.workspaceId, id, ...fields } });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data.updateWebhookEndpoint, null, 2),
+                },
+            ],
+        };
     });
-    server.tool("delete_record", "Delete a record permanently.", {
-        id: z.string().describe("Record id (ObjectId) to delete"),
+    server.tool("rotate_webhook_secret", "Rotate a webhook endpoint's signing secret. Returns the endpoint and the NEW secret - shown only once.", {
+        id: z.string(),
     }, async ({ id }) => {
-        const data = await client.query(DELETE_MODEL_RECORD_MUTATION, { id });
+        const data = await client.query(ROTATE_WEBHOOK_SECRET_MUTATION, { workspaceId: client.workspaceId, id });
         return {
             content: [
                 {
                     type: "text",
-                    text: data.deleteModelRecord
-                        ? "Record deleted"
-                        : "Failed to delete record",
+                    text: JSON.stringify(data.rotateWebhookSecret, null, 2),
                 },
             ],
-            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 } });
+    server.tool("delete_webhook", "Delete a webhook endpoint permanently.", {
+        id: z.string(),
+    }, async ({ id }) => {
+        const data = await client.query(DELETE_WEBHOOK_ENDPOINT_MUTATION, { workspaceId: client.workspaceId, id });
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(data.importModelRecords, null, 2),
+                    text: data.deleteWebhookEndpoint
+                        ? "Webhook deleted"
+                        : "Failed to delete webhook",
                 },
             ],
+            isError: !data.deleteWebhookEndpoint,
         };
     });
     // ─── Resources ───────────────────────────────────────────────