@xano/developer-mcp 1.0.0

package/api_docs/realtime.md

@@ -0,0 +1,153 @@
+# Realtime API
+
+Realtime channels enable real-time bidirectional communication between clients using WebSockets. They support features like presence, message history, and private messaging.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/realtime/channel` | List channels |
+| GET | `/workspace/{workspace_id}/realtime/channel/{channel_id}` | Get channel |
+| POST | `/workspace/{workspace_id}/realtime/channel` | Create channel |
+| PUT | `/workspace/{workspace_id}/realtime/channel/{channel_id}` | Update channel |
+| DELETE | `/workspace/{workspace_id}/realtime/channel/{channel_id}` | Delete channel |
+
+---
+
+## List Realtime Channels
+
+```
+GET /workspace/{workspace_id}/realtime/channel
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "name" | Sort field: "name" |
+| `order` | enum | "desc" | Sort order |
+
+---
+
+## Get Realtime Channel
+
+```
+GET /workspace/{workspace_id}/realtime/channel/{channel_id}
+```
+
+Returns channel definition including XanoScript.
+
+---
+
+## Create Realtime Channel
+
+```
+POST /workspace/{workspace_id}/realtime/channel
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+### XanoScript Realtime Channel Syntax
+
+```xanoscript
+realtime_channel foo {
+  public_messaging = {active: false}
+  private_messaging = {active: false}
+  settings = {
+    anonymous_clients: false
+    nested_channels  : false
+    message_history  : 0
+    auth_channel     : false
+    presence         : false
+  }
+}
+```
+
+### Messaging Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `public_messaging` | object | Configure public message broadcasting |
+| `private_messaging` | object | Configure private direct messages |
+
+### Settings
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `anonymous_clients` | bool | Allow connections without authentication |
+| `nested_channels` | bool | Allow sub-channels (e.g., `chat/room1`) |
+| `message_history` | int | Messages to keep in history (0 = disabled) |
+| `auth_channel` | bool | Require authentication for channel access |
+| `presence` | bool | Track online/offline status of users |
+
+### Example: Chat Room Channel
+
+```xanoscript
+realtime_channel chat {
+  public_messaging = {active: true}
+  private_messaging = {active: true}
+  settings = {
+    anonymous_clients: false
+    nested_channels  : true
+    message_history  : 100
+    auth_channel     : true
+    presence         : true
+  }
+}
+```
+
+### Example: Notifications Channel
+
+```xanoscript
+realtime_channel notifications {
+  public_messaging = {active: true}
+  private_messaging = {active: false}
+  settings = {
+    anonymous_clients: false
+    nested_channels  : false
+    message_history  : 50
+    auth_channel     : true
+    presence         : false
+  }
+}
+```
+
+### Example: Public Broadcast Channel
+
+```xanoscript
+realtime_channel announcements {
+  public_messaging = {active: true}
+  private_messaging = {active: false}
+  settings = {
+    anonymous_clients: true
+    nested_channels  : false
+    message_history  : 10
+    auth_channel     : false
+    presence         : false
+  }
+}
+```
+
+---
+
+## Update Realtime Channel
+
+```
+PUT /workspace/{workspace_id}/realtime/channel/{channel_id}
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+Send complete channel definition.
+
+---
+
+## Delete Realtime Channel
+
+```
+DELETE /workspace/{workspace_id}/realtime/channel/{channel_id}
+```
+
+**Warning:** This action cannot be undone. All connected clients will be disconnected.

package/api_docs/table.md

@@ -0,0 +1,151 @@
+# Table API
+
+Tables are database objects that store structured data. Tables are defined using XanoScript with schema definitions, indexes, and constraints.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/table` | List all tables |
+| GET | `/workspace/{workspace_id}/table/{table_id}` | Get table details |
+| POST | `/workspace/{workspace_id}/table` | Create table |
+| PUT | `/workspace/{workspace_id}/table/{table_id}` | Update table |
+| DELETE | `/workspace/{workspace_id}/table/{table_id}` | Delete table |
+
+---
+
+## List Tables
+
+```
+GET /workspace/{workspace_id}/table
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "name" | Sort: "created_at", "updated_at", "name" |
+| `order` | enum | "asc" | Sort order: "asc", "desc" |
+
+---
+
+## Get Table
+
+```
+GET /workspace/{workspace_id}/table/{table_id}
+```
+
+Returns table definition including schema, indexes, and XanoScript.
+
+---
+
+## Create Table
+
+```
+POST /workspace/{workspace_id}/table
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+### XanoScript Table Syntax
+
+```xanoscript
+table book {
+  schema {
+    int id
+    text title
+    text description
+  }
+
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+}
+```
+
+### Schema Field Types
+
+| Type | Description |
+|------|-------------|
+| `int` | Integer |
+| `text` | Text/string |
+| `bool` | Boolean |
+| `float` | Floating point number |
+| `timestamp` | Timestamp/datetime |
+| `date` | Date only |
+| `time` | Time only |
+| `json` | JSON object |
+| `uuid` | UUID string |
+| `enum` | Enumerated values |
+| `object` | Nested object |
+| `object[]` | Array of objects |
+
+### Field Modifiers
+
+| Modifier | Syntax | Description |
+|----------|--------|-------------|
+| Optional | `field_name?` | Nullable field |
+| Default | `default = value` | Default value |
+
+### Index Types
+
+| Type | Description |
+|------|-------------|
+| `primary` | Primary key index |
+| `unique` | Unique constraint |
+| `index` | Regular index |
+| `fulltext` | Full-text search index |
+
+### Complete Example
+
+```xanoscript
+table user {
+  schema {
+    int id
+    text email
+    text password
+    text name?
+    timestamp created_at
+    bool active default = true
+    enum role {
+      values = ["admin", "user", "guest"]
+      default = "user"
+    }
+  }
+
+  index = [
+    {type: "primary", field: [{name: "id"}]},
+    {type: "unique", field: [{name: "email"}]},
+    {type: "index", field: [{name: "created_at"}]}
+  ]
+}
+```
+
+---
+
+## Update Table
+
+```
+PUT /workspace/{workspace_id}/table/{table_id}
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+Send complete table definition with updated schema.
+
+**Notes:**
+- Schema changes may trigger database migrations
+- Removing fields or changing types may result in data loss
+- Adding new fields typically requires default values for existing rows
+
+---
+
+## Delete Table
+
+```
+DELETE /workspace/{workspace_id}/table/{table_id}
+```
+
+**Warning:** This action cannot be undone. All data in the table will be permanently deleted.

package/api_docs/task.md

@@ -0,0 +1,191 @@
+# Task API
+
+Tasks are scheduled jobs that run automatically based on a cron-like schedule. They are defined using XanoScript.
+
+**Note:** Task functionality is restricted to paid accounts.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/task` | List tasks |
+| GET | `/workspace/{workspace_id}/task/{task_id}` | Get task |
+| POST | `/workspace/{workspace_id}/task` | Create task |
+| PUT | `/workspace/{workspace_id}/task/{task_id}` | Update task |
+| DELETE | `/workspace/{workspace_id}/task/{task_id}` | Delete task |
+| PUT | `/workspace/{workspace_id}/task/{task_id}/security` | Update security |
+
+---
+
+## List Tasks
+
+```
+GET /workspace/{workspace_id}/task
+```
+
+**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 Task
+
+```
+GET /workspace/{workspace_id}/task/{task_id}
+```
+
+Returns task definition including schedule and XanoScript.
+
+---
+
+## Create Task
+
+```
+POST /workspace/{workspace_id}/task
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+
+### XanoScript Task Syntax
+
+```xanoscript
+task foo {
+  stack {
+    var $x1 {
+      value = 1
+    }
+  }
+
+  schedule = [{starts_on: 2025-10-28 18:03:58+0000, freq: 900}]
+}
+```
+
+### Stack Section
+
+The task logic (same syntax as functions):
+
+```xanoscript
+stack {
+  db.query user {
+    where = $db.user.active == false
+    return = {type: "list"}
+  }
+
+  foreach $user as $u {
+    // Process each user
+  }
+}
+```
+
+### Schedule Section
+
+#### Inline Format
+```xanoscript
+schedule = [{
+  starts_on: 2025-10-28 18:03:58+0000,
+  freq: 900
+}]
+```
+
+#### Block Format
+```xanoscript
+schedule {
+  events = [{
+    starts_on: 2025-07-25 20:00:12+0000,
+    freq: 900
+  }]
+}
+```
+
+### Schedule Options
+
+| Field | Description |
+|-------|-------------|
+| `starts_on` | ISO timestamp when schedule begins |
+| `freq` | Frequency in seconds between runs |
+
+### Common Frequencies
+
+| Seconds | Interval |
+|---------|----------|
+| 60 | Every minute |
+| 300 | Every 5 minutes |
+| 900 | Every 15 minutes |
+| 3600 | Every hour |
+| 86400 | Every day |
+
+### Complete Example
+
+```xanoscript
+task cleanup_expired_sessions {
+  stack {
+    // Find expired sessions
+    db.query session {
+      where = $db.session.expires_at < now()
+      return = {type: "list"}
+    }
+
+    // Delete each expired session
+    foreach $session as $s {
+      db.delete session {
+        where = $db.session.id == $s.id
+      }
+    }
+
+    var $deleted_count {
+      value = count($session)
+    }
+  }
+
+  schedule = [{
+    starts_on: 2025-01-01 00:00:00+0000,
+    freq: 3600
+  }]
+}
+```
+
+---
+
+## Update Task
+
+```
+PUT /workspace/{workspace_id}/task/{task_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete Task
+
+```
+DELETE /workspace/{workspace_id}/task/{task_id}
+```
+
+**Warning:** This action cannot be undone.
+
+---
+
+## Update Task Security
+
+```
+PUT /workspace/{workspace_id}/task/{task_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |

package/api_docs/tool.md

@@ -0,0 +1,216 @@
+# Tool API
+
+Tools are functions that AI agents can call to perform actions. They extend agent capabilities by allowing them to interact with databases, external APIs, and perform computations.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/tool` | List tools |
+| GET | `/workspace/{workspace_id}/tool/{tool_id}` | Get tool |
+| POST | `/workspace/{workspace_id}/tool` | Create tool |
+| PUT | `/workspace/{workspace_id}/tool/{tool_id}` | Update tool |
+| DELETE | `/workspace/{workspace_id}/tool/{tool_id}` | Delete tool |
+| PUT | `/workspace/{workspace_id}/tool/{tool_id}/security` | Update security |
+
+---
+
+## List Tools
+
+```
+GET /workspace/{workspace_id}/tool
+```
+
+**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 Tool
+
+```
+GET /workspace/{workspace_id}/tool/{tool_id}
+```
+
+Returns tool definition including XanoScript.
+
+---
+
+## Create Tool
+
+```
+POST /workspace/{workspace_id}/tool
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+
+### XanoScript Tool Syntax
+
+Tools follow the same syntax as functions, with input, stack, and response sections:
+
+```xanoscript
+tool foo {
+  input {
+    int score
+  }
+
+  stack {
+    var $x1 {
+      value = $input.score + 1
+    }
+  }
+
+  response = $x1
+}
+```
+
+### Input Section
+
+Define parameters the agent can pass to the tool. Include descriptions for AI understanding:
+
+```xanoscript
+input {
+  text user_id {
+    description = "The user's unique identifier"
+  }
+  text query {
+    description = "Search query string"
+  }
+}
+```
+
+### Stack Section
+
+The logic that executes when the tool is called:
+
+```xanoscript
+stack {
+  db.query user {
+    where = $db.user.id == $input.user_id
+    return = {type: "single"}
+  }
+}
+```
+
+### Example: Database Lookup Tool
+
+```xanoscript
+tool get_user_orders {
+  input {
+    int user_id {
+      description = "The ID of the user to look up orders for"
+    }
+    int limit? {
+      description = "Maximum number of orders to return"
+      default = 10
+    }
+  }
+
+  stack {
+    db.query order {
+      where = $db.order.user_id == $input.user_id
+      limit = $input.limit
+      order = {created_at: "desc"}
+      return = {type: "list"}
+    }
+  }
+
+  response = $order
+}
+```
+
+### Example: External API Tool
+
+```xanoscript
+tool search_products {
+  input {
+    text query {
+      description = "Product search query"
+    }
+  }
+
+  stack {
+    external.api_call {
+      url = "https://api.example.com/search"
+      method = "GET"
+      params = {q: $input.query}
+    }
+  }
+
+  response = $api_result
+}
+```
+
+### Example: Data Processing Tool
+
+```xanoscript
+tool calculate_statistics {
+  input {
+    int[] values {
+      description = "Array of numbers to analyze"
+    }
+  }
+
+  stack {
+    var $sum { value = sum($input.values) }
+    var $count { value = count($input.values) }
+    var $avg { value = $sum / $count }
+    var $min { value = min($input.values) }
+    var $max { value = max($input.values) }
+  }
+
+  response = {
+    sum: $sum,
+    count: $count,
+    average: $avg,
+    min: $min,
+    max: $max
+  }
+}
+```
+
+---
+
+## Update Tool
+
+```
+PUT /workspace/{workspace_id}/tool/{tool_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete Tool
+
+```
+DELETE /workspace/{workspace_id}/tool/{tool_id}
+```
+
+**Warning:** This action cannot be undone. Any agents using this tool will no longer have access to it.
+
+---
+
+## Update Tool Security
+
+```
+PUT /workspace/{workspace_id}/tool/{tool_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |