@xano/developer-mcp 1.0.13 → 1.0.15

package/README.md

@@ -194,7 +194,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 +230,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
@@ -287,7 +287,7 @@ 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
@@ -327,7 +327,7 @@ 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
     │
     ├─► mcp_version → Returns server version from package.json
     │
@@ -357,7 +357,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/api_docs/format.js

@@ -121,10 +121,13 @@ export function formatDocumentation(doc, detailLevel = "detailed", includeSchema
         sections.push("## AI Usage Hints");
         sections.push(doc.ai_hints);
     }
-    // Endpoints
-    if (doc.endpoints?.length) {
+    // 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("");

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"));
@@ -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;

package/dist/meta_api_docs/topics/agent.js

@@ -0,0 +1,142 @@
+export const agentDoc = {
+    topic: "agent",
+    title: "AI Agent Management",
+    description: `Agents are AI-powered automation units that use LLMs (like Claude) to make decisions and execute multi-step workflows.
+
+## Key Concepts
+- Agents use LLMs for reasoning and decision-making
+- Can call tools to perform actions
+- Support multiple LLM providers (Anthropic, OpenAI, etc.)
+- Configurable system prompts, temperature, max steps
+- Can have triggers that invoke them automatically
+
+## LLM Configuration
+- Type: Provider (e.g., "anthropic")
+- Model: Specific model (e.g., "claude-4-sonnet-20250514")
+- System prompt: Instructions for the agent
+- Temperature: Creativity level (0-1)
+- Max steps: Maximum reasoning iterations
+- Reasoning: Enable/disable chain-of-thought`,
+    ai_hints: `- Create tools first, then create agent and associate tools
+- System prompt is critical for agent behavior
+- Lower temperature = more deterministic responses
+- Max steps limits runaway agent loops
+- Use triggers to invoke agents on events (table changes, etc.)`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/agent",
+            tool_name: "listAgents",
+            description: "List all AI agents in a workspace.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "page", type: "integer", default: 1, description: "Page number" },
+                { name: "per_page", type: "integer", default: 50, description: "Items per page" },
+                { name: "search", type: "string", description: "Search by agent name" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft versions" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "getAgent",
+            description: "Get details of a specific AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft version" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/agent",
+            tool_name: "createAgent",
+            description: "Create a new AI agent with LLM configuration.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Agent name", required: true },
+                    description: { type: "string", description: "Agent description" },
+                    xanoscript: { type: "string", description: "XanoScript agent definition", required: true }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/agent",
+                body: {
+                    name: "support_agent",
+                    description: "Customer support AI agent",
+                    xanoscript: `agent support_agent {
+  llm {
+    type = "anthropic"
+    model = "claude-4-sonnet-20250514"
+    system_prompt = "You are a helpful customer support agent."
+    max_steps = 10
+    temperature = 0.3
+  }
+  tools = [lookup_order, update_ticket]
+}`
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "updateAgent",
+            description: "Update an existing AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" },
+                { name: "publish", type: "boolean", default: true, description: "Publish changes immediately" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Agent name" },
+                    description: { type: "string", description: "Agent description" },
+                    xanoscript: { type: "string", description: "XanoScript agent definition" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "deleteAgent",
+            description: "Delete an AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" }
+            ]
+        }
+    ],
+    schemas: {
+        Agent: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                llm: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", description: "LLM provider (anthropic, openai, etc.)" },
+                        model: { type: "string", description: "Model identifier" },
+                        system_prompt: { type: "string" },
+                        max_steps: { type: "integer" },
+                        temperature: { type: "number" },
+                        reasoning: { type: "boolean" }
+                    }
+                },
+                tools: { type: "array", items: { type: "string" } },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["tool", "mcp_server", "function"]
+};

package/dist/meta_api_docs/topics/api.d.ts

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