@xano/developer-mcp 1.0.27 → 1.0.28

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

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

package/dist/api_docs/topics/mcp_server.js

@@ -0,0 +1,139 @@
+export const mcpServerDoc = {
+    topic: "mcp_server",
+    title: "MCP Server Management",
+    description: `MCP (Model Context Protocol) Servers expose tools to external AI clients like Claude Desktop, Cursor, or other MCP-compatible applications.
+
+## Key Concepts
+- MCP Servers expose Xano tools via the MCP protocol
+- External AI clients can discover and call these tools
+- Supports authentication for secure access
+- Can have triggers for event-driven invocation
+- Standardized interface for AI tool discovery
+
+## Use Cases
+- Expose Xano functionality to Claude Desktop
+- Integrate with AI IDEs like Cursor
+- Build custom AI assistants with Xano backend
+- Provide tools to any MCP-compatible client`,
+    ai_hints: `- MCP Servers expose existing tools to external clients
+- Create tools first, then create MCP server to expose them
+- Authentication settings control who can access the server
+- Use triggers to invoke actions when MCP events occur
+- Check documentation endpoint for client setup instructions`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/mcp_server",
+            tool_name: "listMcpServers",
+            description: "List all MCP servers 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 name" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/mcp_server/{mcp_server_id}",
+            tool_name: "getMcpServer",
+            description: "Get details of a specific MCP server.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "mcp_server_id", type: "integer", required: true, in: "path", description: "MCP Server ID" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/mcp_server",
+            tool_name: "createMcpServer",
+            description: "Create a new MCP server to expose tools.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "MCP server name", required: true },
+                    description: { type: "string", description: "MCP server description" },
+                    xanoscript: { type: "string", description: "XanoScript MCP server definition", required: true }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/mcp_server",
+                body: {
+                    name: "my_tools",
+                    description: "MCP server exposing customer support tools",
+                    xanoscript: `mcp_server my_tools {
+  tools = [lookup_order, update_ticket, send_notification]
+  authentication {
+    type = "bearer"
+    token = env.MCP_TOKEN
+  }
+}`
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/mcp_server/{mcp_server_id}",
+            tool_name: "updateMcpServer",
+            description: "Update an existing MCP server.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "mcp_server_id", type: "integer", required: true, in: "path", description: "MCP Server ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "MCP server name" },
+                    description: { type: "string", description: "MCP server description" },
+                    xanoscript: { type: "string", description: "XanoScript MCP server definition" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/mcp_server/{mcp_server_id}",
+            tool_name: "deleteMcpServer",
+            description: "Delete an MCP server.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "mcp_server_id", type: "integer", required: true, in: "path", description: "MCP Server ID" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/mcp_server/documentation",
+            tool_name: "getMcpDocumentation",
+            description: "Get MCP documentation for setup and syntax reference.",
+            parameters: [
+                { name: "type", type: "string", enum: ["start", "api", "function", "task", "mcp", "agent", "tool", "fs-syntax", "table", "database"], description: "Documentation type to retrieve" }
+            ]
+        }
+    ],
+    schemas: {
+        McpServer: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                tools: { type: "array", items: { type: "string" } },
+                authentication: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", enum: ["none", "bearer", "basic"] },
+                        token: { type: "string" }
+                    }
+                },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["tool", "agent", "authentication"]
+};

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

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

package/dist/api_docs/topics/middleware.js

@@ -0,0 +1,156 @@
+export const middlewareDoc = {
+    topic: "middleware",
+    title: "Middleware Management",
+    description: `Middleware are request/response interceptors that run before or after API endpoints. They handle cross-cutting concerns like authentication, logging, rate limiting, and request transformation.
+
+## Key Concepts
+- Middleware runs before (pre) or after (post) API endpoints
+- Can modify requests, responses, or halt execution
+- Used for: auth validation, logging, rate limiting, CORS, etc.
+- Can be applied to specific endpoints or entire API groups
+- Support draft/publish workflow
+
+## Common Middleware Patterns
+- Authentication/authorization checks
+- Request logging and timing
+- Rate limiting
+- Request/response transformation
+- CORS handling
+- Input validation`,
+    ai_hints: `- Middleware runs on every matching request - keep it fast
+- Pre-middleware can halt execution (auth checks)
+- Post-middleware can transform responses
+- Check existing middleware before creating duplicates
+- Security settings control which endpoints use the middleware`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/middleware",
+            tool_name: "listMiddlewares",
+            description: "List all middleware 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 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}/middleware/{middleware_id}",
+            tool_name: "getMiddleware",
+            description: "Get details of a specific middleware.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "middleware_id", type: "integer", required: true, in: "path", description: "Middleware 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}/middleware",
+            tool_name: "createMiddleware",
+            description: "Create a new middleware.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Middleware name", required: true },
+                    description: { type: "string", description: "Middleware description" },
+                    type: { type: "string", description: "pre or post", required: true },
+                    xanoscript: { type: "string", description: "XanoScript middleware definition", required: true }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/middleware",
+                body: {
+                    name: "rate_limiter",
+                    description: "Limit requests to 100 per minute per IP",
+                    type: "pre",
+                    xanoscript: `middleware rate_limiter {
+  stack {
+    var $key {
+      value = "ratelimit:" + $request.ip
+    }
+    var $count {
+      value = redis.incr($key)
+    }
+    if ($count == 1) {
+      redis.expire($key, 60)
+    }
+    if ($count > 100) {
+      throw(429, "Rate limit exceeded")
+    }
+  }
+}`
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/middleware/{middleware_id}",
+            tool_name: "updateMiddleware",
+            description: "Update an existing middleware.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "middleware_id", type: "integer", required: true, in: "path", description: "Middleware ID" },
+                { name: "publish", type: "boolean", default: true, description: "Publish changes immediately" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Middleware name" },
+                    description: { type: "string", description: "Middleware description" },
+                    xanoscript: { type: "string", description: "XanoScript middleware definition" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/middleware/{middleware_id}",
+            tool_name: "deleteMiddleware",
+            description: "Delete a middleware.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "middleware_id", type: "integer", required: true, in: "path", description: "Middleware ID" }
+            ]
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/middleware/{middleware_id}/security",
+            tool_name: "updateMiddlewareSecurity",
+            description: "Update security settings for the middleware.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "middleware_id", type: "integer", required: true, in: "path", description: "Middleware ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    guid: { type: "string", description: "Security group GUID" }
+                }
+            }
+        }
+    ],
+    schemas: {
+        Middleware: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                type: { type: "string", enum: ["pre", "post"] },
+                xanoscript: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["api", "apigroup", "authentication"]
+};

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

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

package/dist/api_docs/topics/realtime.js

@@ -0,0 +1,112 @@
+export const realtimeDoc = {
+    topic: "realtime",
+    title: "Realtime Channel Management",
+    description: `Realtime channels enable WebSocket-based push notifications and live updates to connected clients.
+
+## Key Concepts
+- Channels are WebSocket endpoints for real-time communication
+- Clients subscribe to channels to receive updates
+- Server can publish messages to channels
+- Triggers can respond to channel events
+- Useful for chat, notifications, live updates
+
+## Common Use Cases
+- Live chat applications
+- Real-time notifications
+- Live dashboards
+- Collaborative editing
+- Push updates to mobile apps`,
+    ai_hints: `- Create channels for different message types (chat, notifications, etc.)
+- Use triggers to respond to channel events (subscribe, message, etc.)
+- Channels require authenticated connections for security
+- Consider rate limiting for high-traffic channels
+- Test with WebSocket clients before production`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/realtime/channel",
+            tool_name: "listRealtimeChannels",
+            description: "List all realtime channels 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 channel name" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/realtime/channel/{channel_id}",
+            tool_name: "getRealtimeChannel",
+            description: "Get details of a specific realtime channel.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "channel_id", type: "integer", required: true, in: "path", description: "Channel ID" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/realtime/channel",
+            tool_name: "createRealtimeChannel",
+            description: "Create a new realtime channel.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Channel name", required: true },
+                    description: { type: "string", description: "Channel description" }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/realtime/channel",
+                body: {
+                    name: "notifications",
+                    description: "User notification channel"
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/realtime/channel/{channel_id}",
+            tool_name: "updateRealtimeChannel",
+            description: "Update an existing realtime channel.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "channel_id", type: "integer", required: true, in: "path", description: "Channel ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Channel name" },
+                    description: { type: "string", description: "Channel description" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/realtime/channel/{channel_id}",
+            tool_name: "deleteRealtimeChannel",
+            description: "Delete a realtime channel.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "channel_id", type: "integer", required: true, in: "path", description: "Channel ID" }
+            ]
+        }
+    ],
+    schemas: {
+        RealtimeChannel: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["api", "function"]
+};

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

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

package/dist/api_docs/topics/start.js

@@ -0,0 +1,107 @@
+export const startDoc = {
+    topic: "start",
+    title: "Xano Meta API - Getting Started",
+    description: `The Xano Meta API provides programmatic access to manage your Xano instance. Use it to create, modify, and manage workspaces, databases, APIs, functions, scheduled tasks, AI agents, and more.
+
+## Base URL
+\`\`\`
+https://<your-instance-subdomain>.xano.io/api:meta/<endpoint>
+\`\`\`
+
+**Example:** If your Xano instance is \`https://x8ki-letl-twmt.n7.xano.io\`, the full URL to list workspaces would be:
+\`\`\`
+https://x8ki-letl-twmt.n7.xano.io/api:meta/workspace
+\`\`\`
+
+Your instance URL can be found in the Xano dashboard URL or in your API endpoint URLs.
+
+## Authentication
+Include your Access Token in the Authorization header:
+\`\`\`
+Authorization: Bearer <your-access-token>
+\`\`\`
+
+Access tokens are created in the Xano dashboard under Settings > Access Tokens.
+
+## Quick Start
+1. **Get your workspaces:** \`GET /workspace\`
+2. **List tables in a workspace:** \`GET /workspace/{id}/table\`
+3. **Create an API endpoint:** \`POST /workspace/{id}/apigroup/{id}/api\`
+
+## Resource Hierarchy
+\`\`\`
+workspace/
+  ├── apigroup/         # API groups (REST endpoint collections)
+  │   └── api/          # Individual endpoints
+  ├── table/            # Database tables
+  │   ├── schema/       # Table schema definitions
+  │   ├── index/        # Database indexes
+  │   └── trigger/      # Table triggers
+  ├── function/         # Reusable functions
+  ├── task/             # Scheduled tasks
+  ├── agent/            # AI agents
+  │   └── trigger/      # Agent triggers
+  ├── tool/             # Agent tools
+  ├── mcp_server/       # MCP servers
+  │   └── trigger/      # MCP triggers
+  ├── middleware/       # Request interceptors
+  ├── realtime/         # WebSocket channels
+  │   └── trigger/      # Realtime triggers
+  ├── branch/           # Environment branches
+  └── file/             # File storage
+\`\`\`
+
+## Common Parameters
+Most list endpoints support:
+- \`page\`: Page number (default: 1)
+- \`per_page\`: Items per page (default: 50, max: 10000)
+- \`search\`: Search by name
+- \`sort\`: Sort field (usually: id, name, created_at)
+- \`order\`: Sort direction (asc, desc)
+- \`branch\`: Filter by branch name
+
+## XanoScript Integration
+Many endpoints accept XanoScript code for logic definition:
+- Use \`include_xanoscript=true\` to get code in responses
+- POST/PUT bodies can include XanoScript directly
+- Use \`/convert/fromXS\` and \`/convert/toXS\` for format conversion`,
+    ai_hints: `- Start by calling \`GET /workspace\` to get workspace IDs
+- Use \`GET /workspace/{id}/context\` to get a full workspace map for AI understanding
+- Always check existing resources before creating new ones
+- Use \`include_xanoscript=true\` to see implementation details
+- Draft/publish workflow: changes are drafts until published`,
+    related_topics: ["authentication", "workspace", "workflows"],
+    examples: [
+        {
+            title: "List all workspaces",
+            description: "Get a list of all accessible workspaces",
+            request: {
+                method: "GET",
+                path: "/workspace",
+                headers: { "Authorization": "Bearer <token>" }
+            },
+            response: {
+                curPage: 1,
+                nextPage: null,
+                prevPage: null,
+                items: [
+                    { id: 1, name: "My App", description: "Production workspace" }
+                ]
+            }
+        },
+        {
+            title: "Get workspace context for AI",
+            description: "Generate complete workspace context for AI agents",
+            request: {
+                method: "GET",
+                path: "/workspace/1/context?format=json",
+                headers: { "Authorization": "Bearer <token>" }
+            },
+            response: {
+                tables: ["users", "posts", "comments"],
+                api_groups: [{ name: "public", endpoints: 12 }],
+                functions: ["auth_check", "send_email"]
+            }
+        }
+    ]
+};

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

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