@centrali-io/centrali-mcp 4.4.6 → 4.4.8-rc.0

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server for the Centrali platform. Lets AI assistant
 
 > **Full documentation:** [docs.centrali.io](https://docs.centrali.io) — SDK guide, API reference, compute functions, orchestrations, and more.
 
-Built on `@centrali-io/centrali-sdk` v4.4.6. Authenticates via service account client credentials.
+Built on `@centrali-io/centrali-sdk` v4.4.7. Authenticates via service account client credentials.
 
 ## Setup
 
@@ -110,6 +110,7 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `get_compute_job_status` | Check async job status by job ID (poll after invoke_trigger) |
 | `list_allowed_domains` | List allowed domains for outbound HTTP |
 | `add_allowed_domain` | Add a domain to the allowlist |
+| `invoke_endpoint` | Call a sync compute endpoint by path (returns response inline) |
 | `remove_allowed_domain` | Remove a domain from the allowlist |
 
 ### Smart Queries

package/dist/index.js

@@ -51,7 +51,7 @@ function main() {
             version: "1.0.0",
         });
         // Register all tools
-        (0, structures_js_1.registerCollectionTools)(server, sdk);
+        (0, structures_js_1.registerCollectionTools)(server, sdk, baseUrl, workspaceId);
         (0, structures_js_1.registerStructureTools)(server, sdk);
         (0, records_js_1.registerRecordTools)(server, sdk);
         (0, search_js_1.registerSearchTools)(server, sdk);

package/dist/tools/auth-providers.js

@@ -37,10 +37,10 @@ function ensureToken(sdk) {
  */
 function createIamClient(sdk, centraliUrl, workspaceId) {
     const url = new URL(centraliUrl);
-    const hostname = url.hostname.startsWith("api.")
+    const hostname = url.hostname.startsWith("auth.")
         ? url.hostname
-        : `api.${url.hostname}`;
-    const baseURL = `${url.protocol}//${hostname}/iam/workspace/${workspaceId}/api/v1/external-auth-providers`;
+        : `auth.${url.hostname.replace(/^api\./, '')}`;
+    const baseURL = `${url.protocol}//${hostname}/workspace/${workspaceId}/api/v1/external-auth-providers`;
     const client = axios_1.default.create({ baseURL });
     client.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
         const token = yield ensureToken(sdk);

package/dist/tools/compute.js

@@ -82,9 +82,9 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
             };
         }
     }));
-    server.tool("list_triggers", "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger).", {
+    server.tool("list_triggers", "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger, endpoint).", {
         executionType: zod_1.z
-            .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
+            .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
             .optional()
             .describe("Filter by trigger execution type"),
         page: zod_1.z.number().optional().describe("Page number"),
@@ -394,13 +394,13 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
         name: zod_1.z.string().describe("Display name for the trigger"),
         functionId: zod_1.z.string().describe("The compute function ID (UUID) to execute"),
         executionType: zod_1.z
-            .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
-            .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), or http-trigger (external HTTP POST)"),
+            .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
+            .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), http-trigger (external HTTP POST), or endpoint (synchronous HTTP API — returns response inline)"),
         description: zod_1.z.string().optional().describe("Optional description"),
         triggerMetadata: zod_1.z
             .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug } where eventType is record_created | record_updated | record_deleted. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL."),
+            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }."),
         enabled: zod_1.z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, functionId, executionType, description, triggerMetadata, enabled }) {
         try {
@@ -616,6 +616,54 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
             };
         }
     }));
+    // ── Endpoint Trigger (Sync Execution) ─────────────────────────────
+    server.tool("invoke_endpoint", "Invoke a compute endpoint trigger by path. The function executes synchronously — Centrali waits for the function to complete and returns its output directly in the response. No polling needed. Max execution time: 30 seconds (configurable via triggerMetadata.timeoutMs, range 1–30s). If the function exceeds the timeout, returns 504. Endpoint triggers must be created first with executionType='endpoint'. Use this for real-time API responses; use invoke_trigger for long-running background work that doesn't need an immediate response.", {
+        path: zod_1.z.string().describe("The endpoint path (e.g., 'create-order', 'webhook/shipments'). This is set in the trigger's triggerMetadata.path."),
+        method: zod_1.z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional().describe("HTTP method (default: POST). Must be in the trigger's allowedMethods."),
+        payload: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe("Request body payload (sent as JSON)"),
+        headers: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional().describe("Additional headers (e.g., X-API-Key for apiKey auth)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ path, method, payload, headers: extraHeaders }) {
+        try {
+            const token = yield ensureToken(sdk);
+            const url = new URL(centraliUrl);
+            const hostname = url.hostname.startsWith("api.")
+                ? url.hostname
+                : `api.${url.hostname}`;
+            const apiUrl = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/endpoints/${path}`;
+            const reqHeaders = {};
+            if (token)
+                reqHeaders.Authorization = `Bearer ${token}`;
+            if (extraHeaders)
+                Object.assign(reqHeaders, extraHeaders);
+            const httpMethod = (method || "POST").toLowerCase();
+            const result = yield (0, axios_1.default)({
+                method: httpMethod,
+                url: apiUrl,
+                data: ["get", "delete"].includes(httpMethod) ? undefined : (payload || {}),
+                headers: reqHeaders,
+                validateStatus: () => true, // Don't throw on non-2xx — return the function's response as-is
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: result.status,
+                            headers: {
+                                "content-type": result.headers["content-type"],
+                                "x-execution-id": result.headers["x-execution-id"],
+                            },
+                            body: result.data,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `invoking endpoint '${path}'`) }],
+                isError: true,
+            };
+        }
+    }));
     // ── Allowed Domains tools ──────────────────────────────────────────
     server.tool("list_allowed_domains", "List all allowed domains for compute function HTTP requests. Functions can only call external APIs on domains in this allowlist.", {}, () => __awaiter(this, void 0, void 0, function* () {
         try {

package/dist/tools/describe.js

@@ -85,6 +85,7 @@ function registerDescribeTools(server) {
                                     "get_function_run",
                                     "list_function_runs",
                                     "get_compute_job_status",
+                                    "invoke_endpoint",
                                 ],
                             },
                             smart_queries: {
@@ -220,6 +221,16 @@ function registerDescribeTools(server) {
                                 ],
                             },
                         },
+                        naming_guide: {
+                            description: "Different tools use different parameter names for the same concept (collection identifier). This is a historical naming drift — all of these refer to the same thing.",
+                            aliases: {
+                                recordSlug: "Used by record tools (query_records, create_record, etc.). This is the collection's URL-safe slug, e.g., 'orders'.",
+                                structureSlug: "Used by validation and insights tools. Same value as recordSlug.",
+                                collections: "Used by search_records. Same value as recordSlug. Accepts a string or array of strings.",
+                                structureIds: "Used by generate_starter_pages. This is the collection UUID (not the slug). Get it from list_collections → id field.",
+                            },
+                            rule: "When a tool asks for recordSlug, structureSlug, or collections — use the collection's slug (e.g., 'orders'). When a tool asks for structureIds — use the collection's UUID.",
+                        },
                         workflow: "Typical workflow: 1) Define collections → 2) Create records → 3) Write compute functions → 4) Wire orchestrations → 5) Build pages to surface data → 6) Publish pages for end users. When building an app, also: 7) Create a service account → 8) Grant least-privilege permissions via remediation → 9) Create publishable keys for the frontend.",
                         app_credential_setup: {
                             description: "When building an app that uses Centrali, you need credentials. The flow depends on whether the code runs server-side or client-side.",
@@ -522,13 +533,29 @@ function registerDescribeTools(server) {
                                 description: "Triggered by an external HTTP POST to a generated webhook URL.",
                                 config: "Each http-trigger gets a unique URL to share with external services",
                             },
+                            "endpoint": {
+                                description: "Turns a compute function into a custom API endpoint. Unlike all other trigger types (which are async and return a job ID you must poll), endpoint triggers WAIT for the function to complete and return its output directly in the HTTP response. Max execution time: 30 seconds.",
+                                when_to_use: "Use endpoint triggers when the caller needs the function's output immediately (REST APIs, form handlers, webhook responders, data calculations). Use on-demand/invoke_trigger for long-running work (>30s) or fire-and-forget background jobs.",
+                                config: {
+                                    path: "string — URL-safe path (e.g., 'create-order', 'webhook/shipments'). Must be unique per workspace.",
+                                    allowedMethods: "string[] — HTTP methods to accept (default: ['POST']). Options: GET, POST, PUT, DELETE, PATCH.",
+                                    timeoutMs: "number — execution timeout 1000-30000ms (default: 30000). Function MUST complete within this window or the request returns 504 Gateway Timeout.",
+                                    auth: "{ mode: 'bearer'|'public'|'apiKey'|'hmac' } — authentication mode. bearer=IAM token, public=no auth, apiKey=X-API-Key header (auto-generated), hmac=X-Signature header (auto-generated signing secret).",
+                                },
+                                invocation: "Call invoke_endpoint with the path. Response comes back inline — no polling needed.",
+                                example_use_cases: [
+                                    "Build a REST API endpoint backed by a compute function",
+                                    "Create a webhook receiver that processes and responds synchronously",
+                                    "Expose a function as an HTTP service for external integrations",
+                                ],
+                            },
                         },
                         trigger_shape: {
                             id: "UUID",
                             name: "string",
                             description: "string | null",
                             functionId: "UUID — the compute function to execute",
-                            executionType: "'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger'",
+                            executionType: "'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger' | 'endpoint'",
                             triggerMetadata: "object — type-specific configuration (event, cron, params, etc.)",
                             enabled: "boolean — whether the trigger is active (default: true)",
                             workspaceSlug: "string",
@@ -575,6 +602,7 @@ function registerDescribeTools(server) {
                                 triggerMetadata_examples: {
                                     "event-driven": { eventType: "record_created", recordSlug: "orders" },
                                     scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                                    endpoint: { path: "create-order", allowedMethods: ["POST"], timeoutMs: 10000, auth: { mode: "bearer" } },
                                 },
                             },
                             update_trigger: {
@@ -969,7 +997,7 @@ function registerDescribeTools(server) {
                             id: "UUID",
                             structureSlug: "string — the collection where the anomaly was detected",
                             type: "string — anomaly type (e.g., 'spike', 'drop', 'outlier', 'pattern_break')",
-                            severity: "'critical' | 'high' | 'medium' | 'low'",
+                            severity: "'info' | 'warning' | 'critical'",
                             status: "'active' | 'acknowledged' | 'dismissed'",
                             title: "string — human-readable summary",
                             description: "string — detailed explanation of the anomaly",
@@ -986,12 +1014,12 @@ function registerDescribeTools(server) {
                             totalActive: "number",
                             totalAcknowledged: "number",
                             totalDismissed: "number",
-                            bySeverity: "{ critical: n, high: n, medium: n, low: n }",
+                            bySeverity: "{ info: n, warning: n, critical: n }",
                         },
                         tips: [
                             "Use trigger_anomaly_analysis to scan a specific collection on-demand",
                             "Use get_insights_summary for a quick overview before diving into individual insights",
-                            "Filter by severity='critical' to focus on the most important issues first",
+                            "Filter by severity='critical' to focus on the most important issues first. Severity levels: info (noteworthy), warning (needs attention), critical (requires action).",
                             "Acknowledged insights are still visible — use dismiss for false positives",
                         ],
                     }, null, 2),
@@ -1108,6 +1136,12 @@ function registerDescribeTools(server) {
                             "4_publish": "publish_page — makes the page accessible at its runtime URL",
                             "5_iterate": "Repeat steps 2-4 to update. Each publish creates a new version.",
                             unpublish: "unpublish_page — removes the page from its runtime URL (keeps the definition)",
+                            important_behavior: {
+                                description: "Publishing does NOT consume or delete the draft. After publishing, the page has BOTH an activePublication (the live version) and a currentDraft (a new working draft for future edits). This is intentional — it allows iterating on changes without affecting the live page.",
+                                example: "After publishing version 1, get_page shows: activePublication.versionNumber=1 (live) and currentDraft.versionNumber=2 (editable). The draft is not stale — it's the starting point for the next publish cycle.",
+                                agent_tip: "Do not treat the draft as an error or leftover. The normal state of a published page is: one active publication + one working draft. Edit the draft, validate, publish again to create version 3, etc.",
+                            },
+                            eventual_consistency_note: "After save_page_draft or set_navigation, there may be a brief delay before the data is visible via get_page_draft or get_navigation. If you get a 'not found' immediately after writing, wait 1-2 seconds and retry.",
                         },
                         access_modes: {
                             public: "Anyone can view — no authentication required",

package/dist/tools/insights.js

@@ -46,7 +46,7 @@ function registerInsightTools(server, sdk) {
             .optional()
             .describe("Filter by insight status"),
         severity: zod_1.z
-            .enum(["critical", "high", "medium", "low"])
+            .enum(["info", "warning", "critical"])
             .optional()
             .describe("Filter by severity level"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ structureSlug, status, severity }) {

package/dist/tools/service-accounts.js

@@ -37,10 +37,10 @@ function ensureToken(sdk) {
  */
 function createIamClient(sdk, centraliUrl, workspaceId, baseSuffix) {
     const url = new URL(centraliUrl);
-    const hostname = url.hostname.startsWith("api.")
+    const hostname = url.hostname.startsWith("auth.")
         ? url.hostname
-        : `api.${url.hostname}`;
-    const baseURL = `${url.protocol}//${hostname}/iam/workspace/${workspaceId}/api/v1/${baseSuffix}`;
+        : `auth.${url.hostname.replace(/^api\./, '')}`;
+    const baseURL = `${url.protocol}//${hostname}/workspace/${workspaceId}/api/v1/${baseSuffix}`;
     const client = axios_1.default.create({ baseURL });
     client.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
         const token = yield ensureToken(sdk);

package/dist/tools/structures.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 export declare function registerStructureTools(server: McpServer, sdk: CentraliSDK): void;
-export declare function registerCollectionTools(server: McpServer, sdk: CentraliSDK): void;
+export declare function registerCollectionTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string): void;

package/dist/tools/structures.js

@@ -8,18 +8,39 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerStructureTools = registerStructureTools;
 exports.registerCollectionTools = registerCollectionTools;
+const axios_1 = __importDefault(require("axios"));
 const zod_1 = require("zod");
 function formatError(error, context) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     if (error && typeof error === 'object') {
         const e = error;
+        if ((_a = e.response) === null || _a === void 0 ? void 0 : _a.data) {
+            const d = e.response.data;
+            const code = (_f = (_e = (_c = (_b = d.code) !== null && _b !== void 0 ? _b : d.errorCode) !== null && _c !== void 0 ? _c : (_d = d.error) === null || _d === void 0 ? void 0 : _d.code) !== null && _e !== void 0 ? _e : e.response.status) !== null && _f !== void 0 ? _f : "ERROR";
+            const message = (_j = (_g = d.message) !== null && _g !== void 0 ? _g : (_h = d.error) === null || _h === void 0 ? void 0 : _h.message) !== null && _j !== void 0 ? _j : JSON.stringify(d);
+            let msg = `Error ${context}: [${code}] ${message}`;
+            // Include extra context from error response (e.g. classification details)
+            if (d.classification) {
+                msg += `\nClassification: ${JSON.stringify(d.classification)}`;
+            }
+            if (d.criticalChanges) {
+                msg += `\nCritical changes: ${JSON.stringify(d.criticalChanges)}`;
+            }
+            if (d.suggestion) {
+                msg += `\nSuggestion: ${d.suggestion}`;
+            }
+            return msg;
+        }
         if ('message' in e) {
             let msg = `Error ${context}`;
             if ('code' in e || 'status' in e) {
-                msg += `: [${(_b = (_a = e.code) !== null && _a !== void 0 ? _a : e.status) !== null && _b !== void 0 ? _b : 'ERROR'}] ${e.message}`;
+                msg += `: [${(_l = (_k = e.code) !== null && _k !== void 0 ? _k : e.status) !== null && _l !== void 0 ? _l : 'ERROR'}] ${e.message}`;
             }
             else {
                 msg += `: ${e.message}`;
@@ -34,6 +55,58 @@ function formatError(error, context) {
     }
     return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
 }
+/**
+ * Ensures the SDK has a valid token.
+ */
+function ensureToken(sdk) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let token = sdk.getToken();
+        if (token)
+            return token;
+        try {
+            yield sdk.functions.list({ limit: 1 });
+        }
+        catch ( /* token refresh side effect */_a) { /* token refresh side effect */ }
+        return sdk.getToken();
+    });
+}
+/**
+ * Creates an axios instance pointing at the data service collections API.
+ */
+function createDataClient(sdk, centraliUrl, workspaceId, pathSuffix) {
+    const url = new URL(centraliUrl);
+    const hostname = url.hostname.startsWith("api.")
+        ? url.hostname
+        : `api.${url.hostname}`;
+    const baseURL = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/${pathSuffix}`;
+    const client = axios_1.default.create({ baseURL });
+    client.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
+        const token = yield ensureToken(sdk);
+        if (token) {
+            config.headers.Authorization = `Bearer ${token}`;
+        }
+        return config;
+    }));
+    client.interceptors.response.use((response) => response, (error) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const originalRequest = error.config;
+        const isAuthError = ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 401 || ((_b = error.response) === null || _b === void 0 ? void 0 : _b.status) === 403;
+        if (isAuthError && !originalRequest._hasRetried) {
+            originalRequest._hasRetried = true;
+            try {
+                yield sdk.functions.list({ limit: 1 });
+            }
+            catch ( /* token refresh side effect */_c) { /* token refresh side effect */ }
+            const token = sdk.getToken();
+            if (token) {
+                originalRequest.headers.Authorization = `Bearer ${token}`;
+                return client.request(originalRequest);
+            }
+        }
+        return Promise.reject(error);
+    }));
+    return client;
+}
 function registerStructureTools(server, sdk) {
     server.tool("list_structures", "[DEPRECATED: use list_collections instead] List all data structures (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each structure.", {
         page: zod_1.z.number().optional().describe("Page number (1-indexed)"),
@@ -85,7 +158,8 @@ function registerStructureTools(server, sdk) {
         }
     }));
 }
-function registerCollectionTools(server, sdk) {
+function registerCollectionTools(server, sdk, centraliUrl, workspaceId) {
+    const getCollectionsClient = () => createDataClient(sdk, centraliUrl, workspaceId, "collections");
     server.tool("list_collections", "List all data collections (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each collection.", {
         page: zod_1.z.number().optional().describe("Page number (1-indexed)"),
         limit: zod_1.z.number().optional().describe("Results per page"),
@@ -181,14 +255,132 @@ function registerCollectionTools(server, sdk) {
             };
         }
     }));
-    server.tool("update_collection", "Update an existing collection by ID. Only include the fields you want to change.", {
+    // ── Schema Update Workflow ─────────────────────────────────────────
+    //
+    // Updating a collection schema is a multi-step process because changes
+    // may require migrating existing records. The workflow is:
+    //
+    //   1. analyze_collection_update  — classify changes, get suggested fixes
+    //   2. preview_collection_migration — (optional) test fixes on sample records
+    //   3. update_collection — apply the update, with migration plan if needed
+    //   4. get_collection_upgrade_progress — poll async migration status
+    //
+    // For simple changes (adding optional fields, renaming, metadata-only),
+    // update_collection handles everything automatically. For breaking or
+    // critical changes, analyze first to understand what's needed.
+    server.tool("analyze_collection_update", `Analyze proposed schema changes BEFORE applying them. Returns whether migration is needed, what changes are breaking/critical, suggested fixes, and estimated duration.
+
+WHEN TO USE: Call this before update_collection when you are changing properties (adding required fields, changing types, renaming fields, deleting fields, or toggling isSecret). This tells you exactly what will happen and what migration plan is needed.
+
+CHANGE CATEGORIES:
+- Non-breaking (no migration): adding optional fields, metadata changes → update_collection handles directly
+- Breaking (migration, skippable on non-strict): field renames, deletions, type changes, constraint changes → can skip on schemaless/auto-evolving collections
+- Critical (migration, NEVER skippable): adding required fields without defaults, toggling isSecret → must provide a migration plan with fixes
+
+RESPONSE FIELDS:
+- needsMigration: whether existing records need to be updated
+- canSkip: whether migration can be skipped (only false for critical changes or strict schemas with breaking changes)
+- recordCount: number of existing records affected
+- classification: detailed breakdown of all changes by category
+- suggestedFixes: auto-generated fixes you can use in update_collection's migrationPlan
+- estimatedDuration: 'instant' | 'seconds' | 'minutes' | 'long'`, {
+        collectionId: zod_1.z.string().describe("The collection ID (UUID) to analyze"),
+        properties: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .describe("The COMPLETE new properties array (all fields, not just changed ones). Must include existing property IDs for fields being kept/modified."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ collectionId, properties }) {
+        try {
+            const client = getCollectionsClient();
+            const result = yield client.post(`/${collectionId}/analyze-update`, { properties });
+            const data = result.data;
+            // Build a human-readable summary for the LLM
+            const lines = [];
+            lines.push(`## Analysis for collection ${collectionId}`);
+            lines.push(`- Records affected: ${data.recordCount}`);
+            lines.push(`- Needs migration: ${data.needsMigration}`);
+            lines.push(`- Can skip migration: ${data.canSkip}`);
+            lines.push(`- Estimated duration: ${data.estimatedDuration}`);
+            if (!data.needsMigration) {
+                lines.push(`\n✅ No migration needed. You can call update_collection directly.`);
+            }
+            else if (data.canSkip) {
+                lines.push(`\n⚠️ Migration can be skipped. Call update_collection without a migrationPlan to skip, or provide one for a clean migration.`);
+            }
+            else {
+                lines.push(`\n🔴 Migration REQUIRED and cannot be skipped. You must call update_collection with a migrationPlan.`);
+                lines.push(`Use mode 'auto' to apply suggested fixes, or mode 'manual' with custom fixes.`);
+            }
+            if (data.suggestedFixes && data.suggestedFixes.length > 0) {
+                lines.push(`\n### Suggested fixes (use these in migrationPlan.fixes or mode 'auto'):`);
+            }
+            lines.push(`\n### Full analysis:`);
+            lines.push(JSON.stringify(data, null, 2));
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `analyzing update for collection '${collectionId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("preview_collection_migration", `Preview the effect of migration fixes on sample records BEFORE applying them. Shows before/after snapshots so you can verify fixes are correct.
+
+WHEN TO USE: After analyze_collection_update returns suggestedFixes, call this to see how those fixes would transform actual records. Useful for validating type conversions, default values, and expressions before committing.`, {
+        collectionId: zod_1.z.string().describe("The collection ID (UUID)"),
+        fixes: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .describe("Array of migration fixes to preview (from analyze_collection_update suggestedFixes or custom fixes)"),
+        properties: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .describe("The COMPLETE new properties array (same as passed to analyze_collection_update)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ collectionId, fixes, properties }) {
+        try {
+            const client = getCollectionsClient();
+            const result = yield client.post(`/${collectionId}/preview-fixes`, { fixes, properties });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `previewing fixes for collection '${collectionId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("update_collection", `Update a collection's schema using the safe upgrade endpoint. This handles both simple updates and complex migrations.
+
+HOW IT WORKS:
+1. If your changes don't require migration (adding optional fields, metadata changes) → completes immediately
+2. If migration is required but you don't provide a migrationPlan → returns an error telling you what's needed
+3. If migration is required and you provide migrationPlan → starts the migration (may be async for large collections)
+
+RECOMMENDED WORKFLOW:
+1. Call analyze_collection_update first to understand what changes require
+2. If needsMigration=false → call this tool without migrationPlan
+3. If needsMigration=true and canSkip=true → call this tool without migrationPlan to skip migration
+4. If needsMigration=true and canSkip=false → call this tool WITH migrationPlan
+5. If status='in_progress' → poll with get_collection_upgrade_progress
+
+MIGRATION PLAN:
+- mode 'auto': Uses system-generated fixes from analyze_collection_update (handles renames, type conversions, deletions automatically)
+- mode 'manual': Provide your own fixes array for full control over how records are transformed
+
+FIX FORMAT (for manual mode):
+Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAll?, filterConditions? }
+- fixType: 'static_value' (set a fixed value), 'expression' (JS expression with 'record' variable), 'auto' (system handles it)
+- For new required fields: provide a default value or expression
+- For type changes: provide a conversion expression`, {
         collectionId: zod_1.z.string().describe("The collection ID (UUID) to update"),
         name: zod_1.z.string().optional().describe("Updated display name"),
         description: zod_1.z.string().optional().describe("Updated description"),
         properties: zod_1.z
             .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
             .optional()
-            .describe("Updated array of property definitions (replaces existing properties)"),
+            .describe("The COMPLETE new properties array. Must include ALL fields (existing + new). Include property 'id' for existing fields being kept/modified."),
         enableVersioning: zod_1.z.boolean().optional().describe("Enable or disable record versioning"),
         tags: zod_1.z.array(zod_1.z.string()).optional().describe("Updated tags"),
         defaultTtlSeconds: zod_1.z
@@ -196,36 +388,83 @@ function registerCollectionTools(server, sdk) {
             .nullable()
             .optional()
             .describe("Default TTL in seconds for new records. Set to null to clear."),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ collectionId, name, description, properties, enableVersioning, tags, defaultTtlSeconds }) {
+        migrationPlan: zod_1.z
+            .object({
+            mode: zod_1.z.enum(["auto", "manual"]).describe("'auto' uses suggested fixes, 'manual' uses your custom fixes array"),
+            fixes: zod_1.z
+                .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+                .optional()
+                .describe("Required for 'manual' mode. Array of fix objects specifying how to transform records."),
+        })
+            .optional()
+            .describe("Migration plan for breaking/critical changes. Omit to skip migration (only works if canSkip=true from analyze). Required when canSkip=false."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ collectionId, name, description, properties, enableVersioning, tags, defaultTtlSeconds, migrationPlan }) {
         try {
-            const input = {};
+            const client = getCollectionsClient();
+            const body = {};
             if (name !== undefined)
-                input.name = name;
+                body.name = name;
             if (description !== undefined)
-                input.description = description;
+                body.description = description;
             if (properties !== undefined)
-                input.properties = properties;
+                body.properties = properties;
             if (enableVersioning !== undefined)
-                input.enableVersioning = enableVersioning;
+                body.enableVersioning = enableVersioning;
             if (tags !== undefined)
-                input.tags = tags;
+                body.tags = tags;
             if (defaultTtlSeconds !== undefined)
-                input.defaultTtlSeconds = defaultTtlSeconds;
-            const result = yield sdk.collections.update(collectionId, input);
+                body.defaultTtlSeconds = defaultTtlSeconds;
+            if (migrationPlan !== undefined)
+                body.migrationPlan = migrationPlan;
+            const result = yield client.post(`/${collectionId}/upgrade`, body);
+            const data = result.data;
+            if (data.status === 'completed') {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Collection updated successfully.\n\n${JSON.stringify(data.structure, null, 2)}`,
+                        }],
+                };
+            }
+            if (data.status === 'in_progress') {
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `Migration started (async). Records are being updated in the background.`,
+                                `- Job ID: ${data.jobId}`,
+                                `- Progress URL: ${data.progressUrl}`,
+                                ``,
+                                `Call get_collection_upgrade_progress with collectionId='${collectionId}' and jobId='${data.jobId}' to check status.`,
+                            ].join("\n"),
+                        }],
+                };
+            }
             return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
             };
         }
         catch (error) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: formatError(error, `updating collection '${collectionId}'`),
-                    },
-                ],
+                content: [{ type: "text", text: formatError(error, `updating collection '${collectionId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("get_collection_upgrade_progress", "Check the progress of an async collection migration/upgrade job. Call this after update_collection returns status='in_progress'.", {
+        collectionId: zod_1.z.string().describe("The collection ID (UUID)"),
+        jobId: zod_1.z.string().describe("The job ID returned by update_collection"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ collectionId, jobId }) {
+        try {
+            const client = getCollectionsClient();
+            const result = yield client.get(`/${collectionId}/upgrade/${jobId}/progress`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `getting upgrade progress for '${collectionId}'`) }],
                 isError: true,
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.4.6",
+  "version": "4.4.8-rc.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -25,7 +25,7 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^4.4.6",
+    "@centrali-io/centrali-sdk": "^4.4.7",
     "@modelcontextprotocol/sdk": "^1.12.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -45,7 +45,7 @@ async function main() {
   });
 
   // Register all tools
-  registerCollectionTools(server, sdk);
+  registerCollectionTools(server, sdk, baseUrl, workspaceId);
   registerStructureTools(server, sdk);
   registerRecordTools(server, sdk);
   registerSearchTools(server, sdk);

package/src/tools/auth-providers.ts

@@ -22,10 +22,10 @@ async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
  */
 function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string): AxiosInstance {
   const url = new URL(centraliUrl);
-  const hostname = url.hostname.startsWith("api.")
+  const hostname = url.hostname.startsWith("auth.")
     ? url.hostname
-    : `api.${url.hostname}`;
-  const baseURL = `${url.protocol}//${hostname}/iam/workspace/${workspaceId}/api/v1/external-auth-providers`;
+    : `auth.${url.hostname.replace(/^api\./, '')}`;
+  const baseURL = `${url.protocol}//${hostname}/workspace/${workspaceId}/api/v1/external-auth-providers`;
 
   const client = axios.create({ baseURL });
 

package/src/tools/compute.ts

@@ -74,10 +74,10 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   server.tool(
     "list_triggers",
-    "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger).",
+    "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger, endpoint).",
     {
       executionType: z
-        .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
+        .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
         .optional()
         .describe("Filter by trigger execution type"),
       page: z.number().optional().describe("Page number"),
@@ -437,13 +437,13 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
       name: z.string().describe("Display name for the trigger"),
       functionId: z.string().describe("The compute function ID (UUID) to execute"),
       executionType: z
-        .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
-        .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), or http-trigger (external HTTP POST)"),
+        .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
+        .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), http-trigger (external HTTP POST), or endpoint (synchronous HTTP API — returns response inline)"),
       description: z.string().optional().describe("Optional description"),
       triggerMetadata: z
         .record(z.string(), z.any())
         .optional()
-        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug } where eventType is record_created | record_updated | record_deleted. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL."),
+        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }."),
       enabled: z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     },
     async ({ name, functionId, executionType, description, triggerMetadata, enabled }) => {
@@ -687,6 +687,61 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
+  // ── Endpoint Trigger (Sync Execution) ─────────────────────────────
+
+  server.tool(
+    "invoke_endpoint",
+    "Invoke a compute endpoint trigger by path. The function executes synchronously — Centrali waits for the function to complete and returns its output directly in the response. No polling needed. Max execution time: 30 seconds (configurable via triggerMetadata.timeoutMs, range 1–30s). If the function exceeds the timeout, returns 504. Endpoint triggers must be created first with executionType='endpoint'. Use this for real-time API responses; use invoke_trigger for long-running background work that doesn't need an immediate response.",
+    {
+      path: z.string().describe("The endpoint path (e.g., 'create-order', 'webhook/shipments'). This is set in the trigger's triggerMetadata.path."),
+      method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional().describe("HTTP method (default: POST). Must be in the trigger's allowedMethods."),
+      payload: z.record(z.string(), z.any()).optional().describe("Request body payload (sent as JSON)"),
+      headers: z.record(z.string(), z.string()).optional().describe("Additional headers (e.g., X-API-Key for apiKey auth)"),
+    },
+    async ({ path, method, payload, headers: extraHeaders }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const url = new URL(centraliUrl);
+        const hostname = url.hostname.startsWith("api.")
+          ? url.hostname
+          : `api.${url.hostname}`;
+        const apiUrl = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/endpoints/${path}`;
+
+        const reqHeaders: Record<string, string> = {};
+        if (token) reqHeaders.Authorization = `Bearer ${token}`;
+        if (extraHeaders) Object.assign(reqHeaders, extraHeaders);
+
+        const httpMethod = (method || "POST").toLowerCase();
+        const result = await axios({
+          method: httpMethod as any,
+          url: apiUrl,
+          data: ["get", "delete"].includes(httpMethod) ? undefined : (payload || {}),
+          headers: reqHeaders,
+          validateStatus: () => true, // Don't throw on non-2xx — return the function's response as-is
+        });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: result.status,
+              headers: {
+                "content-type": result.headers["content-type"],
+                "x-execution-id": result.headers["x-execution-id"],
+              },
+              body: result.data,
+            }, null, 2),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `invoking endpoint '${path}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // ── Allowed Domains tools ──────────────────────────────────────────
 
   server.tool(

package/src/tools/describe.ts

@@ -85,6 +85,7 @@ export function registerDescribeTools(server: McpServer) {
                     "get_function_run",
                     "list_function_runs",
                     "get_compute_job_status",
+                    "invoke_endpoint",
                   ],
                 },
                 smart_queries: {
@@ -227,6 +228,16 @@ export function registerDescribeTools(server: McpServer) {
                   ],
                 },
               },
+              naming_guide: {
+                description: "Different tools use different parameter names for the same concept (collection identifier). This is a historical naming drift — all of these refer to the same thing.",
+                aliases: {
+                  recordSlug: "Used by record tools (query_records, create_record, etc.). This is the collection's URL-safe slug, e.g., 'orders'.",
+                  structureSlug: "Used by validation and insights tools. Same value as recordSlug.",
+                  collections: "Used by search_records. Same value as recordSlug. Accepts a string or array of strings.",
+                  structureIds: "Used by generate_starter_pages. This is the collection UUID (not the slug). Get it from list_collections → id field.",
+                },
+                rule: "When a tool asks for recordSlug, structureSlug, or collections — use the collection's slug (e.g., 'orders'). When a tool asks for structureIds — use the collection's UUID.",
+              },
               workflow:
                 "Typical workflow: 1) Define collections → 2) Create records → 3) Write compute functions → 4) Wire orchestrations → 5) Build pages to surface data → 6) Publish pages for end users. When building an app, also: 7) Create a service account → 8) Grant least-privilege permissions via remediation → 9) Create publishable keys for the frontend.",
               app_credential_setup: {
@@ -594,13 +605,30 @@ export function registerDescribeTools(server: McpServer) {
                     "Triggered by an external HTTP POST to a generated webhook URL.",
                   config: "Each http-trigger gets a unique URL to share with external services",
                 },
+                "endpoint": {
+                  description:
+                    "Turns a compute function into a custom API endpoint. Unlike all other trigger types (which are async and return a job ID you must poll), endpoint triggers WAIT for the function to complete and return its output directly in the HTTP response. Max execution time: 30 seconds.",
+                  when_to_use: "Use endpoint triggers when the caller needs the function's output immediately (REST APIs, form handlers, webhook responders, data calculations). Use on-demand/invoke_trigger for long-running work (>30s) or fire-and-forget background jobs.",
+                  config: {
+                    path: "string — URL-safe path (e.g., 'create-order', 'webhook/shipments'). Must be unique per workspace.",
+                    allowedMethods: "string[] — HTTP methods to accept (default: ['POST']). Options: GET, POST, PUT, DELETE, PATCH.",
+                    timeoutMs: "number — execution timeout 1000-30000ms (default: 30000). Function MUST complete within this window or the request returns 504 Gateway Timeout.",
+                    auth: "{ mode: 'bearer'|'public'|'apiKey'|'hmac' } — authentication mode. bearer=IAM token, public=no auth, apiKey=X-API-Key header (auto-generated), hmac=X-Signature header (auto-generated signing secret).",
+                  },
+                  invocation: "Call invoke_endpoint with the path. Response comes back inline — no polling needed.",
+                  example_use_cases: [
+                    "Build a REST API endpoint backed by a compute function",
+                    "Create a webhook receiver that processes and responds synchronously",
+                    "Expose a function as an HTTP service for external integrations",
+                  ],
+                },
               },
               trigger_shape: {
                 id: "UUID",
                 name: "string",
                 description: "string | null",
                 functionId: "UUID — the compute function to execute",
-                executionType: "'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger'",
+                executionType: "'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger' | 'endpoint'",
                 triggerMetadata: "object — type-specific configuration (event, cron, params, etc.)",
                 enabled: "boolean — whether the trigger is active (default: true)",
                 workspaceSlug: "string",
@@ -647,6 +675,7 @@ export function registerDescribeTools(server: McpServer) {
                   triggerMetadata_examples: {
                     "event-driven": { eventType: "record_created", recordSlug: "orders" },
                     scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                    endpoint: { path: "create-order", allowedMethods: ["POST"], timeoutMs: 10000, auth: { mode: "bearer" } },
                   },
                 },
                 update_trigger: {
@@ -1074,7 +1103,7 @@ export function registerDescribeTools(server: McpServer) {
                 id: "UUID",
                 structureSlug: "string — the collection where the anomaly was detected",
                 type: "string — anomaly type (e.g., 'spike', 'drop', 'outlier', 'pattern_break')",
-                severity: "'critical' | 'high' | 'medium' | 'low'",
+                severity: "'info' | 'warning' | 'critical'",
                 status: "'active' | 'acknowledged' | 'dismissed'",
                 title: "string — human-readable summary",
                 description: "string — detailed explanation of the anomaly",
@@ -1093,12 +1122,12 @@ export function registerDescribeTools(server: McpServer) {
                 totalActive: "number",
                 totalAcknowledged: "number",
                 totalDismissed: "number",
-                bySeverity: "{ critical: n, high: n, medium: n, low: n }",
+                bySeverity: "{ info: n, warning: n, critical: n }",
               },
               tips: [
                 "Use trigger_anomaly_analysis to scan a specific collection on-demand",
                 "Use get_insights_summary for a quick overview before diving into individual insights",
-                "Filter by severity='critical' to focus on the most important issues first",
+                "Filter by severity='critical' to focus on the most important issues first. Severity levels: info (noteworthy), warning (needs attention), critical (requires action).",
                 "Acknowledged insights are still visible — use dismiss for false positives",
               ],
             },
@@ -1255,6 +1284,12 @@ export function registerDescribeTools(server: McpServer) {
                   "Repeat steps 2-4 to update. Each publish creates a new version.",
                 unpublish:
                   "unpublish_page — removes the page from its runtime URL (keeps the definition)",
+                important_behavior: {
+                  description: "Publishing does NOT consume or delete the draft. After publishing, the page has BOTH an activePublication (the live version) and a currentDraft (a new working draft for future edits). This is intentional — it allows iterating on changes without affecting the live page.",
+                  example: "After publishing version 1, get_page shows: activePublication.versionNumber=1 (live) and currentDraft.versionNumber=2 (editable). The draft is not stale — it's the starting point for the next publish cycle.",
+                  agent_tip: "Do not treat the draft as an error or leftover. The normal state of a published page is: one active publication + one working draft. Edit the draft, validate, publish again to create version 3, etc.",
+                },
+                eventual_consistency_note: "After save_page_draft or set_navigation, there may be a brief delay before the data is visible via get_page_draft or get_navigation. If you get a 'not found' immediately after writing, wait 1-2 seconds and retry.",
               },
               access_modes: {
                 public: "Anyone can view — no authentication required",

package/src/tools/insights.ts

@@ -41,7 +41,7 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
         .optional()
         .describe("Filter by insight status"),
       severity: z
-        .enum(["critical", "high", "medium", "low"])
+        .enum(["info", "warning", "critical"])
         .optional()
         .describe("Filter by severity level"),
     },

package/src/tools/service-accounts.ts

@@ -22,10 +22,10 @@ async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
  */
 function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string, baseSuffix: string): AxiosInstance {
   const url = new URL(centraliUrl);
-  const hostname = url.hostname.startsWith("api.")
+  const hostname = url.hostname.startsWith("auth.")
     ? url.hostname
-    : `api.${url.hostname}`;
-  const baseURL = `${url.protocol}//${hostname}/iam/workspace/${workspaceId}/api/v1/${baseSuffix}`;
+    : `auth.${url.hostname.replace(/^api\./, '')}`;
+  const baseURL = `${url.protocol}//${hostname}/workspace/${workspaceId}/api/v1/${baseSuffix}`;
 
   const client = axios.create({ baseURL });
 

package/src/tools/structures.ts

@@ -1,10 +1,28 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import axios, { AxiosInstance } from "axios";
 import { z } from "zod";
 
 function formatError(error: unknown, context: string): string {
   if (error && typeof error === 'object') {
     const e = error as Record<string, any>;
+    if (e.response?.data) {
+      const d = e.response.data;
+      const code = d.code ?? d.errorCode ?? d.error?.code ?? e.response.status ?? "ERROR";
+      const message = d.message ?? d.error?.message ?? JSON.stringify(d);
+      let msg = `Error ${context}: [${code}] ${message}`;
+      // Include extra context from error response (e.g. classification details)
+      if (d.classification) {
+        msg += `\nClassification: ${JSON.stringify(d.classification)}`;
+      }
+      if (d.criticalChanges) {
+        msg += `\nCritical changes: ${JSON.stringify(d.criticalChanges)}`;
+      }
+      if (d.suggestion) {
+        msg += `\nSuggestion: ${d.suggestion}`;
+      }
+      return msg;
+    }
     if ('message' in e) {
       let msg = `Error ${context}`;
       if ('code' in e || 'status' in e) {
@@ -23,6 +41,63 @@ function formatError(error: unknown, context: string): string {
   return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
 }
 
+/**
+ * Ensures the SDK has a valid token.
+ */
+async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
+  let token = sdk.getToken();
+  if (token) return token;
+  try {
+    await sdk.functions.list({ limit: 1 });
+  } catch { /* token refresh side effect */ }
+  return sdk.getToken();
+}
+
+/**
+ * Creates an axios instance pointing at the data service collections API.
+ */
+function createDataClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string, pathSuffix: string): AxiosInstance {
+  const url = new URL(centraliUrl);
+  const hostname = url.hostname.startsWith("api.")
+    ? url.hostname
+    : `api.${url.hostname}`;
+  const baseURL = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/${pathSuffix}`;
+
+  const client = axios.create({ baseURL });
+
+  client.interceptors.request.use(async (config) => {
+    const token = await ensureToken(sdk);
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      const originalRequest = error.config;
+      const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+
+      if (isAuthError && !originalRequest._hasRetried) {
+        originalRequest._hasRetried = true;
+        try {
+          await sdk.functions.list({ limit: 1 });
+        } catch { /* token refresh side effect */ }
+
+        const token = sdk.getToken();
+        if (token) {
+          originalRequest.headers.Authorization = `Bearer ${token}`;
+          return client.request(originalRequest);
+        }
+      }
+      return Promise.reject(error);
+    }
+  );
+
+  return client;
+}
+
 export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "list_structures",
@@ -84,7 +159,9 @@ export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
   );
 }
 
-export function registerCollectionTools(server: McpServer, sdk: CentraliSDK) {
+export function registerCollectionTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
+  const getCollectionsClient = () => createDataClient(sdk, centraliUrl, workspaceId, "collections");
+
   server.tool(
     "list_collections",
     "List all data collections (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each collection.",
@@ -192,9 +269,141 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
+  // ── Schema Update Workflow ─────────────────────────────────────────
+  //
+  // Updating a collection schema is a multi-step process because changes
+  // may require migrating existing records. The workflow is:
+  //
+  //   1. analyze_collection_update  — classify changes, get suggested fixes
+  //   2. preview_collection_migration — (optional) test fixes on sample records
+  //   3. update_collection — apply the update, with migration plan if needed
+  //   4. get_collection_upgrade_progress — poll async migration status
+  //
+  // For simple changes (adding optional fields, renaming, metadata-only),
+  // update_collection handles everything automatically. For breaking or
+  // critical changes, analyze first to understand what's needed.
+
+  server.tool(
+    "analyze_collection_update",
+    `Analyze proposed schema changes BEFORE applying them. Returns whether migration is needed, what changes are breaking/critical, suggested fixes, and estimated duration.
+
+WHEN TO USE: Call this before update_collection when you are changing properties (adding required fields, changing types, renaming fields, deleting fields, or toggling isSecret). This tells you exactly what will happen and what migration plan is needed.
+
+CHANGE CATEGORIES:
+- Non-breaking (no migration): adding optional fields, metadata changes → update_collection handles directly
+- Breaking (migration, skippable on non-strict): field renames, deletions, type changes, constraint changes → can skip on schemaless/auto-evolving collections
+- Critical (migration, NEVER skippable): adding required fields without defaults, toggling isSecret → must provide a migration plan with fixes
+
+RESPONSE FIELDS:
+- needsMigration: whether existing records need to be updated
+- canSkip: whether migration can be skipped (only false for critical changes or strict schemas with breaking changes)
+- recordCount: number of existing records affected
+- classification: detailed breakdown of all changes by category
+- suggestedFixes: auto-generated fixes you can use in update_collection's migrationPlan
+- estimatedDuration: 'instant' | 'seconds' | 'minutes' | 'long'`,
+    {
+      collectionId: z.string().describe("The collection ID (UUID) to analyze"),
+      properties: z
+        .array(z.record(z.string(), z.any()))
+        .describe("The COMPLETE new properties array (all fields, not just changed ones). Must include existing property IDs for fields being kept/modified."),
+    },
+    async ({ collectionId, properties }) => {
+      try {
+        const client = getCollectionsClient();
+        const result = await client.post(`/${collectionId}/analyze-update`, { properties });
+        const data = result.data;
+
+        // Build a human-readable summary for the LLM
+        const lines: string[] = [];
+        lines.push(`## Analysis for collection ${collectionId}`);
+        lines.push(`- Records affected: ${data.recordCount}`);
+        lines.push(`- Needs migration: ${data.needsMigration}`);
+        lines.push(`- Can skip migration: ${data.canSkip}`);
+        lines.push(`- Estimated duration: ${data.estimatedDuration}`);
+
+        if (!data.needsMigration) {
+          lines.push(`\n✅ No migration needed. You can call update_collection directly.`);
+        } else if (data.canSkip) {
+          lines.push(`\n⚠️ Migration can be skipped. Call update_collection without a migrationPlan to skip, or provide one for a clean migration.`);
+        } else {
+          lines.push(`\n🔴 Migration REQUIRED and cannot be skipped. You must call update_collection with a migrationPlan.`);
+          lines.push(`Use mode 'auto' to apply suggested fixes, or mode 'manual' with custom fixes.`);
+        }
+
+        if (data.suggestedFixes && data.suggestedFixes.length > 0) {
+          lines.push(`\n### Suggested fixes (use these in migrationPlan.fixes or mode 'auto'):`);
+        }
+
+        lines.push(`\n### Full analysis:`);
+        lines.push(JSON.stringify(data, null, 2));
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `analyzing update for collection '${collectionId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "preview_collection_migration",
+    `Preview the effect of migration fixes on sample records BEFORE applying them. Shows before/after snapshots so you can verify fixes are correct.
+
+WHEN TO USE: After analyze_collection_update returns suggestedFixes, call this to see how those fixes would transform actual records. Useful for validating type conversions, default values, and expressions before committing.`,
+    {
+      collectionId: z.string().describe("The collection ID (UUID)"),
+      fixes: z
+        .array(z.record(z.string(), z.any()))
+        .describe("Array of migration fixes to preview (from analyze_collection_update suggestedFixes or custom fixes)"),
+      properties: z
+        .array(z.record(z.string(), z.any()))
+        .describe("The COMPLETE new properties array (same as passed to analyze_collection_update)"),
+    },
+    async ({ collectionId, fixes, properties }) => {
+      try {
+        const client = getCollectionsClient();
+        const result = await client.post(`/${collectionId}/preview-fixes`, { fixes, properties });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `previewing fixes for collection '${collectionId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     "update_collection",
-    "Update an existing collection by ID. Only include the fields you want to change.",
+    `Update a collection's schema using the safe upgrade endpoint. This handles both simple updates and complex migrations.
+
+HOW IT WORKS:
+1. If your changes don't require migration (adding optional fields, metadata changes) → completes immediately
+2. If migration is required but you don't provide a migrationPlan → returns an error telling you what's needed
+3. If migration is required and you provide migrationPlan → starts the migration (may be async for large collections)
+
+RECOMMENDED WORKFLOW:
+1. Call analyze_collection_update first to understand what changes require
+2. If needsMigration=false → call this tool without migrationPlan
+3. If needsMigration=true and canSkip=true → call this tool without migrationPlan to skip migration
+4. If needsMigration=true and canSkip=false → call this tool WITH migrationPlan
+5. If status='in_progress' → poll with get_collection_upgrade_progress
+
+MIGRATION PLAN:
+- mode 'auto': Uses system-generated fixes from analyze_collection_update (handles renames, type conversions, deletions automatically)
+- mode 'manual': Provide your own fixes array for full control over how records are transformed
+
+FIX FORMAT (for manual mode):
+Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAll?, filterConditions? }
+- fixType: 'static_value' (set a fixed value), 'expression' (JS expression with 'record' variable), 'auto' (system handles it)
+- For new required fields: provide a default value or expression
+- For type changes: provide a conversion expression`,
     {
       collectionId: z.string().describe("The collection ID (UUID) to update"),
       name: z.string().optional().describe("Updated display name"),
@@ -202,7 +411,7 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK) {
       properties: z
         .array(z.record(z.string(), z.any()))
         .optional()
-        .describe("Updated array of property definitions (replaces existing properties)"),
+        .describe("The COMPLETE new properties array. Must include ALL fields (existing + new). Include property 'id' for existing fields being kept/modified."),
       enableVersioning: z.boolean().optional().describe("Enable or disable record versioning"),
       tags: z.array(z.string()).optional().describe("Updated tags"),
       defaultTtlSeconds: z
@@ -210,30 +419,85 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK) {
         .nullable()
         .optional()
         .describe("Default TTL in seconds for new records. Set to null to clear."),
+      migrationPlan: z
+        .object({
+          mode: z.enum(["auto", "manual"]).describe("'auto' uses suggested fixes, 'manual' uses your custom fixes array"),
+          fixes: z
+            .array(z.record(z.string(), z.any()))
+            .optional()
+            .describe("Required for 'manual' mode. Array of fix objects specifying how to transform records."),
+        })
+        .optional()
+        .describe("Migration plan for breaking/critical changes. Omit to skip migration (only works if canSkip=true from analyze). Required when canSkip=false."),
     },
-    async ({ collectionId, name, description, properties, enableVersioning, tags, defaultTtlSeconds }) => {
+    async ({ collectionId, name, description, properties, enableVersioning, tags, defaultTtlSeconds, migrationPlan }) => {
       try {
-        const input: Record<string, any> = {};
-        if (name !== undefined) input.name = name;
-        if (description !== undefined) input.description = description;
-        if (properties !== undefined) input.properties = properties;
-        if (enableVersioning !== undefined) input.enableVersioning = enableVersioning;
-        if (tags !== undefined) input.tags = tags;
-        if (defaultTtlSeconds !== undefined) input.defaultTtlSeconds = defaultTtlSeconds;
-        const result = await sdk.collections.update(collectionId, input as any);
+        const client = getCollectionsClient();
+        const body: Record<string, any> = {};
+        if (name !== undefined) body.name = name;
+        if (description !== undefined) body.description = description;
+        if (properties !== undefined) body.properties = properties;
+        if (enableVersioning !== undefined) body.enableVersioning = enableVersioning;
+        if (tags !== undefined) body.tags = tags;
+        if (defaultTtlSeconds !== undefined) body.defaultTtlSeconds = defaultTtlSeconds;
+        if (migrationPlan !== undefined) body.migrationPlan = migrationPlan;
+
+        const result = await client.post(`/${collectionId}/upgrade`, body);
+        const data = result.data;
+
+        if (data.status === 'completed') {
+          return {
+            content: [{
+              type: "text",
+              text: `Collection updated successfully.\n\n${JSON.stringify(data.structure, null, 2)}`,
+            }],
+          };
+        }
+
+        if (data.status === 'in_progress') {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `Migration started (async). Records are being updated in the background.`,
+                `- Job ID: ${data.jobId}`,
+                `- Progress URL: ${data.progressUrl}`,
+                ``,
+                `Call get_collection_upgrade_progress with collectionId='${collectionId}' and jobId='${data.jobId}' to check status.`,
+              ].join("\n"),
+            }],
+          };
+        }
+
         return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
+          content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
         };
       } catch (error: unknown) {
         return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `updating collection '${collectionId}'`),
-            },
-          ],
+          content: [{ type: "text", text: formatError(error, `updating collection '${collectionId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_collection_upgrade_progress",
+    "Check the progress of an async collection migration/upgrade job. Call this after update_collection returns status='in_progress'.",
+    {
+      collectionId: z.string().describe("The collection ID (UUID)"),
+      jobId: z.string().describe("The job ID returned by update_collection"),
+    },
+    async ({ collectionId, jobId }) => {
+      try {
+        const client = getCollectionsClient();
+        const result = await client.get(`/${collectionId}/upgrade/${jobId}/progress`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting upgrade progress for '${collectionId}'`) }],
           isError: true,
         };
       }