@centrali-io/centrali-mcp 4.4.8 → 4.4.9

package/README.md

@@ -36,6 +36,23 @@ Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
 | `CENTRALI_CLIENT_SECRET` | Yes | Service account client secret |
 | `CENTRALI_WORKSPACE` | Yes | Workspace slug to operate in |
 
+### Service Account Permissions
+
+A freshly created service account **has no permissions by default**. You must assign it a role before the MCP server can do anything useful, otherwise every tool call will return `403 Forbidden`.
+
+**Quickest setup — full admin access:**
+
+1. In the Console, go to **Settings → Service Accounts**
+2. Create your service account and save the client secret
+3. Open the service account, go to the **Groups** tab
+4. Add it to the **workspace_administrators** group
+
+This gives the MCP server full access to all workspace resources.
+
+**Least-privilege setup — custom permissions:**
+
+If you only want the MCP to manage specific resources (e.g., collections and records but not billing), create a custom group with a policy scoped to the resources you need, then add the service account to that group. See the [Policies and Permissions guide](https://docs.centrali.io/authentication/policies-and-permissions/) for details.
+
 ## Getting Started
 
 After connecting, call `describe_centrali` first — it returns the full capability map, feature matrix, and SDK integration guidance. Then use the specific `describe_*` tools for deeper schema details on any domain.

package/dist/index.js

@@ -53,7 +53,7 @@ function main() {
         // Register all tools
         (0, structures_js_1.registerCollectionTools)(server, sdk, baseUrl, workspaceId);
         (0, structures_js_1.registerStructureTools)(server, sdk);
-        (0, records_js_1.registerRecordTools)(server, sdk);
+        (0, records_js_1.registerRecordTools)(server, sdk, baseUrl, workspaceId);
         (0, search_js_1.registerSearchTools)(server, sdk);
         (0, compute_js_1.registerComputeTools)(server, sdk, baseUrl, workspaceId);
         (0, smart_queries_js_1.registerSmartQueryTools)(server, sdk);

package/dist/tools/compute.js

@@ -735,4 +735,171 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
             };
         }
     }));
+    // ── Scaffold (function + trigger in one step) ─────────────────────
+    server.tool("scaffold_function", "Create a compute function with boilerplate code and optionally wire a trigger — all in one step. The function uses the required `async function run()` pattern with `api.*` globals, `triggerParams`, and `executionParams` available.", {
+        name: zod_1.z.string().describe("Function name"),
+        description: zod_1.z.string().optional().describe("Function description"),
+        code: zod_1.z.string().describe("Function code. Must use `async function run() { ... }` pattern. Has access to `api` (data operations), `triggerParams` (static config), and `executionParams` (runtime parameters)."),
+        trigger: zod_1.z.object({
+            type: zod_1.z.enum(["on_demand", "record", "schedule", "endpoint"]).describe("Trigger type"),
+            name: zod_1.z.string().optional().describe("Trigger name (auto-generated if omitted)"),
+            description: zod_1.z.string().optional(),
+            // Record trigger fields
+            recordSlug: zod_1.z.string().optional().describe("Collection slug (required for record triggers)"),
+            event: zod_1.z.string().optional().describe("Record event: afterCreate, afterUpdate, afterDelete (required for record triggers)"),
+            // Schedule trigger fields
+            cronExpression: zod_1.z.string().optional().describe("Cron expression (required for schedule triggers)"),
+            // Endpoint trigger fields
+            endpointPath: zod_1.z.string().optional().describe("URL path segment (required for endpoint triggers)"),
+            // Common
+            params: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe("Static trigger parameters available as triggerParams in the function"),
+        }).optional().describe("Trigger configuration. If omitted, creates function without a trigger."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, description, code, trigger }) {
+        try {
+            // Validate code pattern
+            if (/module\.exports\s*=/.test(code)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: Do not use module.exports. Functions must define 'async function run() { ... }'. Globals available: api, triggerParams, executionParams.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Step 1: Create the function
+            const fnInput = { name, code };
+            if (description !== undefined)
+                fnInput.description = description;
+            const fnResult = yield sdk.functions.create(fnInput);
+            const fn = fnResult.data;
+            const fnId = fn.id;
+            // If no trigger requested, return function only
+            if (!trigger) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `Function created:`,
+                                `  ID: ${fnId}`,
+                                `  Name: ${name}`,
+                                ``,
+                                `No trigger requested. Use create_trigger to wire one later.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            // Step 2: Build trigger input from the simplified config
+            const typeMap = {
+                on_demand: "on-demand",
+                record: "event-driven",
+                schedule: "scheduled",
+                endpoint: "endpoint",
+            };
+            const executionType = typeMap[trigger.type];
+            const triggerName = trigger.name || `${name} trigger`;
+            const triggerInput = {
+                name: triggerName,
+                functionId: fnId,
+                executionType,
+            };
+            if (trigger.description !== undefined)
+                triggerInput.description = trigger.description;
+            // Build triggerMetadata based on type
+            const meta = {};
+            if (trigger.params)
+                meta.params = trigger.params;
+            if (trigger.type === "record") {
+                if (trigger.recordSlug)
+                    meta.recordSlug = trigger.recordSlug;
+                if (trigger.event)
+                    meta.eventType = trigger.event;
+            }
+            else if (trigger.type === "schedule") {
+                meta.scheduleType = "cron";
+                if (trigger.cronExpression)
+                    meta.cronExpression = trigger.cronExpression;
+            }
+            else if (trigger.type === "endpoint") {
+                if (trigger.endpointPath)
+                    meta.path = trigger.endpointPath;
+            }
+            if (Object.keys(meta).length > 0)
+                triggerInput.triggerMetadata = meta;
+            // Step 3: Create the trigger
+            let triggerData;
+            try {
+                const triggerResult = yield sdk.triggers.create(triggerInput);
+                triggerData = triggerResult.data;
+            }
+            catch (triggerError) {
+                // Function succeeded but trigger failed — report both
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `Function created:`,
+                                `  ID: ${fnId}`,
+                                `  Name: ${name}`,
+                                ``,
+                                formatError(triggerError, "creating trigger"),
+                                ``,
+                                `The function was created successfully but the trigger failed. You can retry with create_trigger using functionId '${fnId}'.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            // Build a human-friendly trigger type label
+            let typeLabel = trigger.type;
+            if (trigger.type === "record" && trigger.event && trigger.recordSlug) {
+                typeLabel = `record (${trigger.event} on ${trigger.recordSlug})`;
+            }
+            else if (trigger.type === "schedule" && trigger.cronExpression) {
+                typeLabel = `schedule (${trigger.cronExpression})`;
+            }
+            else if (trigger.type === "endpoint" && trigger.endpointPath) {
+                typeLabel = `endpoint (/${trigger.endpointPath})`;
+            }
+            const lines = [
+                `Function created:`,
+                `  ID: ${fnId}`,
+                `  Name: ${name}`,
+                ``,
+                `Trigger created:`,
+                `  ID: ${triggerData.id}`,
+                `  Type: ${typeLabel}`,
+                ``,
+            ];
+            if (trigger.type === "on_demand") {
+                lines.push(`Your function is ready. Invoke it via the trigger or use invoke_trigger with ID ${triggerData.id}.`);
+            }
+            else if (trigger.type === "endpoint") {
+                lines.push(`Your function is ready. Invoke it via invoke_endpoint with path '${trigger.endpointPath}' or use invoke_trigger with ID ${triggerData.id}.`);
+            }
+            else {
+                lines.push(`Your function is ready. Invoke it via the trigger or use invoke_trigger with ID ${triggerData.id}.`);
+            }
+            return {
+                content: [
+                    { type: "text", text: lines.join("\n") },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatError(error, `scaffolding function '${name}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
 }

package/dist/tools/describe.js

@@ -987,7 +987,7 @@ function registerDescribeTools(server) {
                         domain: "Orchestrations",
                         description: "Orchestrations are multi-step workflows that chain compute functions together. Each step executes a function and passes its output to the next step.",
                         orchestration_shape: {
-                            id: "UUID",
+                            id: "Prefixed xid (e.g. orch_ctb5h4l6n7m8p9q0r1s2)",
                             name: "string",
                             description: "string | null",
                             status: "'draft' | 'active' | 'paused'",
@@ -1058,8 +1058,8 @@ function registerDescribeTools(server) {
                             },
                         },
                         run_shape: {
-                            id: "UUID",
-                            orchestrationId: "UUID",
+                            id: "Prefixed xid (e.g. orun_ctb5h4l6n7m8p9q0r1s2)",
+                            orchestrationId: "Prefixed xid (e.g. orch_ctb5h4l6n7m8p9q0r1s2)",
                             status: "'pending' | 'running' | 'waiting' | 'completed' | 'failed'",
                             input: "object — the input data provided when the run was triggered",
                             output: "object | null — final output after all steps complete",
@@ -1068,7 +1068,7 @@ function registerDescribeTools(server) {
                             correlationId: "string | null — optional tracing ID",
                         },
                         run_step_shape: {
-                            stepId: "UUID",
+                            stepId: "Prefixed xid (e.g. ostep_ctb5h4l6n7m8p9q0r1s2)",
                             status: "'pending' | 'running' | 'completed' | 'failed' | 'skipped'",
                             input: "object — input passed to this step",
                             output: "object | null — output returned by this step",
@@ -1903,7 +1903,7 @@ function registerDescribeTools(server) {
                             },
                             "start-orchestration": {
                                 description: "Start an orchestration workflow run. Use for multi-step processes.",
-                                targetRef: "Orchestration ID (UUID)",
+                                targetRef: "Orchestration ID (prefixed xid, e.g. orch_...)",
                                 typical_activation: "button",
                                 executionMode: "'fire-and-poll' recommended — orchestrations are long-running",
                             },

package/dist/tools/records.d.ts

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

package/dist/tools/records.js

@@ -8,8 +8,12 @@ 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.registerRecordTools = registerRecordTools;
+const axios_1 = __importDefault(require("axios"));
 const zod_1 = require("zod");
 function formatError(error, context) {
     var _a, _b;
@@ -33,7 +37,59 @@ function formatError(error, context) {
     }
     return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
 }
-function registerRecordTools(server, sdk) {
+/**
+ * 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.queryRecords("__noop__", { limit: 1 });
+        }
+        catch ( /* token refresh side effect */_a) { /* token refresh side effect */ }
+        return sdk.getToken();
+    });
+}
+/**
+ * Creates an axios instance pointing at the data service records API for a given recordSlug.
+ */
+function createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug) {
+    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/records/slug/${recordSlug}`;
+    const client = axios_1.default.create({ baseURL, proxy: false });
+    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.queryRecords("__noop__", { 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 registerRecordTools(server, sdk, centraliUrl, workspaceId) {
     server.tool("query_records", "Query records from a collection with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).", {
         recordSlug: zod_1.z
             .string()
@@ -268,4 +324,153 @@ function registerRecordTools(server, sdk) {
             };
         }
     }));
+    // ── Bulk Operations (1 aggregate event per operation) ───────────────
+    server.tool("bulk_create_records", `Bulk create multiple records in a collection. All records are created in a single transaction. Publishes ONE aggregate 'records_bulk_created' event (not one per record). Use this when downstream triggers should process all records together as a batch. Max 1000 records per call. For individual events per record, use batch_create_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug (e.g., 'orders')"),
+        records: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .describe("Array of record data objects to create (max 1000). Each object has field names as keys."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, records }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const result = yield client.post("/bulk", records);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `bulk creating records in '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("bulk_update_records", `Bulk update multiple records with the same data. All records are updated in a single transaction. Publishes ONE aggregate 'records_bulk_updated' event (not one per record). Use this when all records need the same change and downstream triggers should process them together. For different data per record or individual events, use batch_update_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug"),
+        ids: zod_1.z.array(zod_1.z.string()).describe("Array of record IDs (UUIDs) to update"),
+        data: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.any())
+            .describe("Object with fields to set on ALL specified records (same data applied to each)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, ids, data }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const result = yield client.patch("/bulk", { ids, data });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `bulk updating records in '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("bulk_delete_records", `Bulk delete multiple records. All records are deleted in a single transaction. Publishes ONE aggregate 'records_bulk_deleted' event (not one per record). Use this when downstream triggers should process all deletions together. For individual events per deletion, use batch_delete_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug"),
+        ids: zod_1.z.array(zod_1.z.string()).describe("Array of record IDs (UUIDs) to delete"),
+        hard: zod_1.z
+            .boolean()
+            .optional()
+            .describe("If true, permanently delete. Default: false (soft delete, can be restored)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, ids, hard }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const body = { ids };
+            if (hard !== undefined)
+                body.hard = hard;
+            const result = yield client.delete("/bulk", { data: body });
+            const deleteType = hard ? "permanently deleted" : "soft-deleted";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${ids.length} records ${deleteType} from '${recordSlug}'.\n\n${JSON.stringify(result.data, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `bulk deleting records from '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    // ── Batch Operations (1 event per record) ──────────────────────────
+    server.tool("batch_create_records", `Create multiple records individually. Each record gets its own 'record_created' event. Use this when downstream triggers (functions, webhooks, orchestrations) should process each record separately. Supports partial failure — some records can succeed even if others fail. For a single aggregate event, use bulk_create_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug (e.g., 'orders')"),
+        records: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .describe("Array of record data objects to create. Each object has field names as keys."),
+        stopOnError: zod_1.z
+            .boolean()
+            .optional()
+            .describe("If true, stop processing on the first error. Default: false (continue and report failures)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, records, stopOnError }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const params = {};
+            if (stopOnError !== undefined)
+                params.stopOnError = stopOnError;
+            const result = yield client.post("/batch", records, { params });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `batch creating records in '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("batch_update_records", `Update multiple records individually with different data per record. Each record gets its own 'record_updated' event. Use this when each record needs different changes and downstream triggers should process each update separately. For the same change applied to all records with a single event, use bulk_update_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug"),
+        updates: zod_1.z
+            .array(zod_1.z.object({
+            id: zod_1.z.string().describe("The record ID (UUID) to update"),
+            data: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.any())
+                .describe("Object with fields to update for this specific record"),
+        }))
+            .describe("Array of update objects, each with an 'id' and 'data' to apply to that record"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, updates }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const result = yield client.patch("/batch", updates);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `batch updating records in '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("batch_delete_records", `Delete multiple records individually. Each record gets its own 'record_deleted' event. Use this when downstream triggers should process each deletion separately. For a single aggregate event, use bulk_delete_records instead.`, {
+        recordSlug: zod_1.z.string().describe("The collection's record slug"),
+        ids: zod_1.z.array(zod_1.z.string()).describe("Array of record IDs (UUIDs) to delete"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, ids }) {
+        try {
+            const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+            const result = yield client.delete("/batch", { data: { ids } });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${ids.length} records batch-deleted from '${recordSlug}'.\n\n${JSON.stringify(result.data, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error, `batch deleting records from '${recordSlug}'`) }],
+                isError: true,
+            };
+        }
+    }));
 }

package/dist/tools/structures.js

@@ -500,4 +500,143 @@ Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAl
             };
         }
     }));
+    server.tool("explore_collections", "Get a compact overview of ALL collections in the workspace with their field names, types, and constraints. Returns everything in one call — no need to list collections and then get each one separately.", {
+        includeRecordCounts: zod_1.z.boolean().optional().describe("Include record counts for each collection (slower, requires an extra query per collection). Defaults to false."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ includeRecordCounts }) {
+        var _b, _c, _d, _e;
+        try {
+            // Fetch all collections (paginate to get everything)
+            const firstPage = yield sdk.collections.list({ page: 1, limit: 100 });
+            let allCollections = (_b = firstPage.data) !== null && _b !== void 0 ? _b : [];
+            const meta = firstPage.meta;
+            if (meta && meta.total > allCollections.length) {
+                const totalPages = Math.ceil(meta.total / 100);
+                for (let page = 2; page <= totalPages; page++) {
+                    const nextPage = yield sdk.collections.list({ page, limit: 100 });
+                    allCollections = allCollections.concat((_c = nextPage.data) !== null && _c !== void 0 ? _c : []);
+                }
+            }
+            if (allCollections.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No collections found in this workspace." }],
+                };
+            }
+            // Fetch full schema for each collection
+            const details = yield Promise.all(allCollections.map((col) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c;
+                try {
+                    const full = yield sdk.collections.getBySlug(col.recordSlug);
+                    const detail = Object.assign({}, ((_a = full.data) !== null && _a !== void 0 ? _a : col));
+                    if (includeRecordCounts) {
+                        try {
+                            const records = yield sdk.queryRecords(col.recordSlug, { pageSize: 1 });
+                            detail._recordCount = (_c = (_b = records.meta) === null || _b === void 0 ? void 0 : _b.total) !== null && _c !== void 0 ? _c : "unknown";
+                        }
+                        catch (_d) {
+                            detail._recordCount = "unknown";
+                        }
+                    }
+                    return detail;
+                }
+                catch (_e) {
+                    return Object.assign(Object.assign({}, col), { _fetchError: true });
+                }
+            })));
+            // Format as compact readable text
+            const lines = [];
+            for (const col of details) {
+                lines.push(`=== Collection: ${col.name} (slug: ${col.recordSlug}) ===`);
+                if (col.description) {
+                    lines.push(`Description: ${col.description}`);
+                }
+                lines.push(`Schema mode: ${(_d = col.schemaDiscoveryMode) !== null && _d !== void 0 ? _d : "strict"}`);
+                if (col.tags && col.tags.length > 0) {
+                    lines.push(`Tags: ${col.tags.join(", ")}`);
+                }
+                if (col._fetchError) {
+                    lines.push("Fields: (unable to fetch full schema)");
+                }
+                else if (col.properties && col.properties.length > 0) {
+                    lines.push("Fields:");
+                    for (const prop of col.properties) {
+                        const parts = [];
+                        // Base type
+                        let typeStr = prop.type;
+                        if (prop.type === "string" && prop.renderAs) {
+                            typeStr = prop.renderAs;
+                        }
+                        if (prop.type === "array" && ((_e = prop.items) === null || _e === void 0 ? void 0 : _e.type)) {
+                            typeStr = `array of ${prop.items.type}`;
+                        }
+                        if (prop.type === "reference" && prop.target) {
+                            typeStr = `reference -> ${prop.target}`;
+                            if (prop.relationship)
+                                typeStr += ` (${prop.relationship})`;
+                        }
+                        // Enum / select values
+                        if (prop.enum && prop.enum.length > 0) {
+                            const vals = prop.enum.map(String);
+                            if (vals.length <= 8) {
+                                typeStr = `select: ${vals.join("|")}`;
+                            }
+                            else {
+                                typeStr = `select: ${vals.slice(0, 6).join("|")}|... (${vals.length} values)`;
+                            }
+                        }
+                        parts.push(typeStr);
+                        // Constraints
+                        if (prop.required)
+                            parts.push("required");
+                        if (prop.isUnique)
+                            parts.push("unique");
+                        if (prop.immutable)
+                            parts.push("immutable");
+                        if (prop.isSecret)
+                            parts.push("secret");
+                        if (prop.nullable)
+                            parts.push("nullable");
+                        if (prop.default !== undefined)
+                            parts.push(`default: ${JSON.stringify(prop.default)}`);
+                        if (prop.minimum !== undefined)
+                            parts.push(`min: ${prop.minimum}`);
+                        if (prop.maximum !== undefined)
+                            parts.push(`max: ${prop.maximum}`);
+                        if (prop.minLength !== undefined)
+                            parts.push(`minLen: ${prop.minLength}`);
+                        if (prop.maxLength !== undefined)
+                            parts.push(`maxLen: ${prop.maxLength}`);
+                        if (prop.pattern)
+                            parts.push(`pattern: ${prop.pattern}`);
+                        if (prop.expression)
+                            parts.push("computed");
+                        if (prop.autoIncrement)
+                            parts.push("auto-increment");
+                        lines.push(`  - ${prop.name} (${parts.join(", ")})`);
+                    }
+                }
+                else {
+                    lines.push("Fields: (none)");
+                }
+                if (includeRecordCounts && col._recordCount !== undefined) {
+                    lines.push(`Records: ${col._recordCount}`);
+                }
+                lines.push("");
+            }
+            lines.push(`Total: ${details.length} collection(s)`);
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatError(error, "exploring collections"),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.4.8",
+  "version": "4.4.9",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

package/src/index.ts

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

package/src/tools/compute.ts

@@ -828,4 +828,176 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
       }
     }
   );
+
+  // ── Scaffold (function + trigger in one step) ─────────────────────
+
+  server.tool(
+    "scaffold_function",
+    "Create a compute function with boilerplate code and optionally wire a trigger — all in one step. The function uses the required `async function run()` pattern with `api.*` globals, `triggerParams`, and `executionParams` available.",
+    {
+      name: z.string().describe("Function name"),
+      description: z.string().optional().describe("Function description"),
+      code: z.string().describe("Function code. Must use `async function run() { ... }` pattern. Has access to `api` (data operations), `triggerParams` (static config), and `executionParams` (runtime parameters)."),
+      trigger: z.object({
+        type: z.enum(["on_demand", "record", "schedule", "endpoint"]).describe("Trigger type"),
+        name: z.string().optional().describe("Trigger name (auto-generated if omitted)"),
+        description: z.string().optional(),
+        // Record trigger fields
+        recordSlug: z.string().optional().describe("Collection slug (required for record triggers)"),
+        event: z.string().optional().describe("Record event: afterCreate, afterUpdate, afterDelete (required for record triggers)"),
+        // Schedule trigger fields
+        cronExpression: z.string().optional().describe("Cron expression (required for schedule triggers)"),
+        // Endpoint trigger fields
+        endpointPath: z.string().optional().describe("URL path segment (required for endpoint triggers)"),
+        // Common
+        params: z.record(z.string(), z.any()).optional().describe("Static trigger parameters available as triggerParams in the function"),
+      }).optional().describe("Trigger configuration. If omitted, creates function without a trigger."),
+    },
+    async ({ name, description, code, trigger }) => {
+      try {
+        // Validate code pattern
+        if (/module\.exports\s*=/.test(code)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: Do not use module.exports. Functions must define 'async function run() { ... }'. Globals available: api, triggerParams, executionParams.",
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Step 1: Create the function
+        const fnInput: Record<string, any> = { name, code };
+        if (description !== undefined) fnInput.description = description;
+
+        const fnResult = await sdk.functions.create(fnInput as any);
+        const fn = fnResult.data;
+        const fnId = fn.id;
+
+        // If no trigger requested, return function only
+        if (!trigger) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `Function created:`,
+                  `  ID: ${fnId}`,
+                  `  Name: ${name}`,
+                  ``,
+                  `No trigger requested. Use create_trigger to wire one later.`,
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+
+        // Step 2: Build trigger input from the simplified config
+        const typeMap: Record<string, string> = {
+          on_demand: "on-demand",
+          record: "event-driven",
+          schedule: "scheduled",
+          endpoint: "endpoint",
+        };
+
+        const executionType = typeMap[trigger.type];
+        const triggerName = trigger.name || `${name} trigger`;
+
+        const triggerInput: Record<string, any> = {
+          name: triggerName,
+          functionId: fnId,
+          executionType,
+        };
+        if (trigger.description !== undefined) triggerInput.description = trigger.description;
+
+        // Build triggerMetadata based on type
+        const meta: Record<string, any> = {};
+        if (trigger.params) meta.params = trigger.params;
+
+        if (trigger.type === "record") {
+          if (trigger.recordSlug) meta.recordSlug = trigger.recordSlug;
+          if (trigger.event) meta.eventType = trigger.event;
+        } else if (trigger.type === "schedule") {
+          meta.scheduleType = "cron";
+          if (trigger.cronExpression) meta.cronExpression = trigger.cronExpression;
+        } else if (trigger.type === "endpoint") {
+          if (trigger.endpointPath) meta.path = trigger.endpointPath;
+        }
+
+        if (Object.keys(meta).length > 0) triggerInput.triggerMetadata = meta;
+
+        // Step 3: Create the trigger
+        let triggerData: any;
+        try {
+          const triggerResult = await sdk.triggers.create(triggerInput as any);
+          triggerData = triggerResult.data;
+        } catch (triggerError: unknown) {
+          // Function succeeded but trigger failed — report both
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `Function created:`,
+                  `  ID: ${fnId}`,
+                  `  Name: ${name}`,
+                  ``,
+                  formatError(triggerError, "creating trigger"),
+                  ``,
+                  `The function was created successfully but the trigger failed. You can retry with create_trigger using functionId '${fnId}'.`,
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+
+        // Build a human-friendly trigger type label
+        let typeLabel = trigger.type as string;
+        if (trigger.type === "record" && trigger.event && trigger.recordSlug) {
+          typeLabel = `record (${trigger.event} on ${trigger.recordSlug})`;
+        } else if (trigger.type === "schedule" && trigger.cronExpression) {
+          typeLabel = `schedule (${trigger.cronExpression})`;
+        } else if (trigger.type === "endpoint" && trigger.endpointPath) {
+          typeLabel = `endpoint (/${trigger.endpointPath})`;
+        }
+
+        const lines = [
+          `Function created:`,
+          `  ID: ${fnId}`,
+          `  Name: ${name}`,
+          ``,
+          `Trigger created:`,
+          `  ID: ${triggerData.id}`,
+          `  Type: ${typeLabel}`,
+          ``,
+        ];
+
+        if (trigger.type === "on_demand") {
+          lines.push(`Your function is ready. Invoke it via the trigger or use invoke_trigger with ID ${triggerData.id}.`);
+        } else if (trigger.type === "endpoint") {
+          lines.push(`Your function is ready. Invoke it via invoke_endpoint with path '${trigger.endpointPath}' or use invoke_trigger with ID ${triggerData.id}.`);
+        } else {
+          lines.push(`Your function is ready. Invoke it via the trigger or use invoke_trigger with ID ${triggerData.id}.`);
+        }
+
+        return {
+          content: [
+            { type: "text", text: lines.join("\n") },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `scaffolding function '${name}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
 }

package/src/tools/describe.ts

@@ -1083,7 +1083,7 @@ export function registerDescribeTools(server: McpServer) {
               description:
                 "Orchestrations are multi-step workflows that chain compute functions together. Each step executes a function and passes its output to the next step.",
               orchestration_shape: {
-                id: "UUID",
+                id: "Prefixed xid (e.g. orch_ctb5h4l6n7m8p9q0r1s2)",
                 name: "string",
                 description: "string | null",
                 status: "'draft' | 'active' | 'paused'",
@@ -1154,8 +1154,8 @@ export function registerDescribeTools(server: McpServer) {
                 },
               },
               run_shape: {
-                id: "UUID",
-                orchestrationId: "UUID",
+                id: "Prefixed xid (e.g. orun_ctb5h4l6n7m8p9q0r1s2)",
+                orchestrationId: "Prefixed xid (e.g. orch_ctb5h4l6n7m8p9q0r1s2)",
                 status: "'pending' | 'running' | 'waiting' | 'completed' | 'failed'",
                 input: "object — the input data provided when the run was triggered",
                 output: "object | null — final output after all steps complete",
@@ -1164,7 +1164,7 @@ export function registerDescribeTools(server: McpServer) {
                 correlationId: "string | null — optional tracing ID",
               },
               run_step_shape: {
-                stepId: "UUID",
+                stepId: "Prefixed xid (e.g. ostep_ctb5h4l6n7m8p9q0r1s2)",
                 status: "'pending' | 'running' | 'completed' | 'failed' | 'skipped'",
                 input: "object — input passed to this step",
                 output: "object | null — output returned by this step",
@@ -2152,7 +2152,7 @@ export function registerDescribeTools(server: McpServer) {
                 "start-orchestration": {
                   description:
                     "Start an orchestration workflow run. Use for multi-step processes.",
-                  targetRef: "Orchestration ID (UUID)",
+                  targetRef: "Orchestration ID (prefixed xid, e.g. orch_...)",
                   typical_activation: "button",
                   executionMode:
                     "'fire-and-poll' recommended — orchestrations are long-running",

package/src/tools/records.ts

@@ -1,5 +1,6 @@
 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 {
@@ -23,7 +24,64 @@ function formatError(error: unknown, context: string): string {
   return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
 }
 
-export function registerRecordTools(server: McpServer, sdk: CentraliSDK) {
+/**
+ * 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.queryRecords("__noop__", { limit: 1 });
+  } catch { /* token refresh side effect */ }
+  return sdk.getToken();
+}
+
+/**
+ * Creates an axios instance pointing at the data service records API for a given recordSlug.
+ */
+function createRecordsClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string, recordSlug: 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/records/slug/${recordSlug}`;
+
+  const client = axios.create({ baseURL, proxy: false });
+
+  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.queryRecords("__noop__", { 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 registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
   server.tool(
     "query_records",
     "Query records from a collection with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).",
@@ -315,4 +373,185 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK) {
       }
     }
   );
+
+  // ── Bulk Operations (1 aggregate event per operation) ───────────────
+
+  server.tool(
+    "bulk_create_records",
+    `Bulk create multiple records in a collection. All records are created in a single transaction. Publishes ONE aggregate 'records_bulk_created' event (not one per record). Use this when downstream triggers should process all records together as a batch. Max 1000 records per call. For individual events per record, use batch_create_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug (e.g., 'orders')"),
+      records: z
+        .array(z.record(z.string(), z.any()))
+        .describe("Array of record data objects to create (max 1000). Each object has field names as keys."),
+    },
+    async ({ recordSlug, records }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const result = await client.post("/bulk", records);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `bulk creating records in '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "bulk_update_records",
+    `Bulk update multiple records with the same data. All records are updated in a single transaction. Publishes ONE aggregate 'records_bulk_updated' event (not one per record). Use this when all records need the same change and downstream triggers should process them together. For different data per record or individual events, use batch_update_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug"),
+      ids: z.array(z.string()).describe("Array of record IDs (UUIDs) to update"),
+      data: z
+        .record(z.string(), z.any())
+        .describe("Object with fields to set on ALL specified records (same data applied to each)"),
+    },
+    async ({ recordSlug, ids, data }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const result = await client.patch("/bulk", { ids, data });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `bulk updating records in '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "bulk_delete_records",
+    `Bulk delete multiple records. All records are deleted in a single transaction. Publishes ONE aggregate 'records_bulk_deleted' event (not one per record). Use this when downstream triggers should process all deletions together. For individual events per deletion, use batch_delete_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug"),
+      ids: z.array(z.string()).describe("Array of record IDs (UUIDs) to delete"),
+      hard: z
+        .boolean()
+        .optional()
+        .describe("If true, permanently delete. Default: false (soft delete, can be restored)"),
+    },
+    async ({ recordSlug, ids, hard }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const body: Record<string, any> = { ids };
+        if (hard !== undefined) body.hard = hard;
+        const result = await client.delete("/bulk", { data: body });
+        const deleteType = hard ? "permanently deleted" : "soft-deleted";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${ids.length} records ${deleteType} from '${recordSlug}'.\n\n${JSON.stringify(result.data, null, 2)}`,
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `bulk deleting records from '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Batch Operations (1 event per record) ──────────────────────────
+
+  server.tool(
+    "batch_create_records",
+    `Create multiple records individually. Each record gets its own 'record_created' event. Use this when downstream triggers (functions, webhooks, orchestrations) should process each record separately. Supports partial failure — some records can succeed even if others fail. For a single aggregate event, use bulk_create_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug (e.g., 'orders')"),
+      records: z
+        .array(z.record(z.string(), z.any()))
+        .describe("Array of record data objects to create. Each object has field names as keys."),
+      stopOnError: z
+        .boolean()
+        .optional()
+        .describe("If true, stop processing on the first error. Default: false (continue and report failures)"),
+    },
+    async ({ recordSlug, records, stopOnError }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const params: Record<string, any> = {};
+        if (stopOnError !== undefined) params.stopOnError = stopOnError;
+        const result = await client.post("/batch", records, { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `batch creating records in '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "batch_update_records",
+    `Update multiple records individually with different data per record. Each record gets its own 'record_updated' event. Use this when each record needs different changes and downstream triggers should process each update separately. For the same change applied to all records with a single event, use bulk_update_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug"),
+      updates: z
+        .array(
+          z.object({
+            id: z.string().describe("The record ID (UUID) to update"),
+            data: z
+              .record(z.string(), z.any())
+              .describe("Object with fields to update for this specific record"),
+          })
+        )
+        .describe("Array of update objects, each with an 'id' and 'data' to apply to that record"),
+    },
+    async ({ recordSlug, updates }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const result = await client.patch("/batch", updates);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `batch updating records in '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "batch_delete_records",
+    `Delete multiple records individually. Each record gets its own 'record_deleted' event. Use this when downstream triggers should process each deletion separately. For a single aggregate event, use bulk_delete_records instead.`,
+    {
+      recordSlug: z.string().describe("The collection's record slug"),
+      ids: z.array(z.string()).describe("Array of record IDs (UUIDs) to delete"),
+    },
+    async ({ recordSlug, ids }) => {
+      try {
+        const client = createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug);
+        const result = await client.delete("/batch", { data: { ids } });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${ids.length} records batch-deleted from '${recordSlug}'.\n\n${JSON.stringify(result.data, null, 2)}`,
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `batch deleting records from '${recordSlug}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
 }

package/src/tools/structures.ts

@@ -540,4 +540,144 @@ Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAl
       }
     }
   );
+
+  server.tool(
+    "explore_collections",
+    "Get a compact overview of ALL collections in the workspace with their field names, types, and constraints. Returns everything in one call — no need to list collections and then get each one separately.",
+    {
+      includeRecordCounts: z.boolean().optional().describe("Include record counts for each collection (slower, requires an extra query per collection). Defaults to false."),
+    },
+    async ({ includeRecordCounts }) => {
+      try {
+        // Fetch all collections (paginate to get everything)
+        const firstPage = await sdk.collections.list({ page: 1, limit: 100 });
+        let allCollections = firstPage.data ?? [];
+        const meta = (firstPage as any).meta;
+        if (meta && meta.total > allCollections.length) {
+          const totalPages = Math.ceil(meta.total / 100);
+          for (let page = 2; page <= totalPages; page++) {
+            const nextPage = await sdk.collections.list({ page, limit: 100 });
+            allCollections = allCollections.concat(nextPage.data ?? []);
+          }
+        }
+
+        if (allCollections.length === 0) {
+          return {
+            content: [{ type: "text", text: "No collections found in this workspace." }],
+          };
+        }
+
+        // Fetch full schema for each collection
+        const details = await Promise.all(
+          allCollections.map(async (col: any) => {
+            try {
+              const full = await sdk.collections.getBySlug(col.recordSlug);
+              const detail: any = { ...(full.data ?? col) };
+
+              if (includeRecordCounts) {
+                try {
+                  const records = await sdk.queryRecords(col.recordSlug, { pageSize: 1 } as any);
+                  detail._recordCount = (records as any).meta?.total ?? "unknown";
+                } catch {
+                  detail._recordCount = "unknown";
+                }
+              }
+
+              return detail;
+            } catch {
+              return { ...col, _fetchError: true };
+            }
+          })
+        );
+
+        // Format as compact readable text
+        const lines: string[] = [];
+        for (const col of details) {
+          lines.push(`=== Collection: ${col.name} (slug: ${col.recordSlug}) ===`);
+          if (col.description) {
+            lines.push(`Description: ${col.description}`);
+          }
+          lines.push(`Schema mode: ${col.schemaDiscoveryMode ?? "strict"}`);
+          if (col.tags && col.tags.length > 0) {
+            lines.push(`Tags: ${col.tags.join(", ")}`);
+          }
+
+          if (col._fetchError) {
+            lines.push("Fields: (unable to fetch full schema)");
+          } else if (col.properties && col.properties.length > 0) {
+            lines.push("Fields:");
+            for (const prop of col.properties) {
+              const parts: string[] = [];
+
+              // Base type
+              let typeStr = prop.type;
+              if (prop.type === "string" && prop.renderAs) {
+                typeStr = prop.renderAs;
+              }
+              if (prop.type === "array" && prop.items?.type) {
+                typeStr = `array of ${prop.items.type}`;
+              }
+              if (prop.type === "reference" && prop.target) {
+                typeStr = `reference -> ${prop.target}`;
+                if (prop.relationship) typeStr += ` (${prop.relationship})`;
+              }
+
+              // Enum / select values
+              if (prop.enum && prop.enum.length > 0) {
+                const vals = prop.enum.map(String);
+                if (vals.length <= 8) {
+                  typeStr = `select: ${vals.join("|")}`;
+                } else {
+                  typeStr = `select: ${vals.slice(0, 6).join("|")}|... (${vals.length} values)`;
+                }
+              }
+
+              parts.push(typeStr);
+
+              // Constraints
+              if (prop.required) parts.push("required");
+              if (prop.isUnique) parts.push("unique");
+              if (prop.immutable) parts.push("immutable");
+              if (prop.isSecret) parts.push("secret");
+              if (prop.nullable) parts.push("nullable");
+              if (prop.default !== undefined) parts.push(`default: ${JSON.stringify(prop.default)}`);
+              if (prop.minimum !== undefined) parts.push(`min: ${prop.minimum}`);
+              if (prop.maximum !== undefined) parts.push(`max: ${prop.maximum}`);
+              if (prop.minLength !== undefined) parts.push(`minLen: ${prop.minLength}`);
+              if (prop.maxLength !== undefined) parts.push(`maxLen: ${prop.maxLength}`);
+              if (prop.pattern) parts.push(`pattern: ${prop.pattern}`);
+              if (prop.expression) parts.push("computed");
+              if (prop.autoIncrement) parts.push("auto-increment");
+
+              lines.push(`  - ${prop.name} (${parts.join(", ")})`);
+            }
+          } else {
+            lines.push("Fields: (none)");
+          }
+
+          if (includeRecordCounts && col._recordCount !== undefined) {
+            lines.push(`Records: ${col._recordCount}`);
+          }
+
+          lines.push("");
+        }
+
+        lines.push(`Total: ${details.length} collection(s)`);
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, "exploring collections"),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
 }