@xano/developer-mcp 1.0.13 → 1.0.15

package/dist/run_api_docs/format.js

@@ -0,0 +1,175 @@
+/**
+ * Formatting utilities for Run API documentation output
+ */
+/**
+ * Base URL information included with any topic that has endpoints
+ * NOTE: The Run API uses a FIXED base URL, not the user's Xano instance URL
+ */
+const BASE_URL_INFO = `## Base URL
+\`\`\`
+https://app.dev.xano.com/api:run/<endpoint>
+\`\`\`
+
+**Important:** This is a fixed URL - NOT your Xano instance URL. All Run API requests go to this central endpoint.
+
+Authorization: \`Bearer <your-access-token>\`
+`;
+function formatParameter(param) {
+    const required = param.required ? " (required)" : "";
+    const defaultVal = param.default !== undefined ? ` [default: ${param.default}]` : "";
+    const enumVals = param.enum ? ` [options: ${param.enum.join(", ")}]` : "";
+    return `  - \`${param.name}\`: ${param.type}${required}${defaultVal}${enumVals} - ${param.description}`;
+}
+function formatEndpoint(ep, detailLevel) {
+    const lines = [];
+    // Method and path
+    lines.push(`### ${ep.method} ${ep.path}`);
+    if (ep.tool_name) {
+        lines.push(`**Tool:** \`${ep.tool_name}\``);
+    }
+    lines.push("");
+    lines.push(ep.description);
+    if (detailLevel === "overview") {
+        return lines.join("\n");
+    }
+    // Parameters
+    if (ep.parameters?.length) {
+        lines.push("");
+        lines.push("**Parameters:**");
+        for (const param of ep.parameters) {
+            lines.push(formatParameter(param));
+        }
+    }
+    // Request body
+    if (ep.request_body) {
+        lines.push("");
+        lines.push(`**Request Body:** \`${ep.request_body.type}\``);
+        if (ep.request_body.properties) {
+            for (const [key, val] of Object.entries(ep.request_body.properties)) {
+                const req = val.required ? " (required)" : "";
+                lines.push(`  - \`${key}\`: ${val.type}${req} - ${val.description || ""}`);
+            }
+        }
+    }
+    // Example (only in detailed/examples mode)
+    if (detailLevel === "examples" && ep.example) {
+        lines.push("");
+        lines.push("**Example:**");
+        lines.push("```");
+        lines.push(`${ep.example.method} ${ep.example.path}`);
+        if (ep.example.body) {
+            lines.push(JSON.stringify(ep.example.body, null, 2));
+        }
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function formatExample(ex) {
+    const lines = [];
+    lines.push(`### ${ex.title}`);
+    lines.push("");
+    lines.push(ex.description);
+    lines.push("");
+    lines.push("**Request:**");
+    lines.push("```");
+    lines.push(`${ex.request.method} ${ex.request.path}`);
+    if (ex.request.headers) {
+        for (const [key, val] of Object.entries(ex.request.headers)) {
+            lines.push(`${key}: ${val}`);
+        }
+    }
+    if (ex.request.body) {
+        lines.push("");
+        lines.push(JSON.stringify(ex.request.body, null, 2));
+    }
+    lines.push("```");
+    if (ex.response !== undefined) {
+        lines.push("");
+        lines.push("**Response:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(ex.response, null, 2));
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function formatPattern(pattern) {
+    const lines = [];
+    lines.push(`### ${pattern.name}`);
+    if (pattern.description) {
+        lines.push("");
+        lines.push(pattern.description);
+    }
+    lines.push("");
+    lines.push("**Steps:**");
+    for (const step of pattern.steps) {
+        lines.push(step);
+    }
+    if (pattern.example) {
+        lines.push("");
+        lines.push("**Example:**");
+        lines.push("```");
+        lines.push(pattern.example);
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+export function formatDocumentation(doc, detailLevel = "detailed", includeSchemas = true) {
+    const sections = [];
+    // Header
+    sections.push(`# ${doc.title}`);
+    sections.push("");
+    sections.push(doc.description);
+    // AI Hints (always include for AI optimization)
+    if (doc.ai_hints) {
+        sections.push("");
+        sections.push("## AI Usage Hints");
+        sections.push(doc.ai_hints);
+    }
+    // Include base URL info if topic has endpoints or patterns (workflows)
+    if (doc.endpoints?.length || doc.patterns?.length) {
+        sections.push("");
+        sections.push(BASE_URL_INFO);
+    }
+    // Endpoints
+    if (doc.endpoints?.length) {
+        sections.push("## Endpoints");
+        for (const ep of doc.endpoints) {
+            sections.push("");
+            sections.push(formatEndpoint(ep, detailLevel));
+        }
+    }
+    // Patterns/Workflows
+    if (doc.patterns?.length) {
+        sections.push("");
+        sections.push("## Workflows");
+        for (const pattern of doc.patterns) {
+            sections.push("");
+            sections.push(formatPattern(pattern));
+        }
+    }
+    // Examples
+    if ((detailLevel === "detailed" || detailLevel === "examples") && doc.examples?.length) {
+        sections.push("");
+        sections.push("## Examples");
+        for (const ex of doc.examples) {
+            sections.push("");
+            sections.push(formatExample(ex));
+        }
+    }
+    // Schemas
+    if (includeSchemas && doc.schemas && Object.keys(doc.schemas).length > 0) {
+        sections.push("");
+        sections.push("## Schemas");
+        sections.push("");
+        sections.push("```json");
+        sections.push(JSON.stringify(doc.schemas, null, 2));
+        sections.push("```");
+    }
+    // Related topics
+    if (doc.related_topics?.length) {
+        sections.push("");
+        sections.push("## Related Topics");
+        sections.push(`Use \`run_api_docs\` with topic: ${doc.related_topics.join(", ")}`);
+    }
+    return sections.join("\n");
+}

package/dist/run_api_docs/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Xano Run API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the run_api_docs tool handler for the MCP server.
+ */
+import type { TopicDoc } from "../meta_api_docs/types.js";
+/**
+ * All available documentation topics
+ */
+export declare const topics: Record<string, TopicDoc>;
+/**
+ * Get list of all available topic names
+ */
+export declare function getTopicNames(): string[];
+/**
+ * Get topic descriptions for tool documentation
+ */
+export declare function getTopicDescriptions(): string;
+/**
+ * Handler for the run_api_docs tool
+ */
+export declare function handleRunApiDocs(topic?: string, detailLevel?: string, includeSchemas?: boolean): string;
+/**
+ * Tool definition for MCP server
+ */
+export declare const runApiDocsToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            topic: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            detail_level: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            include_schemas: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/run_api_docs/index.js

@@ -0,0 +1,90 @@
+/**
+ * Xano Run API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the run_api_docs tool handler for the MCP server.
+ */
+import { formatDocumentation } from "./format.js";
+// Import all topic documentation
+import { startDoc } from "./topics/start.js";
+import { runDoc } from "./topics/run.js";
+import { sessionDoc } from "./topics/session.js";
+import { historyDoc } from "./topics/history.js";
+import { dataDoc } from "./topics/data.js";
+import { workflowsDoc } from "./topics/workflows.js";
+/**
+ * All available documentation topics
+ */
+export const topics = {
+    start: startDoc,
+    run: runDoc,
+    session: sessionDoc,
+    history: historyDoc,
+    data: dataDoc,
+    workflows: workflowsDoc,
+};
+/**
+ * Get list of all available topic names
+ */
+export function getTopicNames() {
+    return Object.keys(topics);
+}
+/**
+ * Get topic descriptions for tool documentation
+ */
+export function getTopicDescriptions() {
+    return Object.entries(topics)
+        .map(([key, doc]) => `- ${key}: ${doc.title}`)
+        .join("\n");
+}
+/**
+ * Handler for the run_api_docs tool
+ */
+export function handleRunApiDocs(topic, detailLevel, includeSchemas) {
+    // Validate topic
+    if (!topic || !topics[topic]) {
+        const available = getTopicNames().join(", ");
+        return `Error: Unknown topic "${topic}".\n\nAvailable topics: ${available}`;
+    }
+    const doc = topics[topic];
+    return formatDocumentation(doc, detailLevel || "detailed", includeSchemas !== false);
+}
+/**
+ * Tool definition for MCP server
+ */
+export const runApiDocsToolDefinition = {
+    name: "run_api_docs",
+    description: `Get documentation for Xano's Run API. Use this to understand runtime execution, session management, and XanoScript execution.
+
+**Important:** The Run API uses a fixed base URL: https://app.dev.xano.com/api:run/<endpoint> (NOT your Xano instance URL)
+
+## Topics
+${getTopicDescriptions()}
+
+## Usage
+- Start with "start" topic for overview and getting started
+- Use "workflows" for step-by-step guides
+- Use specific topics (run, session, etc.) for detailed endpoint docs`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                enum: getTopicNames(),
+                description: "Documentation topic to retrieve",
+            },
+            detail_level: {
+                type: "string",
+                enum: ["overview", "detailed", "examples"],
+                default: "detailed",
+                description: "Level of detail: overview (brief), detailed (full docs), examples (with code examples)",
+            },
+            include_schemas: {
+                type: "boolean",
+                default: true,
+                description: "Include JSON schemas for requests/responses",
+            },
+        },
+        required: ["topic"],
+    },
+};

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

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

package/dist/run_api_docs/topics/data.js

@@ -0,0 +1,104 @@
+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

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

package/dist/run_api_docs/topics/history.js

@@ -0,0 +1,93 @@
+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

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

package/dist/run_api_docs/topics/run.js

@@ -0,0 +1,110 @@
+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

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