@xano/developer-mcp 1.0.40 → 1.0.42

package/dist/run_api_docs/index.test.js

@@ -1,127 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { topics, getTopicNames, getTopicDescriptions, handleRunApiDocs, runApiDocsToolDefinition, } from "./index.js";
-describe("run_api_docs/index", () => {
-    describe("topics", () => {
-        it("should have all expected topics", () => {
-            const expectedTopics = [
-                "start",
-                "run",
-                "session",
-                "history",
-                "data",
-                "workflows",
-            ];
-            expect(Object.keys(topics)).toEqual(expectedTopics);
-        });
-        it("should have valid TopicDoc structure for each topic", () => {
-            for (const [key, doc] of Object.entries(topics)) {
-                expect(doc).toHaveProperty("topic");
-                expect(doc).toHaveProperty("title");
-                expect(doc).toHaveProperty("description");
-                expect(typeof doc.topic).toBe("string");
-                expect(typeof doc.title).toBe("string");
-                expect(typeof doc.description).toBe("string");
-                expect(doc.topic).toBe(key);
-            }
-        });
-    });
-    describe("getTopicNames", () => {
-        it("should return all topic names", () => {
-            const names = getTopicNames();
-            expect(names).toEqual(Object.keys(topics));
-        });
-        it("should return an array of strings", () => {
-            const names = getTopicNames();
-            expect(Array.isArray(names)).toBe(true);
-            names.forEach((name) => {
-                expect(typeof name).toBe("string");
-            });
-        });
-    });
-    describe("getTopicDescriptions", () => {
-        it("should return formatted topic descriptions", () => {
-            const descriptions = getTopicDescriptions();
-            expect(typeof descriptions).toBe("string");
-            expect(descriptions).toContain("- start:");
-            expect(descriptions).toContain("- run:");
-            expect(descriptions).toContain("- session:");
-        });
-        it("should include all topics", () => {
-            const descriptions = getTopicDescriptions();
-            for (const key of Object.keys(topics)) {
-                expect(descriptions).toContain(`- ${key}:`);
-            }
-        });
-    });
-    describe("handleRunApiDocs", () => {
-        it("should return error for undefined topic", () => {
-            const result = handleRunApiDocs(undefined);
-            expect(result).toContain('Error: Unknown topic "undefined"');
-            expect(result).toContain("Available topics:");
-        });
-        it("should return error for unknown topic", () => {
-            const result = handleRunApiDocs("nonexistent");
-            expect(result).toContain('Error: Unknown topic "nonexistent"');
-            expect(result).toContain("Available topics:");
-        });
-        it("should return documentation for valid topic", () => {
-            const result = handleRunApiDocs("start");
-            expect(result).not.toContain("Error:");
-        });
-        it("should return run documentation", () => {
-            const result = handleRunApiDocs("run");
-            expect(result).toContain("Run Execution");
-            expect(result).toContain("/run/exec");
-        });
-        it("should return session documentation", () => {
-            const result = handleRunApiDocs("session");
-            expect(result).toContain("Session");
-        });
-        it("should use default detail_level of detailed", () => {
-            const result = handleRunApiDocs("run");
-            expect(result).toContain("**Parameters:**");
-        });
-        it("should respect overview detail_level", () => {
-            const result = handleRunApiDocs("run", "overview");
-            expect(result).toContain("Run Execution");
-        });
-        it("should respect examples detail_level", () => {
-            const result = handleRunApiDocs("run", "examples");
-            expect(result).toContain("**Example:**");
-        });
-        it("should include schemas by default", () => {
-            const result = handleRunApiDocs("run");
-            expect(result).toContain("## Schemas");
-        });
-        it("should exclude schemas when includeSchemas is false", () => {
-            const result = handleRunApiDocs("run", "detailed", false);
-            expect(result).not.toContain("## Schemas");
-        });
-        it("should use Run API base URL", () => {
-            const result = handleRunApiDocs("run");
-            expect(result).toContain("https://app.dev.xano.com/api:run/");
-        });
-    });
-    describe("runApiDocsToolDefinition", () => {
-        it("should have required tool properties", () => {
-            expect(runApiDocsToolDefinition).toHaveProperty("name", "run_api_docs");
-            expect(runApiDocsToolDefinition).toHaveProperty("description");
-            expect(runApiDocsToolDefinition).toHaveProperty("inputSchema");
-        });
-        it("should mention fixed base URL in description", () => {
-            expect(runApiDocsToolDefinition.description).toContain("https://app.dev.xano.com/api:run/");
-        });
-        it("should have valid inputSchema", () => {
-            const schema = runApiDocsToolDefinition.inputSchema;
-            expect(schema.type).toBe("object");
-            expect(schema.properties).toHaveProperty("topic");
-            expect(schema.properties).toHaveProperty("detail_level");
-            expect(schema.properties).toHaveProperty("include_schemas");
-            expect(schema.required).toEqual(["topic"]);
-        });
-        it("should include all topic names in enum", () => {
-            const topicEnum = runApiDocsToolDefinition.inputSchema.properties.topic.enum;
-            expect(topicEnum).toEqual(getTopicNames());
-        });
-    });
-});

package/dist/run_api_docs/topics/data.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const dataDoc: TopicDoc;

package/dist/run_api_docs/topics/data.js

@@ -1,104 +0,0 @@
-export const dataDoc = {
-    topic: "data",
-    title: "Session Data Export",
-    description: `The sink endpoint provides complete data export from session backups. This is the "kitchen sink" - everything from a session's database state in a single JSON response.
-
-## Prerequisites
-- Session must have been hibernated at least once (backup must exist)
-- Hibernation creates a complete snapshot of all tables and data
-
-## Use Cases
-- Export complete session state for analysis
-- Backup data before session termination
-- Transfer data between sessions
-- Debugging and auditing
-
-## Data Included
-- All table schemas
-- All table data/records
-- Complete as single JSON object`,
-    ai_hints: `- Session must be hibernated before sink is available
-- Hibernation happens automatically after project timeout or manually
-- Large datasets may take time to export - be patient
-- Use for complete data snapshots, not real-time queries
-- Data is read-only - cannot modify via sink endpoint
-- Public sessions can export without authentication`,
-    endpoints: [
-        {
-            method: "GET",
-            path: "/session/{session_id}/sink",
-            tool_name: "getSessionSink",
-            description: "Get full backup data from a session as JSON. Returns the complete 'kitchen sink' - all table schemas and data in one response. Session must have been hibernated at least once.",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ],
-            example: {
-                method: "GET",
-                path: "/session/session-uuid-here/sink"
-            }
-        }
-    ],
-    schemas: {
-        SinkResponse: {
-            type: "object",
-            properties: {
-                tables: {
-                    type: "object",
-                    description: "Map of table names to their data",
-                    additionalProperties: {
-                        type: "object",
-                        properties: {
-                            schema: { type: "array", description: "Field definitions" },
-                            records: { type: "array", description: "All records in the table" }
-                        }
-                    }
-                },
-                metadata: {
-                    type: "object",
-                    properties: {
-                        session_id: { type: "uuid", description: "Source session" },
-                        exported_at: { type: "timestamp", description: "Export timestamp" },
-                        size: { type: "integer", description: "Backup size in bytes" }
-                    }
-                }
-            }
-        }
-    },
-    examples: [
-        {
-            title: "Export session data",
-            description: "Get all data from a hibernated session",
-            request: {
-                method: "GET",
-                path: "/session/abc123-session-uuid/sink",
-                headers: { "Authorization": "Bearer <token>" }
-            },
-            response: {
-                tables: {
-                    users: {
-                        schema: [
-                            { name: "id", type: "int" },
-                            { name: "email", type: "text" },
-                            { name: "name", type: "text" }
-                        ],
-                        records: [
-                            { id: 1, email: "alice@example.com", name: "Alice" },
-                            { id: 2, email: "bob@example.com", name: "Bob" }
-                        ]
-                    },
-                    orders: {
-                        schema: [
-                            { name: "id", type: "int" },
-                            { name: "user_id", type: "int" },
-                            { name: "total", type: "decimal" }
-                        ],
-                        records: [
-                            { id: 1, user_id: 1, total: 99.99 }
-                        ]
-                    }
-                }
-            }
-        }
-    ],
-    related_topics: ["session", "workflows"]
-};

package/dist/run_api_docs/topics/history.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const historyDoc: TopicDoc;

package/dist/run_api_docs/topics/history.js

@@ -1,93 +0,0 @@
-export const historyDoc = {
-    topic: "history",
-    title: "Run History & Document Analysis",
-    description: `Endpoints for viewing run execution history and analyzing XanoScript documents before execution.
-
-## Use Cases
-- **Run History**: Review past executions, track patterns, audit usage
-- **Document Analysis**: Validate scripts, understand structure before execution
-
-## History Features
-- Paginated access to run history
-- Sorted by creation time (newest first)
-- Includes run metadata and configuration`,
-    ai_hints: `- Use doc/info to validate scripts before execution
-- History is sorted by created_at descending (newest first)
-- Check existing runs before creating duplicates with same script
-- Use pagination for large history sets (default 20 per page, max 100)
-- Document info reveals functions, services, and jobs defined in a script`,
-    endpoints: [
-        {
-            method: "GET",
-            path: "/project/{project_id}/run",
-            tool_name: "getRunHistory",
-            description: "List run execution history for a project with pagination. Returns runs sorted by creation time (newest first).",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "page", type: "integer", default: 1, description: "Page number (min: 1)" },
-                { name: "per_page", type: "integer", default: 20, description: "Items per page (1-100)" }
-            ],
-            example: {
-                method: "GET",
-                path: "/project/abc123-uuid/run?page=1&per_page=20"
-            }
-        },
-        {
-            method: "POST",
-            path: "/project/{project_id}/doc/info",
-            tool_name: "getDocInfo",
-            description: "Parse and analyze a XanoScript document. Returns metadata about the document including defined functions, services, and jobs. Use this to validate scripts before execution.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project context" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    doc: { type: "text", required: true, description: "XanoScript document content to analyze" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/project/abc123-uuid/doc/info",
-                body: {
-                    doc: "job my_job {\n  input { text name }\n  response = \"Hello, \" + $input.name\n}\n\nservice my_service {\n  // service code\n}"
-                }
-            }
-        }
-    ],
-    schemas: {
-        RunHistoryItem: {
-            type: "object",
-            properties: {
-                id: { type: "uuid", description: "Run identifier" },
-                name: { type: "text", description: "Run name" },
-                type: { type: "enum", enum: ["job", "service"], description: "Run type" },
-                sig: { type: "text", description: "Document signature" },
-                project_id: { type: "uuid", description: "Project reference" },
-                user_id: { type: "integer", description: "Owner user ID" },
-                created_at: { type: "timestamp", description: "Creation time" },
-                updated_at: { type: "timestamp", description: "Last update time" }
-            }
-        },
-        DocInfo: {
-            type: "object",
-            properties: {
-                functions: { type: "array", description: "Defined functions" },
-                services: { type: "array", description: "Defined services" },
-                jobs: { type: "array", description: "Defined jobs" },
-                valid: { type: "boolean", description: "Whether document is valid" },
-                errors: { type: "array", description: "Parsing errors if any" }
-            }
-        },
-        PaginatedResponse: {
-            type: "object",
-            properties: {
-                items: { type: "array", description: "List of runs" },
-                curPage: { type: "integer", description: "Current page number" },
-                nextPage: { type: "integer", description: "Next page number or null" },
-                prevPage: { type: "integer", description: "Previous page number or null" }
-            }
-        }
-    },
-    related_topics: ["run", "session", "workflows"]
-};

package/dist/run_api_docs/topics/run.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const runDoc: TopicDoc;

package/dist/run_api_docs/topics/run.js

@@ -1,110 +0,0 @@
-export const runDoc = {
-    topic: "run",
-    title: "Run Execution",
-    description: `Endpoints for executing XanoScript runs. Runs are executable XanoScript documents that can be jobs (one-time execution) or services (long-running processes).
-
-## Run Types
-- **Job**: Executes once and terminates. Use for data processing, migrations, one-time tasks.
-- **Service**: Runs persistently in a tenant. Use for APIs, webhooks, background workers.
-
-## Execution Flow
-1. Submit XanoScript document via \`/run/exec\`
-2. System creates a session to track execution
-3. Session progresses through states: pending → processing → running → complete/error
-4. Retrieve results from the session
-
-## Templates
-The \`template\` parameter controls resource allocation:
-- \`small\`: Default, suitable for most workloads
-- Additional templates may be available for larger workloads`,
-    ai_hints: `- Include complete XanoScript in the 'doc' parameter
-- Use 'args' to pass dynamic data to runs (available as $args in XanoScript)
-- Use 'env' to override environment variables for this execution
-- Template affects resource allocation - use "small" for typical workloads
-- Re-executing a run reuses its stored configuration with optional overrides
-- Check the session state after execution to verify success`,
-    endpoints: [
-        {
-            method: "POST",
-            path: "/project/{project_id}/run/exec",
-            tool_name: "run",
-            description: "Execute a new XanoScript run. Creates a session to track execution and returns the result.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    doc: { type: "text", required: true, description: "XanoScript document content" },
-                    args: { type: "json", description: "Arguments passed to the job (default: {})" },
-                    env: { type: "json", description: "Environment variable overrides (default: {})" },
-                    template: { type: "text", description: "Execution template (default: 'small')" },
-                    logs: { type: "json[]", description: "Execution logs array (default: [])" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/project/abc123-uuid/run/exec",
-                body: {
-                    doc: "job process_data {\n  input { json items }\n  response = $input.items.map(i => i.value * 2)\n}",
-                    args: { items: [{ value: 1 }, { value: 2 }, { value: 3 }] },
-                    template: "small"
-                }
-            }
-        },
-        {
-            method: "POST",
-            path: "/project/{project_id}/run/{run_id}/exec",
-            description: "Re-execute an existing run by its ID. Uses the stored run configuration with optional argument and environment overrides.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "run_id", type: "uuid", required: true, in: "path", description: "Run UUID to re-execute" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    args: { type: "json", description: "Override arguments (default: {})" },
-                    env: { type: "json", description: "Override environment variables (default: {})" },
-                    template: { type: "text", description: "Execution template (default: 'small')" },
-                    logs: { type: "json[]", description: "Execution logs array (default: [])" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/project/abc123-uuid/run/run456-uuid/exec",
-                body: {
-                    args: { updated_value: 100 },
-                    template: "small"
-                }
-            }
-        }
-    ],
-    schemas: {
-        Run: {
-            type: "object",
-            properties: {
-                id: { type: "uuid", description: "Unique run identifier" },
-                name: { type: "text", description: "Run name" },
-                type: { type: "enum", enum: ["job", "service"], description: "Run type" },
-                doc: { type: "text", description: "XanoScript document content" },
-                args: { type: "json", description: "Stored arguments" },
-                project_id: { type: "uuid", description: "Associated project" },
-                user_id: { type: "integer", description: "Owner user ID" },
-                sig: { type: "text", description: "Document signature/hash" },
-                created_at: { type: "timestamp", description: "Creation time" },
-                updated_at: { type: "timestamp", description: "Last update time" }
-            }
-        },
-        ExecutionResult: {
-            type: "object",
-            properties: {
-                session_id: { type: "uuid", description: "Created session ID" },
-                state: { type: "enum", enum: ["pending", "processing", "running", "error", "complete"] },
-                response: { type: "any", description: "Execution result" },
-                error_msg: { type: "text", description: "Error message if failed" },
-                logs: { type: "json[]", description: "Execution logs" }
-            }
-        }
-    },
-    related_topics: ["session", "history", "workflows"]
-};

package/dist/run_api_docs/topics/session.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const sessionDoc: TopicDoc;

package/dist/run_api_docs/topics/session.js

@@ -1,166 +0,0 @@
-export const sessionDoc = {
-    topic: "session",
-    title: "Session Management",
-    description: `Sessions are active runtime execution contexts with isolated state. Each run execution creates a session that tracks the execution lifecycle, timing metrics, and results.
-
-## Session States
-- \`pending\`: Awaiting execution
-- \`processing\`: Setting up execution environment
-- \`running\`: Active execution in progress
-- \`error\`: Execution failed
-- \`complete\`: Execution finished successfully
-
-## Access Levels
-- \`private\`: Requires authentication and project ownership
-- \`public\`: Accessible without authentication
-
-## Session Lifecycle
-1. **Creation**: Session created when a run is executed
-2. **Execution**: Session progresses through states
-3. **Hibernation**: Long-running services may hibernate after timeout
-4. **Termination**: Sessions can be stopped manually or auto-cleanup
-
-## Timing Metrics
-Sessions track detailed timing information:
-- \`boot_time\`: Environment setup time
-- \`pre_time\`: Pre-execution processing
-- \`main_time\`: Main execution duration
-- \`post_time\`: Post-execution cleanup
-- \`total_time\`: Complete execution time`,
-    ai_hints: `- Check session state before performing operations
-- Only "service" type sessions can be re-executed with new documents
-- Public sessions are accessible without auth - use for sharing results
-- Sessions auto-hibernate after project timeout (default: 1 hour)
-- Use /stop endpoint to gracefully terminate running sessions
-- Cannot stop sessions already in "error" or "complete" state`,
-    endpoints: [
-        {
-            method: "GET",
-            path: "/project/{project_id}/run/session",
-            tool_name: "getProjectSessions",
-            description: "List all active sessions for a project with pagination.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "page", type: "integer", default: 1, description: "Page number (min: 1)" }
-            ]
-        },
-        {
-            method: "GET",
-            path: "/project/{project_id}/run/{run_id}/session",
-            tool_name: "getRunSessions",
-            description: "List all sessions for a specific run.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "run_id", type: "uuid", required: true, in: "path", description: "Run UUID" },
-                { name: "page", type: "integer", default: 1, description: "Page number (min: 1)" }
-            ]
-        },
-        {
-            method: "GET",
-            path: "/session/{session_id}",
-            tool_name: "getSession",
-            description: "Get detailed information about a session including status, run config, and timing metrics. Public sessions don't require authentication.",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ]
-        },
-        {
-            method: "POST",
-            path: "/session/{session_id}/access",
-            tool_name: "setSessionAccess",
-            description: "Update the access level of a session (public or private).",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    access: { type: "enum", required: true, description: "Access level: 'public' or 'private'" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/session/session-uuid/access",
-                body: { access: "public" }
-            }
-        },
-        {
-            method: "POST",
-            path: "/session/{session_id}/exec",
-            description: "Re-execute on an existing service session with a new XanoScript document. Reuses the session's resources (tenant). Only works on 'service' type sessions with a valid tenant.",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    doc: { type: "text", required: true, description: "New XanoScript document" },
-                    args: { type: "json", description: "Arguments (default: {})" },
-                    env: { type: "json", description: "Environment overrides (default: {})" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/session/session-uuid/exec",
-                body: {
-                    doc: "job updated_logic {\n  response = \"New execution on existing session\"\n}",
-                    args: {}
-                }
-            }
-        },
-        {
-            method: "PATCH",
-            path: "/session/{session_id}",
-            tool_name: "updateSessionRun",
-            description: "Update the run name associated with a session.",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    name: { type: "text", required: true, description: "New run name (min 1 character)" }
-                }
-            }
-        },
-        {
-            method: "POST",
-            path: "/project/{project_id}/run/{run_id}/session/{session_id}/stop",
-            tool_name: "stopSession",
-            description: "Stop and tear down a running session. Creates a backup before deletion. Cannot stop sessions already in 'error' or 'complete' state.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "run_id", type: "uuid", required: true, in: "path", description: "Run UUID" },
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ]
-        }
-    ],
-    schemas: {
-        Session: {
-            type: "object",
-            properties: {
-                id: { type: "uuid", description: "Session identifier" },
-                run_id: { type: "uuid", description: "Associated run" },
-                state: { type: "enum", enum: ["pending", "processing", "running", "error", "complete"], description: "Current state" },
-                access: { type: "enum", enum: ["private", "public"], description: "Access level" },
-                doc: { type: "text", description: "Executed XanoScript" },
-                version: { type: "integer", description: "Document version" },
-                response: { type: "json", description: "Execution response" },
-                error_msg: { type: "text", description: "Error message if failed" },
-                logs: { type: "json[]", description: "Execution logs" },
-                label: { type: "text", description: "Session label" },
-                tenant_id: { type: "integer", description: "Runtime tenant reference" },
-                hibernate_at: { type: "timestamp", description: "Hibernation timestamp" },
-                pre_time: { type: "decimal", description: "Pre-execution time" },
-                post_time: { type: "decimal", description: "Post-execution time" },
-                main_time: { type: "decimal", description: "Main execution time" },
-                boot_time: { type: "decimal", description: "Boot time" },
-                total_time: { type: "decimal", description: "Total execution time" },
-                backup: { type: "object", description: "Backup info with resource and size" },
-                created_at: { type: "timestamp", description: "Creation time" },
-                updated_at: { type: "timestamp", description: "Last update time" }
-            }
-        }
-    },
-    related_topics: ["run", "data", "workflows"]
-};

package/dist/run_api_docs/topics/start.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const startDoc: TopicDoc;