@xano/developer-mcp 1.0.14 → 1.0.16

package/README.md

@@ -7,6 +7,7 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
 This MCP server acts as a bridge between AI models and Xano's developer ecosystem, offering:
 
 - **Meta API Documentation** - Programmatically manage Xano workspaces, databases, APIs, functions, and more
+- **Run API Documentation** - Runtime execution, session management, and XanoScript execution
 - **XanoScript Documentation** - Language reference with context-aware docs based on file type
 - **Code Validation** - Syntax checking with the official XanoScript language server
 - **Workflow Guides** - Step-by-step guides for common development tasks
@@ -157,7 +158,7 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | `testing` | Unit tests, mocks, and assertions |
 | `integrations` | Cloud storage, Redis, security, and external APIs |
 | `frontend` | Static frontend development and deployment |
-| `ephemeral` | Temporary test environments |
+| `run` | Run job and service configurations |
 | `addons` | Reusable subqueries for fetching related data |
 | `debugging` | Logging, inspecting, and debugging XanoScript execution |
 | `performance` | Performance optimization best practices |
@@ -181,6 +182,45 @@ xanoscript_docs({ file_path: "apis/users/create.xs" })
 xanoscript_docs({ topic: "database", mode: "quick_reference" })
 ```
 
+### 3. `run_api_docs`
+
+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)
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | string | Yes | Documentation topic to retrieve |
+| `detail_level` | string | No | `overview`, `detailed` (default), or `examples` |
+| `include_schemas` | boolean | No | Include JSON schemas for requests/responses (default: true) |
+
+**Available Topics:**
+
+| Topic | Description |
+|-------|-------------|
+| `start` | Getting started with the Run API |
+| `run` | Execute XanoScript code and API endpoints |
+| `session` | Session management for stateful execution |
+| `history` | Execution history and debugging |
+| `data` | Data operations and variable management |
+| `workflows` | Step-by-step workflow guides |
+
+**Examples:**
+```
+// Get overview of Run API
+run_api_docs({ topic: "start" })
+
+// Get detailed run endpoint documentation
+run_api_docs({ topic: "run", detail_level: "detailed" })
+
+// Get examples without schemas (smaller context)
+run_api_docs({ topic: "session", detail_level: "examples", include_schemas: false })
+
+// Step-by-step workflow guides
+run_api_docs({ topic: "workflows" })
+```
+
 ### 4. `mcp_version`
 
 Get the current version of the Xano Developer MCP server.
@@ -194,7 +234,7 @@ Get the current version of the Xano Developer MCP server.
 mcp_version()
 ```
 
-### 5. `api_docs`
+### 5. `meta_api_docs`
 
 Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.
 
@@ -230,16 +270,16 @@ Get documentation for Xano's Meta API. Use this to understand how to programmati
 **Examples:**
 ```
 // Get overview of Meta API
-api_docs({ topic: "start" })
+meta_api_docs({ topic: "start" })
 
 // Get detailed table documentation
-api_docs({ topic: "table", detail_level: "detailed" })
+meta_api_docs({ topic: "table", detail_level: "detailed" })
 
 // Get examples without schemas (smaller context)
-api_docs({ topic: "api", detail_level: "examples", include_schemas: false })
+meta_api_docs({ topic: "api", detail_level: "examples", include_schemas: false })
 
 // Step-by-step workflow guides
-api_docs({ topic: "workflows" })
+meta_api_docs({ topic: "workflows" })
 ```
 
 ## MCP Resources
@@ -263,7 +303,7 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `xanoscript://docs/testing` | Unit tests and mocks |
 | `xanoscript://docs/integrations` | External service integrations |
 | `xanoscript://docs/frontend` | Static frontend development |
-| `xanoscript://docs/ephemeral` | Temporary test environments |
+| `xanoscript://docs/run` | Run job and service configurations |
 | `xanoscript://docs/addons` | Reusable subqueries for related data |
 | `xanoscript://docs/debugging` | Logging and debugging tools |
 | `xanoscript://docs/performance` | Performance optimization |
@@ -287,11 +327,15 @@ xano-developer-mcp/
 ├── src/
 │   ├── index.ts              # Main MCP server implementation
 │   ├── xanoscript.d.ts       # TypeScript declarations
-│   ├── api_docs/             # Meta API documentation
+│   ├── meta_api_docs/        # Meta API documentation
 │   │   ├── index.ts          # API docs tool handler
 │   │   ├── types.ts          # Type definitions
 │   │   ├── format.ts         # Documentation formatter
 │   │   └── topics/           # Individual topic modules
+│   ├── run_api_docs/         # Run API documentation
+│   │   ├── index.ts          # Run API tool handler
+│   │   ├── format.ts         # Documentation formatter
+│   │   └── topics/           # Individual topic modules
 │   ├── xanoscript_docs/      # XanoScript language documentation
 │   │   ├── version.json
 │   │   ├── README.md
@@ -327,7 +371,9 @@ Xano Developer MCP Server
     │
     ├─► xanoscript_docs → Context-aware docs from /xanoscript_docs/*.md
     │
-    ├─► api_docs → Meta API documentation with detail levels
+    ├─► meta_api_docs → Meta API documentation with detail levels
+    │
+    ├─► run_api_docs → Run API documentation for runtime execution
     │
     ├─► mcp_version → Returns server version from package.json
     │
@@ -357,7 +403,7 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
   - **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
   - **description**: Human-readable description of the topic
 
-**Meta API Documentation** (`src/api_docs/`):
+**Meta API Documentation** (`src/meta_api_docs/`):
 - TypeScript modules with structured documentation
 - Supports parameterized output (detail levels, schema inclusion)
 - Better for AI consumption due to context efficiency

package/dist/index.js

@@ -8,7 +8,8 @@ import { dirname, join } from "path";
 import { minimatch } from "minimatch";
 import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser.js";
 import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
-import { apiDocsToolDefinition, handleApiDocs } from "./api_docs/index.js";
+import { metaApiDocsToolDefinition, handleMetaApiDocs } from "./meta_api_docs/index.js";
+import { runApiDocsToolDefinition, handleRunApiDocs } from "./run_api_docs/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -93,10 +94,10 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["static/**/*"],
         description: "Static frontend development and deployment",
     },
-    ephemeral: {
-        file: "ephemeral.md",
-        applyTo: ["ephemeral/**/*.xs"],
-        description: "Temporary test environments",
+    run: {
+        file: "run.md",
+        applyTo: ["run/**/*.xs"],
+        description: "Run job and service configurations for the Xano Job Runner",
     },
     addons: {
         file: "addons.md",
@@ -366,7 +367,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: [],
                 },
             },
-            apiDocsToolDefinition,
+            metaApiDocsToolDefinition,
+            runApiDocsToolDefinition,
         ],
     };
 });
@@ -465,21 +467,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             ],
         };
     }
-    if (request.params.name === "api_docs") {
+    if (request.params.name === "meta_api_docs") {
         const args = request.params.arguments;
         if (!args?.topic) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: "Error: 'topic' parameter is required. Use api_docs with topic='start' for overview.",
+                        text: "Error: 'topic' parameter is required. Use meta_api_docs with topic='start' for overview.",
                     },
                 ],
                 isError: true,
             };
         }
         try {
-            const documentation = handleApiDocs({
+            const documentation = handleMetaApiDocs({
                 topic: args.topic,
                 detail_level: args.detail_level,
                 include_schemas: args.include_schemas,
@@ -506,6 +508,43 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === "run_api_docs") {
+        const args = request.params.arguments;
+        if (!args?.topic) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: 'topic' parameter is required. Use run_api_docs with topic='start' for overview.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const documentation = handleRunApiDocs(args.topic, args.detail_level, args.include_schemas);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: documentation,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error retrieving Run API documentation: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
     return {
         content: [
             {

package/dist/meta_api_docs/format.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Formatting utilities for API documentation output
+ */
+import type { TopicDoc, DetailLevel } from "./types.js";
+export declare function formatDocumentation(doc: TopicDoc, detailLevel?: DetailLevel, includeSchemas?: boolean): string;

package/dist/meta_api_docs/format.js

@@ -0,0 +1,171 @@
+/**
+ * Formatting utilities for API documentation output
+ */
+/**
+ * Base URL information included with any topic that has endpoints
+ */
+const BASE_URL_INFO = `## Base URL
+\`\`\`
+https://<your-instance-subdomain>.xano.io/api:meta/<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 \`meta_api_docs\` with topic: ${doc.related_topics.join(", ")}`);
+    }
+    return sections.join("\n");
+}

package/dist/meta_api_docs/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Xano Meta API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the meta_api_docs tool handler for the MCP server.
+ */
+import type { TopicDoc, MetaApiDocsArgs } from "./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 meta_api_docs tool
+ */
+export declare function handleMetaApiDocs(args: MetaApiDocsArgs): string;
+/**
+ * Tool definition for MCP server
+ */
+export declare const metaApiDocsToolDefinition: {
+    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/meta_api_docs/index.js

@@ -0,0 +1,111 @@
+/**
+ * Xano Meta API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the meta_api_docs tool handler for the MCP server.
+ */
+import { formatDocumentation } from "./format.js";
+// Import all topic documentation
+import { startDoc } from "./topics/start.js";
+import { authenticationDoc } from "./topics/authentication.js";
+import { workspaceDoc } from "./topics/workspace.js";
+import { apigroupDoc } from "./topics/apigroup.js";
+import { apiDoc } from "./topics/api.js";
+import { tableDoc } from "./topics/table.js";
+import { functionDoc } from "./topics/function.js";
+import { taskDoc } from "./topics/task.js";
+import { agentDoc } from "./topics/agent.js";
+import { toolDoc } from "./topics/tool.js";
+import { mcpServerDoc } from "./topics/mcp_server.js";
+import { middlewareDoc } from "./topics/middleware.js";
+import { branchDoc } from "./topics/branch.js";
+import { realtimeDoc } from "./topics/realtime.js";
+import { fileDoc } from "./topics/file.js";
+import { historyDoc } from "./topics/history.js";
+import { workflowsDoc } from "./topics/workflows.js";
+/**
+ * All available documentation topics
+ */
+export const topics = {
+    start: startDoc,
+    authentication: authenticationDoc,
+    workspace: workspaceDoc,
+    apigroup: apigroupDoc,
+    api: apiDoc,
+    table: tableDoc,
+    function: functionDoc,
+    task: taskDoc,
+    agent: agentDoc,
+    tool: toolDoc,
+    mcp_server: mcpServerDoc,
+    middleware: middlewareDoc,
+    branch: branchDoc,
+    realtime: realtimeDoc,
+    file: fileDoc,
+    history: historyDoc,
+    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 meta_api_docs tool
+ */
+export function handleMetaApiDocs(args) {
+    const { topic, detail_level = "detailed", include_schemas = true } = args;
+    // Validate topic
+    if (!topics[topic]) {
+        const available = getTopicNames().join(", ");
+        return `Error: Unknown topic "${topic}".\n\nAvailable topics: ${available}`;
+    }
+    const doc = topics[topic];
+    return formatDocumentation(doc, detail_level, include_schemas);
+}
+/**
+ * Tool definition for MCP server
+ */
+export const metaApiDocsToolDefinition = {
+    name: "meta_api_docs",
+    description: `Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.
+
+## Topics
+${getTopicDescriptions()}
+
+## Usage
+- Start with "start" topic for overview and getting started
+- Use "workflows" for step-by-step guides
+- Use specific topics (workspace, table, api, 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/meta_api_docs/topics/agent.d.ts

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