@xano/developer-mcp 1.0.13 → 1.0.15

package/dist/run_api_docs/topics/session.js

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

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

package/dist/run_api_docs/topics/start.js

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

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

package/dist/run_api_docs/topics/workflows.js

@@ -0,0 +1,140 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "MCP server for Xano Headless API documentation and XanoScript code validation",
   "type": "module",
   "main": "dist/index.js",