@centrali-io/centrali-mcp 4.2.0 → 4.2.2

package/dist/tools/describe.js

@@ -0,0 +1,1485 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDescribeTools = registerDescribeTools;
+/**
+ * Introspection tools that teach AI assistants the valid shapes, schemas,
+ * and domain concepts for every Centrali API. These tools return static
+ * documentation — no network calls, no auth required.
+ *
+ * Pattern inspired by Supabase MCP (list_tables / get_schemas) and
+ * Stripe MCP (search_stripe_documentation).
+ */
+function registerDescribeTools(server) {
+    // ── Master describe tool ────────────────────────────────────────────
+    server.tool("describe_centrali", "Get an overview of all Centrali platform capabilities and API domains. Call this first to understand what Centrali can do and which describe_* tool to call for deeper schema details.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        platform: "Centrali",
+                        description: "Centrali is a low-code backend platform. You define data structures (collections), write compute functions, build orchestration workflows, and publish pages — all through APIs.",
+                        domains: {
+                            collections: {
+                                summary: "Data schemas (formerly 'structures'). Define the shape of your data — fields, types, constraints, references.",
+                                describeWith: "describe_collections",
+                                tools: [
+                                    "list_collections",
+                                    "get_collection",
+                                    "create_collection",
+                                    "update_collection",
+                                    "delete_collection",
+                                    "list_structures (deprecated)",
+                                    "get_structure (deprecated)",
+                                ],
+                            },
+                            records: {
+                                summary: "CRUD operations on data stored in collections. Supports filtering, sorting, pagination, field expansion, upsert, and soft/hard delete.",
+                                describeWith: "describe_records",
+                                tools: [
+                                    "query_records",
+                                    "get_record",
+                                    "create_record",
+                                    "update_record",
+                                    "delete_record",
+                                    "upsert_record",
+                                    "get_records_by_ids",
+                                    "restore_record",
+                                ],
+                            },
+                            search: {
+                                summary: "Full-text search across records powered by Meilisearch. Can filter by collection.",
+                                describeWith: "describe_search",
+                                tools: ["search_records"],
+                            },
+                            compute: {
+                                summary: "Server-side JavaScript functions with triggers (on-demand, event-driven, scheduled, webhook).",
+                                describeWith: "describe_compute",
+                                tools: [
+                                    "list_functions",
+                                    "get_function",
+                                    "create_function",
+                                    "update_function",
+                                    "delete_function",
+                                    "test_function",
+                                    "list_triggers",
+                                    "get_trigger",
+                                    "create_trigger",
+                                    "update_trigger",
+                                    "delete_trigger",
+                                    "invoke_trigger",
+                                    "pause_trigger",
+                                    "resume_trigger",
+                                ],
+                            },
+                            smart_queries: {
+                                summary: "Reusable, parameterized queries defined in the console. Support {{variable}} substitution.",
+                                describeWith: "describe_smart_queries",
+                                tools: [
+                                    "list_smart_queries",
+                                    "get_smart_query",
+                                    "create_smart_query",
+                                    "update_smart_query",
+                                    "delete_smart_query",
+                                    "execute_smart_query",
+                                    "test_smart_query",
+                                ],
+                            },
+                            orchestrations: {
+                                summary: "Multi-step workflows that chain compute functions. Support sequential execution with input/output passing between steps.",
+                                describeWith: "describe_orchestrations",
+                                tools: [
+                                    "list_orchestrations",
+                                    "get_orchestration",
+                                    "create_orchestration",
+                                    "update_orchestration",
+                                    "delete_orchestration",
+                                    "activate_orchestration",
+                                    "pause_orchestration",
+                                    "trigger_orchestration",
+                                    "list_orchestration_runs",
+                                    "get_orchestration_run",
+                                ],
+                            },
+                            insights: {
+                                summary: "AI-powered anomaly detection. Scans data for unusual patterns (spikes, drops, outliers) and generates actionable insights.",
+                                describeWith: "describe_insights",
+                                tools: [
+                                    "list_insights",
+                                    "get_insight",
+                                    "acknowledge_insight",
+                                    "dismiss_insight",
+                                    "get_insights_summary",
+                                    "trigger_anomaly_analysis",
+                                ],
+                            },
+                            validation: {
+                                summary: "AI-powered data quality scanning. Detects typos, format issues, duplicates, semantic errors, and type mismatches.",
+                                describeWith: "describe_validation",
+                                tools: [
+                                    "trigger_validation_scan",
+                                    "list_validation_suggestions",
+                                    "get_validation_summary",
+                                    "accept_validation_suggestion",
+                                    "reject_validation_suggestion",
+                                ],
+                            },
+                            pages: {
+                                summary: "UI page builder. Create list views, detail views, forms, and dashboards backed by collection data. Supports publishing, versioning, access control, and theming.",
+                                describeWith: "describe_pages",
+                                tools: [
+                                    "list_pages",
+                                    "get_page",
+                                    "create_page",
+                                    "update_page",
+                                    "delete_page",
+                                    "save_page_draft",
+                                    "get_page_draft",
+                                    "list_page_versions",
+                                    "validate_page",
+                                    "publish_page",
+                                    "unpublish_page",
+                                    "set_page_access_policy",
+                                    "get_page_theme",
+                                    "set_page_theme",
+                                    "get_navigation",
+                                    "set_navigation",
+                                    "delete_navigation",
+                                    "generate_starter_pages",
+                                    "accept_page_proposal",
+                                ],
+                            },
+                        },
+                        workflow: "Typical workflow: 1) Define collections → 2) Create records → 3) Write compute functions → 4) Wire orchestrations → 5) Build pages to surface data → 6) Publish pages for end users.",
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Collections ────────────────────────────────────────────────────
+    server.tool("describe_collections", "Get the schema reference for Centrali collections (data structures). Explains field types, property shapes, constraints, and how to define data models.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Collections",
+                        description: "Collections (formerly 'structures') define the schema for your data. Each collection has a name, a recordSlug (used in API calls), and an array of properties that define the fields.",
+                        collection_shape: {
+                            id: "UUID — auto-generated",
+                            name: "string — display name (e.g., 'Customers')",
+                            recordSlug: "string — URL-safe identifier used in all record API calls (e.g., 'customers')",
+                            description: "string | null — optional description",
+                            status: "'active' | 'archived'",
+                            properties: "Property[] — array of field definitions (see below)",
+                        },
+                        property_shape: {
+                            name: "string — field name (e.g., 'email', 'totalAmount')",
+                            type: "string — the field data type (see field_types below)",
+                            required: "boolean — whether the field is mandatory",
+                            unique: "boolean — whether values must be unique across records",
+                            defaultValue: "any | null — default value for new records",
+                            description: "string | null — field description",
+                            config: "object | null — type-specific configuration (e.g., min/max for numbers, options for select)",
+                        },
+                        field_types: {
+                            text: "Short text string",
+                            long_text: "Multi-line text / rich text",
+                            number: "Numeric value (integer or decimal). Config: { min, max, precision }",
+                            boolean: "True/false toggle",
+                            date: "Date value (ISO 8601)",
+                            datetime: "Date and time value (ISO 8601 with time)",
+                            email: "Email address (validated format)",
+                            url: "URL (validated format)",
+                            select: "Single choice from predefined options. Config: { options: [{ label, value }] }",
+                            multi_select: "Multiple choices from predefined options. Config: { options: [{ label, value }] }",
+                            reference: "Foreign key to another collection. Config: { referenceSlug: 'other-collection-slug' }",
+                            file: "File attachment (stored in Azure Blob Storage)",
+                            json: "Arbitrary JSON object",
+                            auto_increment: "Auto-incrementing integer (read-only)",
+                        },
+                        crud_tools: {
+                            create_collection: {
+                                description: "Create a new collection with name, slug, properties, and optional settings",
+                                required_params: ["name", "slug"],
+                                optional_params: ["description", "properties", "enableVersioning", "schemaDiscoveryMode", "tags"],
+                            },
+                            update_collection: {
+                                description: "Update an existing collection by ID. Partial updates supported.",
+                                required_params: ["collectionId"],
+                                optional_params: ["name", "description", "properties", "enableVersioning", "tags", "defaultTtlSeconds"],
+                            },
+                            delete_collection: {
+                                description: "Delete a collection by ID. Permanently removes the schema and all records.",
+                                required_params: ["collectionId"],
+                            },
+                        },
+                        tips: [
+                            "Use list_collections to see all collections in the workspace",
+                            "Use get_collection with a recordSlug to see the full property definitions",
+                            "The recordSlug is what you use in query_records, create_record, etc.",
+                            "Reference fields create relationships between collections — use 'expand' parameter in queries to join them",
+                            "Use create_collection to define new data schemas with typed properties",
+                            "Properties array defines the fields — each needs at minimum a name and type",
+                            "Use schemaDiscoveryMode: 'flexible' to auto-add new fields when records are created",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Records ────────────────────────────────────────────────────────
+    server.tool("describe_records", "Get the schema reference for Centrali record operations. Explains filter syntax, sort syntax, pagination, expand, and the data. prefix convention.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Records",
+                        description: "Records are rows of data stored in collections. All custom field values live under the 'data' namespace.",
+                        record_shape: {
+                            id: "UUID — auto-generated",
+                            structureId: "UUID — the collection this record belongs to",
+                            data: "object — all custom field values keyed by field name",
+                            createdAt: "ISO 8601 datetime",
+                            updatedAt: "ISO 8601 datetime",
+                            createdBy: "UUID — user who created the record",
+                            updatedBy: "UUID — user who last updated",
+                            isDeleted: "boolean — true if soft-deleted",
+                        },
+                        filter_syntax: {
+                            description: "Filters are passed as key-value pairs. Keys use the 'data.' prefix for custom fields and bracket notation for operators.",
+                            examples: {
+                                "Exact match": { "data.status": "active" },
+                                "Greater than": { "data.price[gt]": 100 },
+                                "Less than or equal": { "data.age[lte]": 30 },
+                                "Not equal": { "data.type[ne]": "draft" },
+                                "In list": { "data.category[in]": "electronics,books" },
+                                "Not in list": { "data.status[nin]": "deleted,archived" },
+                                "Contains (text)": { "data.name[contains]": "john" },
+                                "Starts with": { "data.email[startswith]": "admin" },
+                                "Ends with": { "data.domain[endswith]": ".com" },
+                            },
+                            operators: [
+                                "eq (default, no bracket needed)",
+                                "ne (not equal)",
+                                "gt (greater than)",
+                                "gte (greater than or equal)",
+                                "lt (less than)",
+                                "lte (less than or equal)",
+                                "in (comma-separated list)",
+                                "nin (not in comma-separated list)",
+                                "contains (substring match)",
+                                "startswith (prefix match)",
+                                "endswith (suffix match)",
+                            ],
+                        },
+                        sort_syntax: {
+                            description: "Sort by a single field. Prefix with '-' for descending order.",
+                            examples: {
+                                "Ascending by date": "createdAt",
+                                "Descending by date": "-createdAt",
+                                "By custom field asc": "data.name",
+                                "By custom field desc": "-data.price",
+                            },
+                        },
+                        pagination: {
+                            page: "1-indexed page number (default: 1)",
+                            pageSize: "Records per page (default: 50, max: 500)",
+                            response_includes: "total, page, pageSize, totalPages in the response metadata",
+                        },
+                        expand: {
+                            description: "Comma-separated list of reference field names to expand (join). Returns the full referenced record instead of just the ID.",
+                            example: "expand: 'customer,product'",
+                        },
+                        upsert: {
+                            description: "Atomic create-or-update. Provide 'match' fields to find existing record and 'data' for the full record body.",
+                            example: {
+                                match: { sku: "WIDGET-001" },
+                                data: { sku: "WIDGET-001", name: "Widget", price: 9.99 },
+                            },
+                            result: "Returns { operation: 'created' | 'updated', data: record }",
+                        },
+                        tips: [
+                            "Always use the 'data.' prefix when filtering on custom fields",
+                            "System fields (id, createdAt, updatedAt) don't need the 'data.' prefix",
+                            "Use upsert_record for idempotent imports — it won't create duplicates",
+                            "Soft-deleted records can be restored with restore_record",
+                            "Use get_records_by_ids for batch lookups (more efficient than individual get_record calls)",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Search ─────────────────────────────────────────────────────────
+    server.tool("describe_search", "Get the schema reference for Centrali full-text search. Explains search behavior, filtering, and result format.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Search",
+                        description: "Full-text search across all records in the workspace, powered by Meilisearch. Searches across all indexed text fields in records.",
+                        parameters: {
+                            query: "string — the search query. Supports natural language, partial matches, and typo tolerance.",
+                            collections: "string | string[] — optional filter to limit search to specific collection(s) by slug",
+                            limit: "number — max results (default: 20, max: 100)",
+                        },
+                        result_shape: {
+                            hits: "Array of matching records with _rankingScore",
+                            query: "The original search query",
+                            processingTimeMs: "Search duration in milliseconds",
+                        },
+                        tips: [
+                            "Search is typo-tolerant — 'custmer' will match 'customer'",
+                            "Use the collections filter to narrow results to a specific data type",
+                            "Results are ranked by relevance — most relevant first",
+                            "Search only works on text/string fields — numeric fields are not full-text indexed",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Compute ────────────────────────────────────────────────────────
+    server.tool("describe_compute", "Get the schema reference for Centrali compute functions and triggers. Explains function types, trigger execution modes, and invocation patterns.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Compute",
+                        description: "Compute functions are server-side JavaScript code blocks. They are executed via triggers, which define when and how a function runs.",
+                        function_shape: {
+                            id: "UUID",
+                            name: "string — display name",
+                            slug: "string — unique identifier",
+                            description: "string | null",
+                            code: "string — the JavaScript source code",
+                            status: "'active' | 'inactive'",
+                            testPayload: "object | null — sample payload for testing",
+                        },
+                        trigger_types: {
+                            "on-demand": {
+                                description: "Manually invoked via API call (invoke_trigger). Use for user-initiated actions.",
+                                invocation: "Call invoke_trigger with the trigger ID and optional payload",
+                                example_use_cases: [
+                                    "Send a notification",
+                                    "Run a data transformation",
+                                    "Generate a report",
+                                ],
+                            },
+                            "event-driven": {
+                                description: "Automatically fires when a data event occurs (record created, updated, deleted).",
+                                event_types: [
+                                    "record.created — fires after a new record is created",
+                                    "record.updated — fires after a record is modified",
+                                    "record.deleted — fires after a record is deleted",
+                                ],
+                                config: "Specify the collection (structureId) and event type to listen for",
+                            },
+                            scheduled: {
+                                description: "Runs on a cron schedule (e.g., every hour, daily at midnight).",
+                                config: "Uses standard cron expression syntax (e.g., '0 * * * *' for hourly)",
+                            },
+                            webhook: {
+                                description: "Triggered by an external HTTP POST to a generated webhook URL.",
+                                config: "Each webhook trigger gets a unique URL to share with external services",
+                            },
+                        },
+                        trigger_shape: {
+                            id: "UUID",
+                            name: "string",
+                            functionId: "UUID — the compute function to execute",
+                            executionType: "'on-demand' | 'event-driven' | 'scheduled' | 'webhook'",
+                            status: "'active' | 'paused'",
+                            config: "object — type-specific configuration (cron, event filters, etc.)",
+                        },
+                        function_crud: {
+                            get_function: {
+                                description: "Get a compute function by ID, including its code",
+                                required_params: ["functionId"],
+                            },
+                            create_function: {
+                                description: "Create a new compute function",
+                                required_params: ["name", "slug", "code"],
+                                optional_params: ["description", "timeout"],
+                                code_format: "module.exports = async (ctx) => { /* your code */ return result; }",
+                            },
+                            update_function: {
+                                description: "Update an existing function. Partial updates supported.",
+                                required_params: ["functionId"],
+                                optional_params: ["name", "description", "code", "timeout"],
+                            },
+                            delete_function: {
+                                description: "Delete a compute function by ID",
+                                required_params: ["functionId"],
+                            },
+                            test_function: {
+                                description: "Test execute code without saving. Returns output, duration, and logs.",
+                                required_params: ["code"],
+                                optional_params: ["input"],
+                            },
+                        },
+                        trigger_crud: {
+                            get_trigger: {
+                                description: "Get any trigger by ID (all execution types)",
+                                required_params: ["triggerId"],
+                            },
+                            create_trigger: {
+                                description: "Create a new function trigger",
+                                required_params: ["name", "functionId", "executionType"],
+                                optional_params: ["description", "triggerMetadata", "enabled"],
+                                triggerMetadata_examples: {
+                                    "event-driven": { event: "record.created", recordSlug: "orders" },
+                                    scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                                },
+                            },
+                            update_trigger: {
+                                description: "Update an existing trigger. Partial updates supported.",
+                                required_params: ["triggerId"],
+                                optional_params: ["name", "description", "enabled", "triggerMetadata"],
+                            },
+                            delete_trigger: {
+                                description: "Delete a trigger by ID",
+                                required_params: ["triggerId"],
+                            },
+                            pause_trigger: {
+                                description: "Pause a trigger to temporarily disable it",
+                                required_params: ["triggerId"],
+                            },
+                            resume_trigger: {
+                                description: "Resume a paused trigger",
+                                required_params: ["triggerId"],
+                            },
+                        },
+                        tips: [
+                            "Use list_functions to see all available functions",
+                            "Use list_triggers to see how functions are wired to execution events",
+                            "Only on-demand triggers can be invoked via invoke_trigger — other types fire automatically",
+                            "Functions receive the trigger payload in their execution context",
+                            "Use pause_trigger/resume_trigger to temporarily disable triggers without deleting them",
+                            "Use test_function to validate code before creating or updating a function",
+                            "Use create_function + create_trigger together to set up a complete compute pipeline",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Smart Queries ──────────────────────────────────────────────────
+    server.tool("describe_smart_queries", "Get the schema reference for Centrali smart queries. Explains parameterized queries, variable substitution, and execution.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Smart Queries",
+                        description: "Smart queries are reusable, parameterized queries defined in the Centrali console. They allow complex filtering and aggregation logic to be saved and executed with variable substitution.",
+                        smart_query_shape: {
+                            id: "UUID",
+                            name: "string — display name",
+                            structureSlug: "string — the collection this query targets",
+                            description: "string | null",
+                            query: "object — the query definition with filters, sort, fields, and aggregations",
+                            variables: "object[] — declared variables with name, type, and default values",
+                        },
+                        variable_syntax: {
+                            description: "Variables use double-brace syntax: {{variableName}}. When executing, pass a variables object to substitute values.",
+                            example: {
+                                query_filter: {
+                                    "data.status": "{{status}}",
+                                    "data.amount[gte]": "{{minAmount}}",
+                                },
+                                execution_variables: {
+                                    status: "active",
+                                    minAmount: "1000",
+                                },
+                            },
+                            note: "Variable values are always passed as strings — the query engine handles type coercion",
+                        },
+                        crud_tools: {
+                            get_smart_query: {
+                                description: "Get a smart query by ID, including its full definition",
+                                required_params: ["recordSlug", "queryId"],
+                            },
+                            create_smart_query: {
+                                description: "Create a new smart query for a collection",
+                                required_params: ["recordSlug", "name", "queryDefinition"],
+                                optional_params: ["description"],
+                                queryDefinition_example: {
+                                    where: { status: { "$eq": "active" } },
+                                    sort: [{ field: "createdAt", direction: "desc" }],
+                                    limit: 100,
+                                },
+                            },
+                            update_smart_query: {
+                                description: "Update an existing smart query. Partial updates supported.",
+                                required_params: ["recordSlug", "queryId"],
+                                optional_params: ["name", "description", "queryDefinition"],
+                            },
+                            delete_smart_query: {
+                                description: "Delete a smart query by ID",
+                                required_params: ["recordSlug", "queryId"],
+                            },
+                            test_smart_query: {
+                                description: "Test execute a query definition without saving it. Preview results before creating.",
+                                required_params: ["recordSlug", "queryDefinition"],
+                                optional_params: ["variables"],
+                            },
+                        },
+                        tips: [
+                            "Use list_smart_queries to discover available queries (optionally filter by collection slug)",
+                            "Smart queries return the same result shape as query_records",
+                            "Variables are defined when creating the query in the console — check the query's variables array to see what's expected",
+                            "Prefer smart queries over ad-hoc query_records filters for complex/reusable logic",
+                            "Use test_smart_query to validate query syntax and preview results before saving",
+                            "Use create_smart_query to save reusable queries that can be executed with execute_smart_query",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Orchestrations ─────────────────────────────────────────────────
+    server.tool("describe_orchestrations", "Get the schema reference for Centrali orchestrations. Explains multi-step workflows, runs, steps, and execution model.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        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",
+                            name: "string",
+                            description: "string | null",
+                            status: "'draft' | 'active' | 'paused'",
+                            steps: "OrchestrationStep[] — ordered array of step definitions",
+                        },
+                        step_shape: {
+                            id: "UUID",
+                            name: "string — step display name",
+                            functionId: "UUID — the compute function to execute",
+                            order: "number — execution order (0-indexed)",
+                            inputMapping: "object | null — maps data from previous step outputs or orchestration input to this step's input",
+                            retryConfig: "object | null — { maxRetries, delayMs } for automatic retry on failure",
+                            timeoutMs: "number | null — step execution timeout",
+                        },
+                        run_shape: {
+                            id: "UUID",
+                            orchestrationId: "UUID",
+                            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",
+                            startedAt: "ISO 8601 datetime",
+                            completedAt: "ISO 8601 datetime | null",
+                            correlationId: "string | null — optional tracing ID",
+                        },
+                        run_step_shape: {
+                            stepId: "UUID",
+                            status: "'pending' | 'running' | 'completed' | 'failed' | 'skipped'",
+                            input: "object — input passed to this step",
+                            output: "object | null — output returned by this step",
+                            error: "string | null — error message if failed",
+                            startedAt: "ISO 8601 datetime | null",
+                            completedAt: "ISO 8601 datetime | null",
+                        },
+                        crud_tools: {
+                            create_orchestration: {
+                                description: "Create a new orchestration workflow",
+                                required_params: ["slug", "name", "trigger", "steps"],
+                                optional_params: ["description"],
+                                trigger_example: { type: "on-demand" },
+                                step_example: {
+                                    id: "validate",
+                                    type: "compute",
+                                    functionId: "func-uuid",
+                                    onSuccess: { nextStepId: "process" },
+                                },
+                            },
+                            update_orchestration: {
+                                description: "Update an existing orchestration. Partial updates supported.",
+                                required_params: ["orchestrationId"],
+                                optional_params: ["name", "description", "status", "trigger", "steps"],
+                            },
+                            delete_orchestration: {
+                                description: "Delete an orchestration and all its runs",
+                                required_params: ["orchestrationId"],
+                            },
+                            activate_orchestration: {
+                                description: "Set orchestration status to 'active' so it can be triggered",
+                                required_params: ["orchestrationId"],
+                            },
+                            pause_orchestration: {
+                                description: "Set orchestration status to 'paused' to prevent triggering",
+                                required_params: ["orchestrationId"],
+                            },
+                        },
+                        tips: [
+                            "Use list_orchestrations to see available workflows",
+                            "Use create_orchestration to define new multi-step workflows",
+                            "Use activate_orchestration to enable a draft orchestration for triggering",
+                            "Use pause_orchestration to temporarily disable an orchestration without deleting it",
+                            "Use trigger_orchestration with an input object to start a run",
+                            "Use get_orchestration_run with includeSteps=true to see step-by-step execution details",
+                            "Orchestrations must be 'active' to be triggered — draft orchestrations cannot run",
+                            "Use correlationId when triggering to trace runs across systems",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Insights ───────────────────────────────────────────────────────
+    server.tool("describe_insights", "Get the schema reference for Centrali anomaly insights. Explains anomaly detection, severity levels, and the acknowledge/dismiss workflow.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Anomaly Insights",
+                        description: "Centrali's AI-powered anomaly detection scans your data for unusual patterns. Insights are generated automatically or on-demand via trigger_anomaly_analysis.",
+                        insight_shape: {
+                            id: "UUID",
+                            structureSlug: "string — the collection where the anomaly was detected",
+                            type: "string — anomaly type (e.g., 'spike', 'drop', 'outlier', 'pattern_break')",
+                            severity: "'critical' | 'high' | 'medium' | 'low'",
+                            status: "'active' | 'acknowledged' | 'dismissed'",
+                            title: "string — human-readable summary",
+                            description: "string — detailed explanation of the anomaly",
+                            affectedRecords: "string[] — IDs of affected records",
+                            detectedAt: "ISO 8601 datetime",
+                            metadata: "object — additional context (field names, thresholds, values)",
+                        },
+                        lifecycle: {
+                            active: "Newly detected, needs review",
+                            acknowledged: "Reviewed and marked as handled (via acknowledge_insight). Remains visible for tracking.",
+                            dismissed: "Marked as false positive or not relevant (via dismiss_insight). Hidden from default views.",
+                        },
+                        summary_shape: {
+                            totalActive: "number",
+                            totalAcknowledged: "number",
+                            totalDismissed: "number",
+                            bySeverity: "{ critical: n, high: n, medium: n, low: n }",
+                        },
+                        tips: [
+                            "Use trigger_anomaly_analysis to scan a specific collection on-demand",
+                            "Use get_insights_summary for a quick overview before diving into individual insights",
+                            "Filter by severity='critical' to focus on the most important issues first",
+                            "Acknowledged insights are still visible — use dismiss for false positives",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Validation ─────────────────────────────────────────────────────
+    server.tool("describe_validation", "Get the schema reference for Centrali data quality validation. Explains scan types, suggestion lifecycle, and how to review/apply fixes.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Data Validation",
+                        description: "AI-powered data quality scanning that detects issues in your records and suggests corrections. Scans run asynchronously and produce suggestions that can be accepted (applied) or rejected.",
+                        scan_types: {
+                            typo: "Detects spelling errors and typos in text fields (e.g., 'Chciago' → 'Chicago')",
+                            format: "Detects format inconsistencies (e.g., mixed date formats, inconsistent phone number formatting)",
+                            duplicate: "Detects potential duplicate records based on field similarity",
+                            semantic: "Detects semantically incorrect values (e.g., a country field containing a city name)",
+                            type: "Detects type mismatches (e.g., a number stored as a string, invalid email format)",
+                        },
+                        suggestion_shape: {
+                            id: "UUID",
+                            structureSlug: "string — the collection containing the issue",
+                            recordId: "UUID — the specific record with the issue",
+                            field: "string — the field name where the issue was found",
+                            issueType: "'typo' | 'format' | 'duplicate' | 'semantic' | 'type'",
+                            severity: "'error' | 'warning' | 'info'",
+                            currentValue: "any — the current (problematic) value",
+                            suggestedValue: "any — the proposed correction",
+                            confidence: "number (0-1) — AI confidence in the suggestion. 0.9+ is high confidence.",
+                            explanation: "string — why this was flagged and what the fix does",
+                            status: "'pending' | 'accepted' | 'rejected' | 'auto-applied'",
+                        },
+                        lifecycle: {
+                            pending: "Newly generated, needs human review",
+                            accepted: "Accepted and applied to the record (via accept_validation_suggestion)",
+                            rejected: "Rejected as incorrect or not applicable (via reject_validation_suggestion)",
+                            "auto-applied": "Automatically applied for high-confidence suggestions (if auto-apply is enabled)",
+                        },
+                        tips: [
+                            "Use trigger_validation_scan to start a scan — you can target specific issue types",
+                            "Use list_validation_suggestions with minConfidence=0.9 to focus on high-confidence fixes",
+                            "Use get_validation_summary for a quick overview of data quality",
+                            "Accept applies the fix immediately — the record's field value is updated",
+                            "Scans are async — there may be a short delay before suggestions appear after triggering",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Pages ──────────────────────────────────────────────────────────
+    server.tool("describe_pages", "Get the schema reference for Centrali pages. Explains page types, the definition structure, sections, blocks, and the publish lifecycle.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Pages",
+                        description: "Pages are pre-built UI views that surface data from collections. Each page has a type, a versioned definition (describing layout and data binding), and a publish lifecycle.",
+                        page_types: {
+                            list: {
+                                description: "Data table view — shows multiple records with columns, sorting, filtering, and pagination.",
+                                typical_sections: ["content"],
+                                typical_blocks: ["data-table"],
+                                validation_requirement: "List pages must have at least one block with configured columns (in presentation.columns or block.columns) to pass publishing validation.",
+                                use_when: "You need to browse, search, or manage a set of records",
+                            },
+                            detail: {
+                                description: "Single-record view — shows all fields of one record with optional related data and actions.",
+                                typical_sections: ["hero", "content", "supporting"],
+                                typical_blocks: [
+                                    "detail-fields",
+                                    "field-display",
+                                    "related-list",
+                                    "activity-feed",
+                                    "markdown",
+                                ],
+                                use_when: "You need to display a single record's full details (e.g., customer profile)",
+                            },
+                            form: {
+                                description: "Data entry form — lets users create or update records with validation and submission actions.",
+                                typical_sections: ["content", "actions"],
+                                typical_blocks: [
+                                    "form",
+                                    "field-group",
+                                    "text-input",
+                                    "number-input",
+                                    "select",
+                                    "checkbox",
+                                    "date-picker",
+                                    "textarea",
+                                    "file-upload",
+                                ],
+                                validation_requirement: "Form pages must have at least one field block (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group, or field-display) to pass publishing validation.",
+                                use_when: "You need users to input or edit data",
+                            },
+                            dashboard: {
+                                description: "Metrics and analytics view — shows KPIs, charts, tables, and activity feeds for data overview.",
+                                typical_sections: ["metrics", "content", "supporting"],
+                                typical_blocks: [
+                                    "stat-group",
+                                    "metric-card",
+                                    "chart",
+                                    "data-table",
+                                    "activity-feed",
+                                    "progress-indicator",
+                                    "kanban",
+                                    "calendar",
+                                    "filter-bar",
+                                ],
+                                use_when: "You need an overview with KPIs, trends, and visual summaries",
+                            },
+                        },
+                        describeDefinitionWith: "describe_page_definition",
+                        describeBlocksWith: "describe_page_blocks",
+                        describeActionsWith: "describe_page_actions",
+                        lifecycle: {
+                            "1_create": "create_page — creates the page record with name, slug, and type",
+                            "2_draft": "save_page_draft — saves or updates the page definition (layout, blocks, data bindings)",
+                            "3_validate": "validate_page — checks the draft for errors before publishing",
+                            "4_publish": "publish_page — makes the page accessible at its runtime URL",
+                            "5_iterate": "Repeat steps 2-4 to update. Each publish creates a new version.",
+                            unpublish: "unpublish_page — removes the page from its runtime URL (keeps the definition)",
+                        },
+                        access_modes: {
+                            public: "Anyone can view — no authentication required",
+                            authenticated: "Only logged-in users can view — redirects to login if not authenticated",
+                            "role-gated": "Only users with specific roles can view — returns 403 for unauthorized users",
+                        },
+                        describeNavigationWith: "describe_navigation",
+                        tips: [
+                            "Call describe_page_definition to learn the full definition schema before using save_page_draft",
+                            "Call describe_page_blocks to see all available block types and their configs",
+                            "Call describe_navigation to learn the navigation config schema before using set_navigation",
+                            "Use generate_starter_pages to auto-generate page proposals from your collections",
+                            "Always validate_page before publish_page — publishing will reject if there are errors",
+                            "Set access policy with set_page_access_policy before publishing if you need auth",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Page Definition Schema ─────────────────────────────────────────
+    server.tool("describe_page_definition", "Get the full schema for a page definition — the JSON structure passed to save_page_draft. Explains sections, blocks, data sources, and how they compose together.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Page Definition",
+                        description: "A page definition is a JSON object that describes the page layout. It contains sections, and each section contains blocks. Blocks are the actual UI components (tables, charts, forms, etc.).",
+                        definition_shape: {
+                            sections: "PageSection[] — ordered array of sections that make up the page",
+                            theme: {
+                                inherit: "boolean — if true, inherits the workspace theme. Usually set to true.",
+                            },
+                        },
+                        section_shape: {
+                            id: "string — unique ID for the section (use a UUID or descriptive slug like 'metrics-strip')",
+                            kind: "'content' | 'metrics' | 'exceptions' | 'actions' | 'hero' | 'supporting'",
+                            title: "string — section heading displayed to users",
+                            layout: "'single-column' | 'two-column' | 'metric-strip' | 'stack'",
+                            blocks: "PageBlock[] — array of blocks in this section",
+                        },
+                        section_kinds: {
+                            hero: "Top of page — typically a title/summary or key metric. Use for detail pages.",
+                            metrics: "KPI strip — typically metric-card or stat-group blocks in metric-strip layout",
+                            content: "Main content area — data tables, charts, forms. The workhorse section.",
+                            supporting: "Secondary content — related data, activity feeds, supplementary info",
+                            actions: "Action buttons or form submission areas. Often at the bottom of form pages.",
+                            exceptions: "Error/warning display area — for anomaly or validation results",
+                        },
+                        section_layouts: {
+                            "single-column": "Full-width blocks stacked vertically",
+                            "two-column": "Blocks arranged in two columns side by side",
+                            "metric-strip": "Horizontal strip of small blocks (ideal for stat-group, metric-card)",
+                            stack: "Compact vertical stack",
+                        },
+                        block_shape: {
+                            id: "string — unique ID for the block (use a UUID)",
+                            blockType: "string — the type of UI component (see describe_page_blocks for all types)",
+                            dataSource: "DataSource | null — where this block gets its data (see below)",
+                            presentation: "BlockPresentation | null — display options (density, columns, chart type, emphasis rules)",
+                            actions: "BlockAction[] | null — interactive actions (buttons, row clicks, form submissions). See describe_page_actions.",
+                            narrative: "BlockNarrative | null — contextual copy (primary question, framing text, comparison)",
+                            filterableColumns: "string[] | null — which columns users can filter on (for data-table blocks)",
+                        },
+                        data_source_shape: {
+                            type: "'structure' | 'query'",
+                            ref: "string — the collection ID (UUID) for 'structure' type, or smart query ID for 'query' type",
+                            mode: "'list' | 'single' | 'aggregate' — how to fetch data. 'list' returns multiple records, 'single' returns one, 'aggregate' returns computed values.",
+                            config: {
+                                fields: "string[] | null — specific fields to fetch (null = all fields)",
+                                fieldOrder: "string[] | null — display order for fields",
+                                filters: "object | null — same filter syntax as query_records (data.field[operator]: value)",
+                                sort: "SortConfig[] | null — array of { field, direction: 'asc' | 'desc' }",
+                                limit: "number | null — max records to fetch",
+                                page: "number | null — for pagination",
+                                pageSize: "number | null — records per page",
+                            },
+                            aggregation: {
+                                description: "Only used when mode is 'aggregate'. Defines computations over the data.",
+                                operations: "Record<string, { count?: '*', sum?: 'fieldName', avg?: 'fieldName', min?: 'fieldName', max?: 'fieldName' }>",
+                                groupBy: "string[] | null — fields to group by",
+                            },
+                        },
+                        presentation_shape: {
+                            density: "'compact' | 'comfortable' | 'spacious' — controls spacing/padding",
+                            columns: "string[] — which columns to show (for table blocks)",
+                            chartType: "'bar' | 'line' | 'pie' — for chart blocks",
+                            emphasisRules: "EmphasisRule[] — conditional formatting rules: { field, operator, threshold, severity }",
+                        },
+                        narrative_shape: {
+                            primaryQuestion: "string — the business question this block answers (e.g., 'How are sales trending?')",
+                            framingCopy: "string — contextual description shown above/below the block",
+                            comparison: "{ type: 'previous-period' | 'target' | 'baseline', value: number } — for metrics comparison",
+                            nextActionLabel: "string — label for a suggested next action (e.g., 'View all orders')",
+                        },
+                        example_list_page_definition: {
+                            sections: [
+                                {
+                                    id: "main-content",
+                                    kind: "content",
+                                    title: "All Customers",
+                                    layout: "single-column",
+                                    blocks: [
+                                        {
+                                            id: "customer-table",
+                                            blockType: "data-table",
+                                            dataSource: {
+                                                type: "structure",
+                                                ref: "<collection-uuid>",
+                                                mode: "list",
+                                                config: {
+                                                    fields: [
+                                                        "name",
+                                                        "email",
+                                                        "status",
+                                                        "createdAt",
+                                                    ],
+                                                    sort: [{ field: "createdAt", direction: "desc" }],
+                                                    pageSize: 25,
+                                                },
+                                            },
+                                            presentation: { density: "comfortable" },
+                                            filterableColumns: ["status", "name"],
+                                        },
+                                    ],
+                                },
+                            ],
+                            theme: { inherit: true },
+                        },
+                        example_dashboard_definition: {
+                            sections: [
+                                {
+                                    id: "kpi-strip",
+                                    kind: "metrics",
+                                    title: "Key Metrics",
+                                    layout: "metric-strip",
+                                    blocks: [
+                                        {
+                                            id: "total-orders",
+                                            blockType: "metric-card",
+                                            dataSource: {
+                                                type: "structure",
+                                                ref: "<orders-collection-uuid>",
+                                                mode: "aggregate",
+                                                config: {},
+                                                aggregation: {
+                                                    operations: { totalOrders: { count: "*" } },
+                                                },
+                                            },
+                                            narrative: {
+                                                primaryQuestion: "How many orders do we have?",
+                                            },
+                                        },
+                                        {
+                                            id: "total-revenue",
+                                            blockType: "metric-card",
+                                            dataSource: {
+                                                type: "structure",
+                                                ref: "<orders-collection-uuid>",
+                                                mode: "aggregate",
+                                                config: {},
+                                                aggregation: {
+                                                    operations: {
+                                                        revenue: { sum: "totalAmount" },
+                                                    },
+                                                },
+                                            },
+                                            narrative: {
+                                                primaryQuestion: "What is our total revenue?",
+                                            },
+                                        },
+                                    ],
+                                },
+                                {
+                                    id: "charts",
+                                    kind: "content",
+                                    title: "Trends",
+                                    layout: "two-column",
+                                    blocks: [
+                                        {
+                                            id: "orders-by-status",
+                                            blockType: "chart",
+                                            dataSource: {
+                                                type: "structure",
+                                                ref: "<orders-collection-uuid>",
+                                                mode: "aggregate",
+                                                config: {},
+                                                aggregation: {
+                                                    operations: { count: { count: "*" } },
+                                                    groupBy: ["status"],
+                                                },
+                                            },
+                                            presentation: { chartType: "pie" },
+                                        },
+                                    ],
+                                },
+                            ],
+                            theme: { inherit: true },
+                        },
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Page Block Types ───────────────────────────────────────────────
+    server.tool("describe_page_blocks", "Get all available page block types and their configuration shapes. Each block type has specific data source requirements and presentation options.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Page Block Types",
+                        description: "Blocks are the UI components inside page sections. Each blockType has its own configuration requirements.",
+                        block_types: {
+                            "data-table": {
+                                description: "Tabular data display with columns, sorting, filtering, and pagination. The primary block for list pages.",
+                                dataSource: "Required — type: 'structure', mode: 'list'",
+                                config: {
+                                    columns: "{ field: string, label: string, sortable?: boolean }[] — column definitions",
+                                    defaultSort: "{ field: string, direction: 'asc' | 'desc' } — initial sort",
+                                    pageSize: "number — rows per page (default: 25)",
+                                    rowClickAction: "BlockAction | null — action when a row is clicked (typically navigate-to-page)",
+                                },
+                                presentation: "density, columns, emphasisRules",
+                                filterableColumns: "string[] — columns users can filter on",
+                            },
+                            "metric-card": {
+                                description: "Single KPI metric display — shows a number with label, optional trend, and thresholds.",
+                                dataSource: "Required — type: 'structure', mode: 'aggregate' with a single aggregation",
+                                config: {
+                                    aggregation: "'count' | 'sum' | 'average' | 'min' | 'max'",
+                                    valueField: "string — field to aggregate (not needed for 'count')",
+                                    label: "string — display label for the metric",
+                                    format: "'number' | 'currency' | 'percentage' — value formatting",
+                                    trend: "{ enabled: boolean, comparison: 'previous-period' }",
+                                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] } — color-code the value",
+                                },
+                            },
+                            "stat-group": {
+                                description: "Group of 2-5 related metrics displayed side by side. More compact than individual metric-cards.",
+                                dataSource: "Not set at block level — each item has its own dataSource",
+                                config: {
+                                    items: "StatGroupItem[] — array of { id, label, dataSource, aggregation, valueField, format, trend }",
+                                },
+                            },
+                            chart: {
+                                description: "Data visualization — bar, line, or pie chart.",
+                                dataSource: "Required — type: 'structure', mode: 'aggregate' with groupBy",
+                                config: {
+                                    chartType: "'bar' | 'line' | 'pie'",
+                                    categoryField: "string — field for x-axis / categories",
+                                    valueField: "string — field for y-axis / values",
+                                    groupByField: "string | null — optional field for series grouping",
+                                    colors: "string[] | null — custom color palette",
+                                    showLegend: "boolean (default: true)",
+                                },
+                                presentation: "chartType",
+                            },
+                            form: {
+                                description: "Data entry form with typed fields, validation, and submission. Used for creating or editing records.",
+                                dataSource: "Optional — if set with mode: 'single', pre-populates form for editing",
+                                config: {
+                                    fields: "FormFieldDef[] — array of field definitions (see below)",
+                                },
+                                form_field_shape: {
+                                    key: "string — maps to the record's data field name",
+                                    label: "string — display label",
+                                    type: "'text' | 'number' | 'email' | 'date' | 'boolean' | 'select' | 'textarea'",
+                                    required: "boolean (default: false)",
+                                    placeholder: "string | null",
+                                    optionSource: "For 'select' type: { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-id', labelField?, valueField? }",
+                                },
+                            },
+                            "detail-fields": {
+                                description: "Read-only display of a single record's fields. Used for detail pages.",
+                                dataSource: "Required — type: 'structure', mode: 'single'",
+                            },
+                            "activity-feed": {
+                                description: "Chronological list of recent items/events, showing title, description, and timestamp.",
+                                dataSource: "Required — type: 'structure', mode: 'list'",
+                                config: {
+                                    titleField: "string — field to use as item title",
+                                    descriptionField: "string | null — field for item description",
+                                    timestampField: "string — field for item timestamp",
+                                    iconField: "string | null — field for item icon",
+                                    maxItems: "number (default: 10)",
+                                },
+                            },
+                            "progress-indicator": {
+                                description: "Visual progress display — bar, ring, or badge. Shows completion toward a target.",
+                                dataSource: "Optional — can use static value or aggregate from data",
+                                config: {
+                                    mode: "'bar' | 'ring' | 'badge'",
+                                    label: "string",
+                                    value: "number | null — static value (if no dataSource)",
+                                    valueField: "string | null — field to aggregate (if using dataSource)",
+                                    aggregation: "'count' | 'sum' | 'average' | 'percentage'",
+                                    target: "number — the 100% target value",
+                                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] }",
+                                },
+                            },
+                            kanban: {
+                                description: "Kanban board — drag-and-drop cards grouped by a status/category field.",
+                                dataSource: "Required — type: 'structure', mode: 'list'",
+                                config: {
+                                    groupByField: "string — field to group cards by (e.g., 'status')",
+                                    columnOrder: "string[] | null — explicit column order (e.g., ['todo', 'in-progress', 'done'])",
+                                    cardTitleField: "string — field for card title",
+                                    cardSubtitleField: "string | null — field for card subtitle",
+                                    cardBadgeField: "string | null — field for a badge/tag on the card",
+                                },
+                            },
+                            calendar: {
+                                description: "Calendar view — displays records as events on a month/week/day calendar.",
+                                dataSource: "Required — type: 'structure', mode: 'list'",
+                                config: {
+                                    dateField: "string — field for event start date",
+                                    endDateField: "string | null — field for event end date (for multi-day events)",
+                                    titleField: "string — field for event title",
+                                    colorField: "string | null — field to determine event color",
+                                    defaultView: "'month' | 'week' | 'day' (default: 'month')",
+                                    eventClickAction: "BlockAction | null — action when an event is clicked",
+                                },
+                            },
+                            "filter-bar": {
+                                description: "Global filter bar for dashboards — provides date range pickers and dropdown filters that control other blocks on the page.",
+                                dataSource: "Not required",
+                                config: {
+                                    dateField: "string | null — field to filter by date range",
+                                    datePresets: "('today' | '7d' | '30d' | '90d' | 'custom')[] — available date range presets",
+                                    dropdownFilters: "{ field: string, label: string }[] — dropdown filter options",
+                                },
+                            },
+                            "related-list": {
+                                description: "Displays related records from another collection. Similar to data-table but used in detail pages to show linked data (e.g., orders belonging to a customer).",
+                                dataSource: "Required — type: 'structure', mode: 'list' (with filters to scope to the parent record)",
+                                allowed_actions: ["navigate-to-page", "invoke-trigger"],
+                                default_activation: "row-click",
+                                param_source: "row",
+                            },
+                            "field-display": {
+                                description: "Read-only display of a single field value with label. Used in detail pages to show individual fields with formatting.",
+                                dataSource: "Required — type: 'structure', mode: 'single'",
+                                allowed_actions: ["invoke-trigger", "navigate-to-page"],
+                                default_activation: "button",
+                                param_source: "record",
+                            },
+                            "field-group": {
+                                description: "Group of editable form fields. Used in form pages for structured data entry with multiple fields in a logical group.",
+                                dataSource: "Optional — if set with mode: 'single', pre-populates for editing",
+                                allowed_actions: [
+                                    "create-record",
+                                    "update-record",
+                                    "invoke-trigger",
+                                ],
+                                default_activation: "form-submit",
+                                param_source: "form",
+                            },
+                            "text-input": {
+                                description: "Single-line text input field for form pages.",
+                                dataSource: "Not required (value comes from user input)",
+                                category: "field-block",
+                            },
+                            "number-input": {
+                                description: "Numeric input field for form pages. Supports min/max constraints.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            select: {
+                                description: "Dropdown select input for form pages. Options can be static or dynamically loaded from a collection.",
+                                dataSource: "Not required (static options) or optional (dynamic options from collection)",
+                                category: "field-block",
+                            },
+                            checkbox: {
+                                description: "Boolean checkbox input for form pages.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            "date-picker": {
+                                description: "Date/datetime picker input for form pages.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            textarea: {
+                                description: "Multi-line text input for form pages. Use for long text, descriptions, notes.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            "file-upload": {
+                                description: "File upload input for form pages. Stores files in blob storage.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            field: {
+                                description: "Generic field block — base type for custom field rendering in form pages.",
+                                dataSource: "Not required",
+                                category: "field-block",
+                            },
+                            markdown: {
+                                description: "Static markdown content block. Renders markdown text on the page. Must have non-empty content to pass publishing validation.",
+                                dataSource: "Not required",
+                                requires: "content property (string) — the markdown text",
+                                category: "content-block",
+                            },
+                            "static-html": {
+                                description: "Static HTML content block. Renders raw HTML on the page. Must have non-empty content to pass publishing validation.",
+                                dataSource: "Not required",
+                                requires: "content property (string) — the HTML markup",
+                                category: "content-block",
+                            },
+                        },
+                        block_categories: {
+                            "data-block": "Blocks that display data from collections (data-table, chart, metric-card, stat-group, detail-fields, related-list, field-display, activity-feed, kanban, calendar, progress-indicator)",
+                            "field-block": "Input blocks for form pages (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group). Form pages must have at least one field block.",
+                            "content-block": "Static content blocks (markdown, static-html). Must have non-empty 'content' property.",
+                            "layout-block": "Blocks that control page-level behavior (filter-bar)",
+                        },
+                        action_mappings: {
+                            description: "Not all action types are valid on all block types. The publish validator warns when an action type is not recommended for a block type.",
+                            per_block_type: {
+                                "data-table": {
+                                    allowed_actions: ["navigate-to-page", "invoke-trigger"],
+                                    default_activation: "row-click",
+                                    param_source: "row",
+                                },
+                                "related-list": {
+                                    allowed_actions: ["navigate-to-page", "invoke-trigger"],
+                                    default_activation: "row-click",
+                                    param_source: "row",
+                                },
+                                "field-display": {
+                                    allowed_actions: ["invoke-trigger", "navigate-to-page"],
+                                    default_activation: "button",
+                                    param_source: "record",
+                                },
+                                "field-group": {
+                                    allowed_actions: [
+                                        "create-record",
+                                        "update-record",
+                                        "invoke-trigger",
+                                    ],
+                                    default_activation: "form-submit",
+                                    param_source: "form",
+                                },
+                                actions: {
+                                    allowed_actions: [
+                                        "invoke-trigger",
+                                        "navigate-to-page",
+                                        "start-orchestration",
+                                        "enqueue-job",
+                                    ],
+                                    default_activation: "button",
+                                    param_source: "none",
+                                },
+                            },
+                        },
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Page Actions ───────────────────────────────────────────────────
+    server.tool("describe_page_actions", "Get all available page action types and their configuration shapes. Actions define interactive behaviors on blocks (button clicks, row clicks, form submissions).", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Page Actions",
+                        description: "Actions define what happens when a user interacts with a block — clicking a row, pressing a button, or submitting a form.",
+                        action_shape: {
+                            id: "string — unique ID for the action (use a UUID)",
+                            type: "ActionType — what the action does (see action_types below)",
+                            label: "string — button/link text (e.g., 'View Details', 'Create Order')",
+                            targetRef: "string — reference to the target resource (page slug, structure ID, orchestration ID, etc.)",
+                            config: "object | null — action-type-specific configuration",
+                            confirmationRequired: "boolean — if true, shows a confirmation dialog before executing",
+                            activation: "'row-click' | 'button' | 'form-submit' — how the action is triggered",
+                            paramConfig: {
+                                source: "'row' | 'record' | 'form' | 'none' — where to get parameters",
+                                mode: "'all' | 'selected' — pass all fields or only selected ones",
+                                selectedFields: "string[] | null — specific fields to pass (when mode is 'selected')",
+                            },
+                            presentation: {
+                                display: "'button' | 'icon' | 'icon-button'",
+                                icon: "string | null — icon name",
+                                color: "'primary' | 'secondary' | 'destructive' | 'neutral'",
+                            },
+                            postSubmit: {
+                                behavior: "'message' | 'navigate'",
+                                message: "string | null — success message to show (when behavior is 'message')",
+                                targetPageSlug: "string | null — page to navigate to (when behavior is 'navigate')",
+                            },
+                            executionMode: "'fire-and-forget' | 'fire-and-poll' — whether to wait for completion",
+                        },
+                        action_types: {
+                            "navigate-to-page": {
+                                description: "Navigate to another page. Use for detail-view links and list-to-detail navigation.",
+                                targetRef: "Page slug to navigate to",
+                                typical_activation: "row-click",
+                                paramConfig: "Use source: 'row', mode: 'selected', selectedFields: ['id'] to pass the record ID to the detail page",
+                                example: {
+                                    id: "view-detail",
+                                    type: "navigate-to-page",
+                                    label: "View Details",
+                                    targetRef: "customer-detail",
+                                    activation: "row-click",
+                                    paramConfig: {
+                                        source: "row",
+                                        mode: "selected",
+                                        selectedFields: ["id"],
+                                    },
+                                },
+                            },
+                            "create-record": {
+                                description: "Create a new record in a collection. Typically used with form blocks.",
+                                targetRef: "Collection ID (UUID) to create the record in",
+                                typical_activation: "form-submit",
+                                paramConfig: "Use source: 'form', mode: 'all'",
+                                postSubmit: "Usually { behavior: 'message', message: 'Record created successfully' } or { behavior: 'navigate', targetPageSlug: 'list-page' }",
+                            },
+                            "update-record": {
+                                description: "Update an existing record. Used with form blocks pre-populated with record data.",
+                                targetRef: "Collection ID (UUID)",
+                                typical_activation: "form-submit",
+                                paramConfig: "Use source: 'form', mode: 'all'",
+                            },
+                            "invoke-trigger": {
+                                description: "Invoke an on-demand compute trigger. Use for server-side actions like sending emails, running calculations, etc.",
+                                targetRef: "Trigger ID (UUID)",
+                                typical_activation: "button",
+                                paramConfig: "Use source: 'row' to pass the current record as payload, or source: 'none' for no payload",
+                                confirmationRequired: "Recommended: true for destructive or costly operations",
+                                executionMode: "'fire-and-forget' for async, 'fire-and-poll' to show loading state",
+                            },
+                            "start-orchestration": {
+                                description: "Start an orchestration workflow run. Use for multi-step processes.",
+                                targetRef: "Orchestration ID (UUID)",
+                                typical_activation: "button",
+                                executionMode: "'fire-and-poll' recommended — orchestrations are long-running",
+                            },
+                            "enqueue-job": {
+                                description: "Enqueue a background job. Use for bulk operations or long-running tasks.",
+                                targetRef: "Job type identifier",
+                                typical_activation: "button",
+                                executionMode: "'fire-and-forget'",
+                            },
+                        },
+                        tips: [
+                            "Every action needs an 'id' — use UUIDs for uniqueness",
+                            "Use 'navigate-to-page' with activation 'row-click' for list-to-detail navigation",
+                            "Form pages typically have one action with activation 'form-submit' and type 'create-record' or 'update-record'",
+                            "Set confirmationRequired: true for destructive actions (delete, bulk update)",
+                            "Use postSubmit to control what happens after a form submission",
+                            "Actions on data-table blocks often use paramConfig with source: 'row' to pass the clicked record's data",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Navigation ─────────────────────────────────────────────────────
+    server.tool("describe_navigation", "Get the full schema for the workspace navigation configuration. Explains how to construct the sidebar/nav shell that wraps published pages — item types, grouping, branding, and limits.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Navigation",
+                        description: "The navigation configuration controls the sidebar/nav shell that wraps published pages. When enabled, all pages in the workspace share a common sidebar with branding, grouped links, and external links. When disabled or deleted, pages render standalone.",
+                        tools: {
+                            get_navigation: "Returns the current config enriched with page metadata (name, slug, isPublished for each page item)",
+                            set_navigation: "Create or update the config. Pass the full config object (not a partial — it replaces the existing config).",
+                            delete_navigation: "Remove the config entirely. Pages revert to standalone rendering.",
+                        },
+                        config_shape: {
+                            enabled: "boolean — master toggle. If false, the nav shell is hidden even if items exist.",
+                            branding: {
+                                logoUrl: "string | undefined — URL to the workspace logo displayed at the top of the sidebar. Must be a valid URL or empty string.",
+                                displayName: "string | undefined — workspace display name shown in the sidebar header. Max 100 characters.",
+                            },
+                            items: "NavEntry[] — ordered array of navigation items (max 50). Each entry is one of three types: 'group', 'page', or 'external-link'.",
+                        },
+                        item_types: {
+                            page: {
+                                description: "Links to a published page in the workspace. The sidebar displays the page's name and slug automatically (resolved from pageId).",
+                                shape: {
+                                    type: "'page' (literal)",
+                                    id: "string (UUID) — unique ID for this nav item",
+                                    pageId: "string (UUID) — the page ID to link to. Must reference an existing page.",
+                                    icon: "string | undefined — icon name (max 50 chars). Optional.",
+                                },
+                                note: "GET response enriches page items with name, slug, and isPublished fields. When setting, you only need type, id, and pageId.",
+                            },
+                            group: {
+                                description: "A collapsible group that contains page items and/or external links. Use to organize nav items by category.",
+                                shape: {
+                                    type: "'group' (literal)",
+                                    id: "string (UUID) — unique ID for this group",
+                                    label: "string — group heading displayed in the sidebar. 1-50 characters.",
+                                    children: "(NavPageItem | NavExternalLink)[] — ordered array of child items (max 20). Cannot contain nested groups.",
+                                },
+                            },
+                            "external-link": {
+                                description: "Links to an external URL. Opens in a new tab. Use for documentation, support links, or other external resources.",
+                                shape: {
+                                    type: "'external-link' (literal)",
+                                    id: "string (UUID) — unique ID for this nav item",
+                                    label: "string — link text displayed in the sidebar. 1-50 characters.",
+                                    url: "string — the external URL. Must be a valid URL.",
+                                    icon: "string | undefined — icon name (max 50 chars). Optional.",
+                                },
+                            },
+                        },
+                        limits: {
+                            max_top_level_items: 50,
+                            max_children_per_group: 20,
+                            max_label_length: 50,
+                            max_display_name_length: 100,
+                            nesting: "Groups cannot be nested — children must be 'page' or 'external-link' items only.",
+                        },
+                        example: {
+                            config: {
+                                enabled: true,
+                                branding: {
+                                    displayName: "Acme Corp",
+                                    logoUrl: "https://acme.com/logo.png",
+                                },
+                                items: [
+                                    {
+                                        type: "page",
+                                        id: "nav-dashboard",
+                                        pageId: "<dashboard-page-uuid>",
+                                        icon: "LayoutDashboard",
+                                    },
+                                    {
+                                        type: "group",
+                                        id: "nav-data",
+                                        label: "Data Management",
+                                        children: [
+                                            {
+                                                type: "page",
+                                                id: "nav-customers",
+                                                pageId: "<customers-page-uuid>",
+                                                icon: "Users",
+                                            },
+                                            {
+                                                type: "page",
+                                                id: "nav-orders",
+                                                pageId: "<orders-page-uuid>",
+                                                icon: "ShoppingCart",
+                                            },
+                                        ],
+                                    },
+                                    {
+                                        type: "external-link",
+                                        id: "nav-docs",
+                                        label: "Documentation",
+                                        url: "https://docs.acme.com",
+                                        icon: "BookOpen",
+                                    },
+                                ],
+                            },
+                        },
+                        tips: [
+                            "Use UUIDs for all 'id' fields — they must be unique across the config",
+                            "Page items only need 'type', 'id', and 'pageId' — name and slug are resolved automatically from the page",
+                            "Groups cannot be nested — keep the hierarchy to one level deep",
+                            "set_navigation replaces the entire config — always send the full config, not a partial update",
+                            "Pages don't need to be published to appear in the nav config, but unpublished pages will show as disabled in the sidebar",
+                            "The showInNavShell field on a page (via update_page) controls whether the page appears in auto-generated nav suggestions",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+}