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

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/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.7",
+  "version": "4.4.8-rc.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

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/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,
         };
       }