@xano/developer-mcp 1.0.13 → 1.0.15

package/dist/meta_api_docs/topics/tool.js

@@ -0,0 +1,150 @@
+export const toolDoc = {
+    topic: "tool",
+    title: "Agent Tool Management",
+    description: `Tools are callable functions that AI agents can use to perform actions. They define inputs, outputs, and the logic to execute.
+
+## Key Concepts
+- Tools are used by agents to interact with data and external systems
+- Each tool has defined inputs and outputs
+- Tools contain XanoScript logic
+- Can be shared across multiple agents
+- Support draft/publish workflow
+
+## Tool Design Best Practices
+- Clear, descriptive names (e.g., "lookup_customer", "send_email")
+- Well-defined input schemas
+- Specific, focused functionality
+- Good error handling`,
+    ai_hints: `- Create tools before creating agents that use them
+- Tool names should be descriptive verbs (lookup, create, update, send)
+- Keep tools focused on single responsibilities
+- Use \`include_xanoscript=true\` to see tool implementation
+- Tools can call other functions for code reuse`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/tool",
+            tool_name: "listTools",
+            description: "List all tools 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 tool name" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript code" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft versions" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/tool/{tool_id}",
+            tool_name: "getTool",
+            description: "Get details of a specific tool.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "tool_id", type: "integer", required: true, in: "path", description: "Tool 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}/tool",
+            tool_name: "createTool",
+            description: "Create a new tool for agents to use.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Tool name", required: true },
+                    description: { type: "string", description: "Tool description (shown to AI)" },
+                    xanoscript: { type: "string", description: "XanoScript tool definition", required: true }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/tool",
+                body: {
+                    name: "lookup_order",
+                    description: "Look up an order by order ID or customer email",
+                    xanoscript: `tool lookup_order {
+  input {
+    int order_id?
+    text email?
+  }
+  stack {
+    var $order {
+      value = db.orders.query()
+        .where("id", "=", $input.order_id)
+        .or("customer_email", "=", $input.email)
+        .first()
+    }
+  }
+  response = $order
+}`
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/tool/{tool_id}",
+            tool_name: "updateTool",
+            description: "Update an existing tool.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "tool_id", type: "integer", required: true, in: "path", description: "Tool ID" },
+                { name: "publish", type: "boolean", default: true, description: "Publish changes immediately" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Tool name" },
+                    description: { type: "string", description: "Tool description" },
+                    xanoscript: { type: "string", description: "XanoScript tool definition" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/tool/{tool_id}",
+            tool_name: "deleteTool",
+            description: "Delete a tool. Ensure no agents depend on it.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "tool_id", type: "integer", required: true, in: "path", description: "Tool ID" }
+            ]
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/tool/{tool_id}/security",
+            tool_name: "updateToolSecurity",
+            description: "Update security settings for the tool.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "tool_id", type: "integer", required: true, in: "path", description: "Tool ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    guid: { type: "string", description: "Security group GUID" }
+                }
+            }
+        }
+    ],
+    schemas: {
+        Tool: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                xanoscript: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["agent", "mcp_server", "function"]
+};

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

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

package/dist/meta_api_docs/topics/workflows.js

@@ -0,0 +1,131 @@
+export const workflowsDoc = {
+    topic: "workflows",
+    title: "Common Workflows",
+    description: `Step-by-step guides for common multi-step tasks using the Xano Meta API.
+
+## Quick Reference
+- **Create API Endpoint**: workspace → apigroup → api
+- **Create Database Table**: workspace → table → schema → index
+- **Set Up AI Agent**: tool → agent → (optional) mcp_server
+- **Deploy Changes**: draft → test → publish`,
+    ai_hints: `- Always start by listing existing resources
+- Use workspace context to understand current state
+- Create dependencies first (tables before APIs, tools before agents)
+- Test in development branch before production
+- Export backup before major changes`,
+    patterns: [
+        {
+            name: "Create a Complete REST API",
+            description: "Set up a table with CRUD endpoints",
+            steps: [
+                "1. `GET /workspace` - Find your workspace ID",
+                "2. `POST /workspace/{id}/table` - Create the database table",
+                "3. `POST /workspace/{id}/table/{id}/schema` - Add fields to the table",
+                "4. `POST /workspace/{id}/table/{id}/index` - Add indexes for query performance",
+                "5. `GET /workspace/{id}/apigroup` - Find or create an API group",
+                "6. `POST /workspace/{id}/apigroup/{id}/api` - Create GET (list) endpoint",
+                "7. `POST /workspace/{id}/apigroup/{id}/api` - Create GET (single) endpoint",
+                "8. `POST /workspace/{id}/apigroup/{id}/api` - Create POST endpoint",
+                "9. `POST /workspace/{id}/apigroup/{id}/api` - Create PUT endpoint",
+                "10. `POST /workspace/{id}/apigroup/{id}/api` - Create DELETE endpoint"
+            ],
+            example: `// Example: Create users table and list endpoint
+
+// 1. Create table
+POST /workspace/1/table
+{
+  "name": "users",
+  "xanoscript": "table users {\\n  id int [pk, auto]\\n  email text [unique]\\n  name text\\n  created_at timestamp [default:now]\\n}"
+}
+
+// 2. Create list endpoint
+POST /workspace/1/apigroup/1/api
+{
+  "name": "listUsers",
+  "path": "/users",
+  "verb": "GET",
+  "xanoscript": "query listUsers {\\n  response = db.users.query().all()\\n}"
+}`
+        },
+        {
+            name: "Set Up an AI Agent with Tools",
+            description: "Create tools and an agent that uses them",
+            steps: [
+                "1. `GET /workspace` - Find your workspace ID",
+                "2. `POST /workspace/{id}/tool` - Create first tool",
+                "3. `POST /workspace/{id}/tool` - Create additional tools as needed",
+                "4. `POST /workspace/{id}/agent` - Create agent with tool references",
+                "5. `POST /workspace/{id}/mcp_server` (optional) - Expose via MCP"
+            ],
+            example: `// 1. Create a lookup tool
+POST /workspace/1/tool
+{
+  "name": "lookup_customer",
+  "description": "Look up customer by email or ID",
+  "xanoscript": "tool lookup_customer {\\n  input { text email? int id? }\\n  response = db.customers.query().where('email', '=', $input.email).or('id', '=', $input.id).first()\\n}"
+}
+
+// 2. Create agent
+POST /workspace/1/agent
+{
+  "name": "support_bot",
+  "xanoscript": "agent support_bot {\\n  llm {\\n    type = \\"anthropic\\"\\n    model = \\"claude-4-sonnet-20250514\\"\\n    system_prompt = \\"You help customers with their orders.\\"\\n  }\\n  tools = [lookup_customer]\\n}"
+}`
+        },
+        {
+            name: "Deploy Function Changes Safely",
+            description: "Use draft/publish workflow for safe deployments",
+            steps: [
+                "1. `GET /workspace/{id}/function/{id}?include_xanoscript=true` - Get current function",
+                "2. `PUT /workspace/{id}/function/{id}?publish=false` - Save changes as draft",
+                "3. Test the draft version in development",
+                "4. `PUT /workspace/{id}/function/{id}?publish=true` - Publish to production"
+            ]
+        },
+        {
+            name: "Create a Scheduled Data Cleanup Task",
+            description: "Set up automated data maintenance",
+            steps: [
+                "1. `GET /workspace` - Find workspace ID",
+                "2. `POST /workspace/{id}/task` - Create the task with schedule",
+                "3. Monitor via `GET /workspace/{id}/task_history`"
+            ],
+            example: `POST /workspace/1/task
+{
+  "name": "cleanup_old_sessions",
+  "schedule": "0 3 * * *",
+  "active": true,
+  "xanoscript": "task cleanup_old_sessions {\\n  stack {\\n    db.sessions.query().where('created_at', '<', now() - 30.days).delete()\\n  }\\n}"
+}`
+        },
+        {
+            name: "Export and Import Workspace",
+            description: "Backup or migrate workspace data",
+            steps: [
+                "1. `POST /workspace/{id}/export` - Export complete workspace",
+                "2. Download the export file",
+                "3. `POST /workspace/{target_id}/import` - Import to target workspace"
+            ]
+        },
+        {
+            name: "Add Authentication to API Group",
+            description: "Secure API endpoints with authentication",
+            steps: [
+                "1. `GET /workspace/{id}/apigroup/{id}` - Get API group details",
+                "2. `PUT /workspace/{id}/apigroup/{id}/security` - Set security GUID",
+                "3. Individual endpoints inherit group security unless overridden"
+            ]
+        },
+        {
+            name: "Debug a Failing API Endpoint",
+            description: "Use history to troubleshoot issues",
+            steps: [
+                "1. `POST /workspace/{id}/request_history/search` - Search for failed requests",
+                "2. Filter by status: [400, 401, 403, 404, 500]",
+                "3. Use include_payload=true to see request/response details",
+                "4. `GET /workspace/{id}/apigroup/{id}/api/{id}?include_xanoscript=true` - Review endpoint code"
+            ]
+        }
+    ],
+    related_topics: ["start", "api", "table", "function", "agent"]
+};

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

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

package/dist/meta_api_docs/topics/workspace.js

@@ -0,0 +1,153 @@
+export const workspaceDoc = {
+    topic: "workspace",
+    title: "Workspace Management",
+    description: `Workspaces are the top-level container for all Xano resources. Each workspace contains databases, APIs, functions, tasks, agents, and more.
+
+## Key Operations
+- List/get workspaces
+- Export/import workspace data
+- Generate workspace context for AI
+- Get OpenAPI specifications
+- Convert between XanoScript and JSON`,
+    ai_hints: `- Use \`getWorkspaceContext\` first to understand workspace structure
+- Export before making major changes (backup)
+- Check branch before modifying (prod vs dev)
+- \`export-schema\` is lighter than \`export\` (schema only vs full data)
+- OpenAPI spec useful for understanding available endpoints`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace",
+            tool_name: "listWorkspaces",
+            description: "List all accessible workspaces with pagination and filtering.",
+            parameters: [
+                { name: "page", type: "integer", default: 1, description: "Page number" },
+                { name: "per_page", type: "integer", default: 50, description: "Items per page (max 10000)" },
+                { name: "search", type: "string", description: "Search by workspace name" },
+                { name: "sort", type: "string", enum: ["id", "name", "created_at"], default: "created_at", description: "Sort field" },
+                { name: "order", type: "string", enum: ["asc", "desc"], default: "desc", description: "Sort direction" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}",
+            tool_name: "getWorkspace",
+            description: "Get details of a specific workspace.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/export-schema",
+            tool_name: "exportWorkspaceSchema",
+            description: "Export database schemas and branch configuration only (lighter than full export).",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "password", type: "string", description: "Optional encryption password" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/export",
+            tool_name: "exportWorkspace",
+            description: "Export complete workspace data and configuration including APIs, functions, data.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "password", type: "string", description: "Optional encryption password" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/import",
+            tool_name: "importWorkspace",
+            description: "Import and restore workspace content from an export file.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "multipart/form-data",
+                properties: {
+                    file: { type: "file", description: "Export file to import", required: true },
+                    password: { type: "string", description: "Decryption password if encrypted" }
+                }
+            }
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/import-schema",
+            tool_name: "importWorkspaceSchema",
+            description: "Import database schema into a new branch.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "multipart/form-data",
+                properties: {
+                    file: { type: "file", description: "Schema export file", required: true },
+                    password: { type: "string", description: "Decryption password if encrypted" }
+                }
+            }
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/openapi",
+            tool_name: "getWorkspaceOpenAPI",
+            description: "Get OpenAPI v3 specification for all APIs in the workspace.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/context",
+            tool_name: "getWorkspaceContext",
+            description: "Generate complete workspace context map for AI agents. Essential for understanding workspace structure.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "format", type: "string", enum: ["json", "yaml"], default: "json", description: "Output format" },
+                { name: "user_descriptions", type: "boolean", default: false, description: "Include user-provided descriptions" },
+                { name: "ai_descriptions", type: "boolean", default: false, description: "Include AI-generated descriptions" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/convert/fromXS",
+            tool_name: "convertFromXanoScript",
+            description: "Convert XanoScript code to JSON format for programmatic manipulation.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "text/x-xanoscript",
+                description: "XanoScript code to convert"
+            }
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/convert/toXS",
+            tool_name: "convertToXanoScript",
+            description: "Convert JSON to XanoScript format for human-readable code.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                description: "JSON structure to convert to XanoScript"
+            }
+        }
+    ],
+    schemas: {
+        Workspace: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Unique workspace ID" },
+                name: { type: "string", description: "Workspace name" },
+                description: { type: "string", description: "Workspace description" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["apigroup", "table", "function", "branch"]
+};

package/dist/meta_api_docs/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type definitions for Xano Meta API documentation
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ParameterDoc {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description: string;
+    enum?: string[];
+    in?: "path" | "query" | "header";
+}
+export interface RequestBodyDoc {
+    type: string;
+    description?: string;
+    properties?: Record<string, {
+        type: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    example?: unknown;
+}
+export interface ResponseDoc {
+    type: string;
+    description?: string;
+    properties?: Record<string, unknown>;
+}
+export interface RequestExampleDoc {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export interface EndpointDoc {
+    method: HttpMethod;
+    path: string;
+    tool_name?: string;
+    description: string;
+    tags?: string[];
+    parameters?: ParameterDoc[];
+    request_body?: RequestBodyDoc;
+    response?: ResponseDoc;
+    example?: RequestExampleDoc;
+}
+export interface ExampleDoc {
+    title: string;
+    description: string;
+    request: {
+        method: string;
+        path: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    response?: unknown;
+}
+export interface PatternDoc {
+    name: string;
+    description?: string;
+    steps: string[];
+    example?: string;
+}
+export interface TopicDoc {
+    topic: string;
+    title: string;
+    description: string;
+    endpoints?: EndpointDoc[];
+    examples?: ExampleDoc[];
+    related_topics?: string[];
+    schemas?: Record<string, unknown>;
+    patterns?: PatternDoc[];
+    ai_hints?: string;
+}
+export type DetailLevel = "overview" | "detailed" | "examples";
+export interface MetaApiDocsArgs {
+    topic: string;
+    detail_level?: DetailLevel;
+    include_schemas?: boolean;
+}

package/dist/meta_api_docs/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Xano Meta API documentation
+ */
+export {};

package/dist/run_api_docs/format.d.ts

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