@xano/developer-mcp 1.0.0

package/api_docs/history.md

@@ -0,0 +1,263 @@
+# History & Audit Logs API
+
+View execution history and audit logs for various resources.
+
+## History Endpoints
+
+| Resource | List Endpoint | Search Endpoint |
+|----------|---------------|-----------------|
+| Request | `/workspace/{workspace_id}/request_history` | `.../request_history/search` |
+| Function | `/workspace/{workspace_id}/function_history` | `.../function_history/search` |
+| Task | `/workspace/{workspace_id}/task_history` | `.../task_history/search` |
+| Middleware | `/workspace/{workspace_id}/middleware_history` | `.../middleware_history/search` |
+| Tool | `/workspace/{workspace_id}/tool_history` | `.../tool_history/search` |
+| Trigger | `/workspace/{workspace_id}/trigger_history` | `.../trigger_history/search` |
+
+## Audit Log Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/audit_log` | Workspace audit logs |
+| GET | `/audit_log` | All audit logs (paid only) |
+| POST | `/workspace/{workspace_id}/audit_log/search` | Search workspace logs |
+| POST | `/audit_log/search` | Search all logs (paid only) |
+
+---
+
+# Request History
+
+## List Request History
+
+```
+GET /workspace/{workspace_id}/request_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `apigroup_id` | int | 0 | Filter by API group ID |
+| `query_id` | int | 0 | Filter by API endpoint ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Request History
+
+```
+POST /workspace/{workspace_id}/request_history/search
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `apigroup_id` | int | 0 | Filter by API group |
+| `query_id` | int | 0 | Filter by endpoint |
+| `search` | json | [] | Search filters |
+| `sort` | json | [] | Sort configuration |
+| `include_output` | bool | false | Include response output |
+
+---
+
+# Function History
+
+## List Function History
+
+```
+GET /workspace/{workspace_id}/function_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `function_id` | int | 0 | Filter by function ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Function History
+
+```
+POST /workspace/{workspace_id}/function_history/search
+```
+
+---
+
+# Task History
+
+## List Task History
+
+```
+GET /workspace/{workspace_id}/task_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `task_id` | int | 0 | Filter by task ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Task History
+
+```
+POST /workspace/{workspace_id}/task_history/search
+```
+
+---
+
+# Middleware History
+
+## List Middleware History
+
+```
+GET /workspace/{workspace_id}/middleware_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `middleware_id` | int | 0 | Filter by middleware ID |
+| `query_id` | int | 0 | Filter by API endpoint ID |
+| `function_id` | int | 0 | Filter by function ID |
+| `task_id` | int | 0 | Filter by task ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Middleware History
+
+```
+POST /workspace/{workspace_id}/middleware_history/search
+```
+
+---
+
+# Tool History
+
+## List Tool History
+
+```
+GET /workspace/{workspace_id}/tool_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `branch` | text | "" | Branch label |
+| `tool_id` | int | 0 | Filter by tool ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Tool History
+
+```
+POST /workspace/{workspace_id}/tool_history/search
+```
+
+---
+
+# Trigger History
+
+## List Trigger History
+
+```
+GET /workspace/{workspace_id}/trigger_history
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `trigger_id` | int | 0 | Filter by trigger ID |
+| `include_output` | bool | false | Include response output |
+
+## Search Trigger History
+
+```
+POST /workspace/{workspace_id}/trigger_history/search
+```
+
+---
+
+# Audit Logs
+
+## List Workspace Audit Logs
+
+```
+GET /workspace/{workspace_id}/audit_log
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `include_data` | bool | false | Include full log data |
+
+## List All Audit Logs
+
+```
+GET /audit_log
+```
+
+**Note:** Requires paid plan.
+
+Same parameters as workspace audit logs.
+
+## Search Workspace Audit Logs
+
+```
+POST /workspace/{workspace_id}/audit_log/search
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-500) |
+| `include_data` | bool | false | Include full log data |
+| `search` | json | [] | Search filters |
+| `sort` | json | [] | Sort configuration |
+
+## Search All Audit Logs
+
+```
+POST /audit_log/search
+```
+
+**Note:** Requires paid plan.
+
+---
+
+# Response Fields
+
+## History Entries
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | History entry ID |
+| `created_at` | timestamp | Execution timestamp |
+| `duration` | int | Execution duration in ms |
+| `status` | int | HTTP status code |
+| `input` | json | Request input |
+| `output` | json | Response output (if requested) |
+
+## Audit Log Entries
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | Log entry ID |
+| `created_at` | timestamp | Event timestamp |
+| `action` | text | Action performed |
+| `user` | object | User who performed action |
+| `data` | json | Additional event data (if requested) |

package/api_docs/index.md

@@ -0,0 +1,104 @@
+# Xano Headless API Documentation
+
+## How to Use This Documentation
+
+This documentation is accessed via the `api_docs` MCP tool. Use the `object` parameter to get detailed documentation for specific API resources.
+
+### Available Object Values
+
+| Object | Description |
+|--------|-------------|
+| `workspace` | Workspace management, branches, datasources, export/import, OpenAPI specs |
+| `table` | Database table schema management with XanoScript |
+| `api_group` | API groups and endpoints management |
+| `function` | Reusable function library |
+| `task` | Scheduled tasks (cron jobs) |
+| `middleware` | Request/response middleware |
+| `addon` | Reusable query addons for response transformation |
+| `agent` | AI agent configuration |
+| `tool` | AI tool definitions for agents |
+| `mcp_server` | Model Context Protocol server management |
+| `realtime` | Realtime WebSocket channels |
+| `triggers` | Event-driven triggers (table, workspace, agent, MCP, realtime) |
+| `file` | File uploads and static hosting |
+| `history` | Request history and audit logs |
+| `authentication` | User authentication and session info |
+
+### Example Usage
+
+```
+// Get overview (this document)
+api_docs()
+
+// Get specific documentation
+api_docs({ object: "table" })
+api_docs({ object: "api_group" })
+api_docs({ object: "function" })
+```
+
+---
+
+## API Overview
+
+The Xano Headless API uses **XanoScript** as the primary input/output format for most mutation operations.
+
+### Base URL
+All API endpoints are relative to your Xano instance's headless API base URL.
+
+### Content Types
+- **Mutations** (POST/PUT): `text/x-xanoscript`
+- **Responses**: `application/json`
+
+### Common Patterns
+
+#### Pagination
+```
+GET /resource?page=1&per_page=50
+```
+Response:
+```json
+{
+  "curPage": 1,
+  "nextPage": 2,
+  "prevPage": null,
+  "items": [...]
+}
+```
+
+#### Branch Targeting
+Most endpoints support `?branch=<label>` (empty = live branch)
+
+#### Sorting
+- `sort`: Field name (varies by endpoint)
+- `order`: `asc` or `desc`
+
+#### Search
+- `search`: Text search filter
+
+---
+
+## Resource Categories
+
+### Core Resources
+- **Workspace** - Container for all Xano resources
+- **Table** - Database tables with schema definitions
+- **API Group** - Groups of related API endpoints
+
+### Logic & Code
+- **Function** - Reusable code blocks
+- **Middleware** - Request/response processing
+- **Addon** - Response transformation queries
+- **Task** - Scheduled jobs
+
+### AI & Integrations
+- **Agent** - AI-powered assistants
+- **Tool** - Functions callable by AI agents
+- **MCP Server** - Model Context Protocol servers
+
+### Events & Realtime
+- **Triggers** - Event-driven automation
+- **Realtime** - WebSocket channels
+
+### Files & Observability
+- **File** - File storage and static hosting
+- **History** - Execution logs and audit trails

package/api_docs/mcp_server.md

@@ -0,0 +1,139 @@
+# MCP Server API
+
+MCP (Model Context Protocol) Servers provide a standardized way to expose tools and resources to AI models. They allow external AI applications to interact with your Xano workspace.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/mcp_server` | List MCP servers |
+| GET | `/workspace/{workspace_id}/mcp_server/{mcp_server_id}` | Get MCP server |
+| POST | `/workspace/{workspace_id}/mcp_server` | Create MCP server |
+| PUT | `/workspace/{workspace_id}/mcp_server/{mcp_server_id}` | Update MCP server |
+| DELETE | `/workspace/{workspace_id}/mcp_server/{mcp_server_id}` | Delete MCP server |
+| GET | `/mcp_server/documentation` | Get XanoScript documentation |
+
+---
+
+## List MCP Servers
+
+```
+GET /workspace/{workspace_id}/mcp_server
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+| `tools` | bool | true | Include tool information |
+
+---
+
+## Get MCP Server
+
+```
+GET /workspace/{workspace_id}/mcp_server/{mcp_server_id}
+```
+
+**Query Parameters:**
+- `tools` (bool, default: true): Include tool information
+
+Returns MCP server definition including XanoScript.
+
+---
+
+## Create MCP Server
+
+```
+POST /workspace/{workspace_id}/mcp_server
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+- `tools` (bool): Include tool information in response
+
+### XanoScript MCP Server Syntax
+
+```xanoscript
+mcp_server foo {
+  description = "test"
+  canonical = "custom"
+  tags = ["test"]
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | text | Human-readable description |
+| `canonical` | text | Unique canonical identifier |
+| `tags` | array | Tags for categorization |
+
+### Example: Data Access MCP Server
+
+```xanoscript
+mcp_server data_access {
+  description = "Provides read access to customer data"
+  canonical = "customer-data"
+  tags = ["data", "customer", "read-only"]
+}
+```
+
+### Example: Admin MCP Server
+
+```xanoscript
+mcp_server admin_tools {
+  description = "Administrative tools for workspace management"
+  canonical = "admin"
+  tags = ["admin", "management", "internal"]
+}
+```
+
+---
+
+## Update MCP Server
+
+```
+PUT /workspace/{workspace_id}/mcp_server/{mcp_server_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+- `tools` (bool, default: true): Include tool information in response
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete MCP Server
+
+```
+DELETE /workspace/{workspace_id}/mcp_server/{mcp_server_id}
+```
+
+**Warning:** This action cannot be undone.
+
+---
+
+## Get MCP Documentation
+
+```
+GET /mcp_server/documentation
+```
+
+Provides comprehensive XanoScript syntax documentation.
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `type` | text | "start" | Documentation type/section |
+
+This endpoint is useful for AI models to learn XanoScript syntax dynamically.

package/api_docs/middleware.md

@@ -0,0 +1,205 @@
+# Middleware API
+
+Middleware are reusable code blocks that run before or after API endpoints. They add common functionality like authentication, logging, or request/response transformation.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/middleware` | List middlewares |
+| GET | `/workspace/{workspace_id}/middleware/{middleware_id}` | Get middleware |
+| POST | `/workspace/{workspace_id}/middleware` | Create middleware |
+| PUT | `/workspace/{workspace_id}/middleware/{middleware_id}` | Update middleware |
+| DELETE | `/workspace/{workspace_id}/middleware/{middleware_id}` | Delete middleware |
+| PUT | `/workspace/{workspace_id}/middleware/{middleware_id}/security` | Update security |
+
+---
+
+## List Middlewares
+
+```
+GET /workspace/{workspace_id}/middleware
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+
+---
+
+## Get Middleware
+
+```
+GET /workspace/{workspace_id}/middleware/{middleware_id}
+```
+
+Returns middleware definition including XanoScript.
+
+---
+
+## Create Middleware
+
+```
+POST /workspace/{workspace_id}/middleware
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+
+### XanoScript Middleware Syntax
+
+Middleware follows the same syntax as functions:
+
+```xanoscript
+middleware foo {
+  input {
+    int score
+  }
+
+  stack {
+    var $x1 {
+      value = $input.score + 1
+    }
+  }
+
+  response = $x1
+}
+```
+
+### Common Use Cases
+
+#### Authentication Check
+
+```xanoscript
+middleware auth_check {
+  input {
+    text token?
+  }
+
+  stack {
+    // Validate token
+    if $input.token == null {
+      precondition.abort {
+        status = 401
+        message = "Unauthorized"
+      }
+    }
+
+    // Decode and verify token
+    var $user {
+      value = decode_jwt($input.token)
+    }
+  }
+
+  response = $user
+}
+```
+
+#### Request Logging
+
+```xanoscript
+middleware request_logger {
+  input {
+    text endpoint
+    json body?
+  }
+
+  stack {
+    db.insert request_log {
+      data = {
+        endpoint: $input.endpoint,
+        body: $input.body,
+        timestamp: now()
+      }
+    }
+  }
+
+  response = true
+}
+```
+
+#### Rate Limiting
+
+```xanoscript
+middleware rate_limit {
+  input {
+    text client_ip
+  }
+
+  stack {
+    // Count recent requests
+    db.query rate_limit {
+      where = $db.rate_limit.ip == $input.client_ip
+        && $db.rate_limit.timestamp > now() - 60
+      return = {type: "count"}
+    }
+
+    if $rate_limit > 100 {
+      precondition.abort {
+        status = 429
+        message = "Too many requests"
+      }
+    }
+
+    // Log this request
+    db.insert rate_limit {
+      data = {ip: $input.client_ip, timestamp: now()}
+    }
+  }
+
+  response = true
+}
+```
+
+### Use Cases
+
+- Authentication and authorization
+- Request logging
+- Rate limiting
+- Request/response transformation
+- Error handling
+- CORS headers
+
+---
+
+## Update Middleware
+
+```
+PUT /workspace/{workspace_id}/middleware/{middleware_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete Middleware
+
+```
+DELETE /workspace/{workspace_id}/middleware/{middleware_id}
+```
+
+**Warning:** This action cannot be undone. Any API groups using this middleware will no longer have it applied.
+
+---
+
+## Update Middleware Security
+
+```
+PUT /workspace/{workspace_id}/middleware/{middleware_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |