@xano/developer-mcp 1.0.41 → 1.0.42

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;

package/dist/run_api_docs/topics/start.js

@@ -1,97 +0,0 @@
-export const startDoc = {
-    topic: "start",
-    title: "Xano Run API - Getting Started",
-    description: `The Xano Run API provides programmatic access to execute XanoScript, manage runtime sessions, and work with execution environments. Use it to run scripts, manage long-running services, and retrieve execution history.
-
-## 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.
-
-## Authentication
-Include your Access Token in the Authorization header:
-\`\`\`
-Authorization: Bearer <your-access-token>
-\`\`\`
-
-Access tokens are created in the Xano dashboard under Settings > Access Tokens.
-
-## Key Concepts
-
-### Run Types
-- **Job**: One-time execution that runs to completion and terminates
-- **Service**: Long-running process that persists in a tenant until stopped
-
-### Sessions
-Sessions are active runtime execution contexts with isolated state. Each execution creates a session that tracks:
-- Execution state (pending, processing, running, error, complete)
-- Timing metrics (boot_time, main_time, total_time, etc.)
-- Response data and logs
-- Access level (public/private)
-
-### Resource Hierarchy
-\`\`\`
-project/
-  └── run/                  # Stored run configurations
-      └── session/          # Active execution contexts
-          └── backup/sink   # Data snapshots
-\`\`\`
-
-## Quick Start
-1. **Execute a script:** \`POST /project/{project_id}/run/exec\` with your XanoScript
-2. **Check session status:** \`GET /session/{session_id}\`
-3. **View run history:** \`GET /project/{project_id}/run\`
-
-## Common Parameters
-- \`project_id\`: UUID of your project (required for most endpoints)
-- \`run_id\`: UUID of a stored run configuration
-- \`session_id\`: UUID of an active session
-- \`doc\`: XanoScript document content
-- \`args\`: JSON arguments passed to the execution
-- \`env\`: Environment variable overrides`,
-    ai_hints: `- Use \`POST /project/{id}/run/exec\` to execute new XanoScript
-- Sessions are created automatically from executions
-- Use "job" type for one-time tasks, "service" for long-running processes
-- Check session state before operations (running, error, complete)
-- Only "service" type sessions can be re-executed with new documents
-- Use \`GET /session/{id}/sink\` to export all data after hibernation`,
-    related_topics: ["run", "session", "workflows"],
-    examples: [
-        {
-            title: "Execute a simple XanoScript",
-            description: "Run a XanoScript job and get the result",
-            request: {
-                method: "POST",
-                path: "/project/abc123-uuid/run/exec",
-                headers: { "Authorization": "Bearer <token>" },
-                body: {
-                    doc: "job hello {\n  response = \"Hello, World!\"\n}",
-                    args: {},
-                    template: "small"
-                }
-            },
-            response: {
-                session_id: "session-uuid-here",
-                state: "complete",
-                response: "Hello, World!"
-            }
-        },
-        {
-            title: "Check session status",
-            description: "Get details about a running or completed session",
-            request: {
-                method: "GET",
-                path: "/session/session-uuid-here",
-                headers: { "Authorization": "Bearer <token>" }
-            },
-            response: {
-                id: "session-uuid-here",
-                state: "running",
-                access: "private",
-                created_at: "2024-01-15T10:30:00Z"
-            }
-        }
-    ]
-};

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

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

package/dist/run_api_docs/topics/workflows.js

@@ -1,140 +0,0 @@
-export const workflowsDoc = {
-    topic: "workflows",
-    title: "Common Workflows",
-    description: `Step-by-step guides for common multi-step tasks using the Xano Run API.
-
-## Quick Reference
-- **Execute Script**: validate doc → execute → check session
-- **Monitor Session**: list sessions → get details → check state
-- **Export Data**: execute service → wait for hibernate → get sink
-- **Re-execute**: get history → re-execute with overrides`,
-    ai_hints: `- Always validate scripts with doc/info before execution
-- Monitor session state changes for long-running services
-- Clean up unused sessions to conserve resources
-- Use the fixed base URL: https://app.dev.xano.com/api:run/<endpoint>
-- Sessions auto-hibernate after project timeout
-- Export data via /sink only after hibernation`,
-    patterns: [
-        {
-            name: "Execute New XanoScript",
-            description: "Validate, execute, and monitor a XanoScript job",
-            steps: [
-                "1. `POST /project/{project_id}/doc/info` - Validate script structure",
-                "2. `POST /project/{project_id}/run/exec` - Execute the script",
-                "3. `GET /session/{session_id}` - Check execution status",
-                "4. (if running) Poll session until state is 'complete' or 'error'"
-            ],
-            example: `// 1. Validate document
-POST https://app.dev.xano.com/api:run/project/abc123/doc/info
-{
-  "doc": "job process_data {\\n  response = db.items.query().all()\\n}"
-}
-
-// 2. Execute
-POST https://app.dev.xano.com/api:run/project/abc123/run/exec
-{
-  "doc": "job process_data {\\n  response = db.items.query().all()\\n}",
-  "args": {},
-  "template": "small"
-}
-
-// 3. Check status
-GET https://app.dev.xano.com/api:run/session/{returned_session_id}`
-        },
-        {
-            name: "Run a Persistent Service",
-            description: "Start a long-running service and manage its lifecycle",
-            steps: [
-                "1. `POST /project/{project_id}/run/exec` - Start service (type: service)",
-                "2. `GET /session/{session_id}` - Verify service is running",
-                "3. `POST /session/{session_id}/access` - Optionally make public",
-                "4. `POST /session/{session_id}/exec` - Re-execute with new code if needed",
-                "5. `POST /project/{project_id}/run/{run_id}/session/{session_id}/stop` - Stop when done"
-            ],
-            example: `// 1. Start service
-POST https://app.dev.xano.com/api:run/project/abc123/run/exec
-{
-  "doc": "service my_api {\\n  endpoint GET /hello {\\n    response = 'Hello!'\\n  }\\n}",
-  "args": {}
-}
-
-// 2. Stop service when done
-POST https://app.dev.xano.com/api:run/project/abc123/run/{run_id}/session/{session_id}/stop`
-        },
-        {
-            name: "Export Session Data",
-            description: "Export all data from a session after hibernation",
-            steps: [
-                "1. Execute a run (job or service)",
-                "2. Wait for session to hibernate (auto or via stop)",
-                "3. `GET /session/{session_id}/sink` - Export all data"
-            ],
-            example: `// 1. After session has run and hibernated
-GET https://app.dev.xano.com/api:run/session/{session_id}/sink
-
-// Response includes all tables and records as JSON`
-        },
-        {
-            name: "Re-execute with Modified Arguments",
-            description: "Run an existing script again with different inputs",
-            steps: [
-                "1. `GET /project/{project_id}/run` - Get run history",
-                "2. Find the run_id you want to re-execute",
-                "3. `POST /project/{project_id}/run/{run_id}/exec` - Re-execute with new args"
-            ],
-            example: `// 1. Get history
-GET https://app.dev.xano.com/api:run/project/abc123/run
-
-// 2. Re-execute with different args
-POST https://app.dev.xano.com/api:run/project/abc123/run/{run_id}/exec
-{
-  "args": {
-    "batch_size": 100,
-    "mode": "production"
-  }
-}`
-        },
-        {
-            name: "Monitor Active Sessions",
-            description: "List and monitor running sessions for a project",
-            steps: [
-                "1. `GET /project/{project_id}/run/session` - List all sessions",
-                "2. Filter by state (running, pending, etc.)",
-                "3. `GET /session/{session_id}` - Get details for specific session",
-                "4. Take action based on state (stop, re-execute, export)"
-            ],
-            example: `// 1. List sessions
-GET https://app.dev.xano.com/api:run/project/abc123/run/session?page=1
-
-// 2. Check specific session
-GET https://app.dev.xano.com/api:run/session/{session_id}
-
-// 3. Stop if needed
-POST https://app.dev.xano.com/api:run/project/abc123/run/{run_id}/session/{session_id}/stop`
-        },
-        {
-            name: "Debug Failed Execution",
-            description: "Investigate why a run failed",
-            steps: [
-                "1. `GET /session/{session_id}` - Check session state and error_msg",
-                "2. Review the 'logs' field for execution details",
-                "3. `POST /project/{project_id}/doc/info` - Validate the script syntax",
-                "4. Fix issues and re-execute"
-            ],
-            example: `// 1. Get session details
-GET https://app.dev.xano.com/api:run/session/{session_id}
-
-// Response includes:
-// - state: "error"
-// - error_msg: "Detailed error message"
-// - logs: [...execution logs...]
-
-// 2. Validate fixed script
-POST https://app.dev.xano.com/api:run/project/abc123/doc/info
-{
-  "doc": "job fixed_script {\\n  // corrected code\\n}"
-}`
-        }
-    ],
-    related_topics: ["start", "run", "session", "data"]
-};

package/dist/tools/run_api_docs.d.ts

@@ -1,46 +0,0 @@
-/**
- * Run API Documentation Tool
- *
- * Retrieves documentation for Xano's Run API.
- * Re-exports from the run_api_docs module with ToolResult support.
- */
-import { runApiDocsToolDefinition, topics, getTopicNames, getTopicDescriptions } from "../run_api_docs/index.js";
-import type { TopicDoc, DetailLevel } from "../meta_api_docs/types.js";
-import type { ToolResult } from "./types.js";
-export { runApiDocsToolDefinition, topics as runApiTopics, getTopicNames as getRunApiTopicNames, getTopicDescriptions as getRunApiTopicDescriptions, };
-export type { TopicDoc, DetailLevel };
-export interface RunApiDocsArgs {
-    topic: string;
-    detail_level?: DetailLevel;
-    include_schemas?: boolean;
-}
-export interface RunApiDocsResult {
-    documentation: string;
-}
-/**
- * Get Xano Run API documentation.
- *
- * @param args - Documentation arguments
- * @returns Documentation content
- *
- * @example
- * ```ts
- * import { runApiDocs } from '@xano/developer-mcp';
- *
- * // Get overview
- * const overview = runApiDocs({ topic: 'start' });
- *
- * // Get session documentation with examples
- * const sessionDocs = runApiDocs({
- *   topic: 'session',
- *   detail_level: 'examples',
- *   include_schemas: true
- * });
- * ```
- */
-export declare function runApiDocs(args: RunApiDocsArgs): RunApiDocsResult;
-/**
- * Get Run API documentation and return a ToolResult.
- */
-export declare function runApiDocsTool(args: RunApiDocsArgs): ToolResult;
-export { runApiDocsToolDefinition as toolDefinition };

package/dist/tools/run_api_docs.js

@@ -1,69 +0,0 @@
-/**
- * Run API Documentation Tool
- *
- * Retrieves documentation for Xano's Run API.
- * Re-exports from the run_api_docs module with ToolResult support.
- */
-import { handleRunApiDocs as _handleRunApiDocs, runApiDocsToolDefinition, topics, getTopicNames, getTopicDescriptions, } from "../run_api_docs/index.js";
-// =============================================================================
-// Re-exports
-// =============================================================================
-export { runApiDocsToolDefinition, topics as runApiTopics, getTopicNames as getRunApiTopicNames, getTopicDescriptions as getRunApiTopicDescriptions, };
-// =============================================================================
-// Standalone Tool Function
-// =============================================================================
-/**
- * Get Xano Run API documentation.
- *
- * @param args - Documentation arguments
- * @returns Documentation content
- *
- * @example
- * ```ts
- * import { runApiDocs } from '@xano/developer-mcp';
- *
- * // Get overview
- * const overview = runApiDocs({ topic: 'start' });
- *
- * // Get session documentation with examples
- * const sessionDocs = runApiDocs({
- *   topic: 'session',
- *   detail_level: 'examples',
- *   include_schemas: true
- * });
- * ```
- */
-export function runApiDocs(args) {
-    if (!args?.topic) {
-        throw new Error("'topic' parameter is required. Use topic='start' for overview.");
-    }
-    const documentation = _handleRunApiDocs(args.topic, args.detail_level, args.include_schemas);
-    return { documentation };
-}
-/**
- * Get Run API documentation and return a ToolResult.
- */
-export function runApiDocsTool(args) {
-    if (!args?.topic) {
-        return {
-            success: false,
-            error: "Error: 'topic' parameter is required. Use run_api_docs with topic='start' for overview.",
-        };
-    }
-    try {
-        const result = runApiDocs(args);
-        return {
-            success: true,
-            data: result.documentation,
-        };
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return {
-            success: false,
-            error: `Error retrieving Run API documentation: ${errorMessage}`,
-        };
-    }
-}
-// Re-export tool definition for MCP
-export { runApiDocsToolDefinition as toolDefinition };