@xano/developer-mcp 1.0.27 → 1.0.29

package/README.md

@@ -40,7 +40,7 @@ This MCP server acts as a bridge between AI models and Xano's developer ecosyste
 ### Claude Code (Recommended)
 
 ```bash
-claude mcp add xano-developer -- npx -y @xano/developer-mcp
+claude mcp add xano -- npx -y @xano/developer-mcp
 ```
 
 That's it! The MCP server will be automatically installed and configured.

package/dist/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/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 \`api_docs\` with topic: ${doc.related_topics.join(", ")}`);
+    }
+    return sections.join("\n");
+}

package/dist/api_docs/index.d.ts

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

@@ -0,0 +1,111 @@
+/**
+ * Xano Meta API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the 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 api_docs tool
+ */
+export function handleApiDocs(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 apiDocsToolDefinition = {
+    name: "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/api_docs/topics/agent.d.ts

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

package/dist/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/api_docs/topics/api.d.ts

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

package/dist/api_docs/topics/api.js

@@ -0,0 +1,176 @@
+export const apiDoc = {
+    topic: "api",
+    title: "API Endpoint Management",
+    description: `API endpoints define individual HTTP routes within an API group. Each endpoint has a path, HTTP method, inputs, and XanoScript logic.
+
+## Key Concepts
+- Endpoints belong to API groups
+- Each endpoint has: method (GET/POST/PUT/DELETE), path, inputs, and stack (logic)
+- Supports path parameters like \`/users/{id}\`
+- XanoScript defines the endpoint logic`,
+    ai_hints: `- Use \`include_xanoscript=true\` to see the endpoint's implementation
+- Check existing endpoints before creating to avoid duplicates
+- Path parameters use \`{param_name}\` syntax
+- Common patterns: CRUD operations, search, authentication
+- Security settings can override group-level settings`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api",
+            tool_name: "listApis",
+            description: "List all API endpoints in an API group.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group 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 name or path" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript code in response" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft versions" },
+                { name: "branch", type: "string", description: "Filter by branch name" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}",
+            tool_name: "getApi",
+            description: "Get details of a specific API endpoint.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group ID" },
+                { name: "api_id", type: "integer", required: true, in: "path", description: "API ID" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript code" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft version" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api",
+            tool_name: "createApi",
+            description: "Create a new API endpoint with XanoScript logic.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Endpoint name", required: true },
+                    path: { type: "string", description: "URL path (e.g., /users/{id})", required: true },
+                    verb: { type: "string", description: "HTTP method: GET, POST, PUT, DELETE", required: true },
+                    description: { type: "string", description: "Endpoint description" },
+                    xanoscript: { type: "string", description: "XanoScript code defining the endpoint logic" }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/apigroup/2/api",
+                body: {
+                    name: "getUsers",
+                    path: "/users",
+                    verb: "GET",
+                    xanoscript: "query getUsers {\n  response = db.users.query().all()\n}"
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}",
+            tool_name: "updateApi",
+            description: "Update an existing API endpoint.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group ID" },
+                { name: "api_id", type: "integer", required: true, in: "path", description: "API ID" },
+                { name: "publish", type: "boolean", default: true, description: "Publish changes immediately" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Endpoint name" },
+                    path: { type: "string", description: "URL path" },
+                    verb: { type: "string", description: "HTTP method" },
+                    description: { type: "string", description: "Endpoint description" },
+                    xanoscript: { type: "string", description: "XanoScript code" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}",
+            tool_name: "deleteApi",
+            description: "Delete an API endpoint.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group ID" },
+                { name: "api_id", type: "integer", required: true, in: "path", description: "API ID" }
+            ]
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}/security",
+            tool_name: "updateApiSecurity",
+            description: "Update security settings for a specific endpoint (overrides group settings).",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "apigroup_id", type: "integer", required: true, in: "path", description: "API Group ID" },
+                { name: "api_id", type: "integer", required: true, in: "path", description: "API ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    guid: { type: "string", description: "Security group GUID" }
+                }
+            }
+        }
+    ],
+    schemas: {
+        Api: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                path: { type: "string" },
+                verb: { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] },
+                description: { type: "string" },
+                xanoscript: { type: "string", description: "Only included if include_xanoscript=true" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    examples: [
+        {
+            title: "Create a GET endpoint",
+            description: "Create a simple endpoint to list all users",
+            request: {
+                method: "POST",
+                path: "/workspace/1/apigroup/2/api",
+                body: {
+                    name: "listUsers",
+                    path: "/users",
+                    verb: "GET",
+                    xanoscript: `query listUsers {
+  input {
+    int page = 1
+    int per_page = 20
+  }
+  stack {
+    var $users {
+      value = db.users.query().paginate($input.page, $input.per_page)
+    }
+  }
+  response = $users
+}`
+                }
+            },
+            response: {
+                id: 123,
+                name: "listUsers",
+                path: "/users",
+                verb: "GET"
+            }
+        }
+    ],
+    related_topics: ["apigroup", "function", "table"]
+};

package/dist/api_docs/topics/apigroup.d.ts

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