@xano/developer-mcp 1.0.0

package/api_docs/triggers.md

@@ -0,0 +1,344 @@
+# Triggers API
+
+Triggers are event-driven functions that execute automatically in response to specific events.
+
+## Trigger Types
+
+| Type | Description |
+|------|-------------|
+| Table Triggers | Respond to database events (insert, update, delete) |
+| Workspace Triggers | Respond to branch events (merge, set live, create) |
+| Agent Triggers | Extend agent functionality with custom hooks |
+| MCP Server Triggers | Extend MCP server functionality |
+| Realtime Triggers | Respond to realtime channel events |
+
+---
+
+# Table Triggers
+
+Execute code when database records are created, updated, or deleted.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/table/trigger` | List triggers |
+| GET | `/workspace/{workspace_id}/table/trigger/{trigger_id}` | Get trigger |
+| POST | `/workspace/{workspace_id}/table/trigger` | Create trigger |
+| PUT | `/workspace/{workspace_id}/table/trigger/{trigger_id}` | Update trigger |
+| DELETE | `/workspace/{workspace_id}/table/trigger/{trigger_id}` | Delete trigger |
+| PUT | `/workspace/{workspace_id}/table/trigger/{trigger_id}/security` | Update security |
+
+## XanoScript Syntax
+
+```xanoscript
+table_trigger foo {
+  table = "user"
+  input {
+    json new
+    json old
+    enum action {
+      values = ["insert", "update", "delete", "truncate"]
+    }
+    text datasource
+  }
+
+  stack {
+    var $x1 {
+      value = $input.score + 1
+    }
+  }
+
+  actions = {insert: true, update: true}
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `table` | text | Name of the table to watch |
+| `actions` | object | Which events trigger execution |
+
+### Available Actions
+
+| Action | Description |
+|--------|-------------|
+| `insert` | New record created |
+| `update` | Record modified |
+| `delete` | Record deleted |
+| `truncate` | Table truncated |
+
+### Input Variables
+
+The trigger receives these inputs automatically:
+
+| Variable | Description |
+|----------|-------------|
+| `$input.new` | New record data (insert/update) |
+| `$input.old` | Previous record data (update/delete) |
+| `$input.action` | The action type |
+| `$input.datasource` | The datasource that triggered the event |
+
+### Example: Audit Log Trigger
+
+```xanoscript
+table_trigger user_audit {
+  table = "user"
+  input {
+    json new
+    json old
+    enum action { values = ["insert", "update", "delete", "truncate"] }
+    text datasource
+  }
+
+  stack {
+    db.insert audit_log {
+      data = {
+        table: "user",
+        action: $input.action,
+        old_data: $input.old,
+        new_data: $input.new,
+        timestamp: now()
+      }
+    }
+  }
+
+  actions = {insert: true, update: true, delete: true}
+}
+```
+
+---
+
+# Workspace Triggers
+
+Execute code when workspace branch events occur.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/trigger` | List triggers |
+| GET | `/workspace/{workspace_id}/trigger/{trigger_id}` | Get trigger |
+| POST | `/workspace/{workspace_id}/trigger` | Create trigger |
+| PUT | `/workspace/{workspace_id}/trigger/{trigger_id}` | Update trigger |
+| DELETE | `/workspace/{workspace_id}/trigger/{trigger_id}` | Delete trigger |
+
+## XanoScript Syntax
+
+```xanoscript
+workspace_trigger foo {
+  input {
+    object to_branch? {
+      schema {
+        int id?
+        text label? filters=trim
+      }
+    }
+    object from_branch? {
+      schema {
+        int id?
+        text label? filters=trim
+      }
+    }
+    enum action {
+      values = ["branch_live", "branch_merge", "branch_new"]
+    }
+  }
+
+  stack {
+    // Your logic here
+  }
+
+  actions = {branch_live: true, branch_merge: true, branch_new: true}
+}
+```
+
+### Available Actions
+
+| Action | Description |
+|--------|-------------|
+| `branch_live` | Branch set as live |
+| `branch_merge` | Branches merged |
+| `branch_new` | New branch created |
+
+---
+
+# Agent Triggers
+
+Extend agent functionality with custom hooks.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/agent/trigger` | List triggers |
+| GET | `/workspace/{workspace_id}/agent/trigger/{trigger_id}` | Get trigger |
+| POST | `/workspace/{workspace_id}/agent/trigger` | Create trigger |
+| PUT | `/workspace/{workspace_id}/agent/trigger/{trigger_id}` | Update trigger |
+| DELETE | `/workspace/{workspace_id}/agent/trigger/{trigger_id}` | Delete trigger |
+
+## XanoScript Syntax
+
+```xanoscript
+agent_trigger foo {
+  agent = "my_agent"
+  input {
+    object toolset {
+      schema {
+        int id
+        text name
+        text instructions
+      }
+    }
+    object[] tools {
+      schema {
+        int id
+        text name
+        text instructions
+      }
+    }
+  }
+
+  stack {
+    var $x1 { value = 123 }
+  }
+
+  actions = {connection: true}
+}
+```
+
+---
+
+# MCP Server Triggers
+
+Extend MCP server functionality.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/mcp_server/trigger` | List triggers |
+| GET | `/workspace/{workspace_id}/mcp_server/trigger/{trigger_id}` | Get trigger |
+| POST | `/workspace/{workspace_id}/mcp_server/trigger` | Create trigger |
+| PUT | `/workspace/{workspace_id}/mcp_server/trigger/{trigger_id}` | Update trigger |
+| DELETE | `/workspace/{workspace_id}/mcp_server/trigger/{trigger_id}` | Delete trigger |
+
+## XanoScript Syntax
+
+```xanoscript
+mcp_server_trigger foo {
+  mcp_server = "my_server"
+  input {
+    object toolset {
+      schema {
+        int id
+        text name
+        text instructions
+      }
+    }
+    object[] tools {
+      schema {
+        int id
+        text name
+        text instructions
+      }
+    }
+  }
+
+  stack {
+    var $x1 { value = 123 }
+  }
+
+  actions = {connection: true}
+}
+```
+
+---
+
+# Realtime Triggers
+
+Execute code when realtime channel events occur.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/realtime/channel/trigger` | List triggers |
+| GET | `/workspace/{workspace_id}/realtime/channel/trigger/{trigger_id}` | Get trigger |
+| POST | `/workspace/{workspace_id}/realtime/channel/trigger` | Create trigger |
+| PUT | `/workspace/{workspace_id}/realtime/channel/trigger/{trigger_id}` | Update trigger |
+| DELETE | `/workspace/{workspace_id}/realtime/channel/trigger/{trigger_id}` | Delete trigger |
+
+## XanoScript Syntax
+
+```xanoscript
+realtime_trigger foo {
+  channel = "my_channel"
+  input {
+    enum action { values = ["message", "join"] }
+    text channel
+    object client {
+      schema {
+        json extras
+        object permissions {
+          schema {
+            int dbo_id
+            text row_id
+          }
+        }
+      }
+    }
+    object options {
+      schema {
+        bool authenticated
+        text channel
+      }
+    }
+    json payload
+  }
+
+  stack {
+    var $x1 { value = 123 }
+  }
+
+  actions = {connection: true}
+}
+```
+
+### Available Actions
+
+| Action | Description |
+|--------|-------------|
+| `connection` | Client connects |
+| `message` | Message received |
+| `join` | Client joins channel |
+
+---
+
+# Workflow Tests
+
+Automated tests for your workflows.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/workflow_test` | List tests |
+| GET | `/workspace/{workspace_id}/workflow_test/{workflow_test_id}` | Get test |
+| POST | `/workspace/{workspace_id}/workflow_test` | Create test |
+| PUT | `/workspace/{workspace_id}/workflow_test/{workflow_test_id}` | Update test |
+| DELETE | `/workspace/{workspace_id}/workflow_test/{workflow_test_id}` | Delete test |
+| PUT | `/workspace/{workspace_id}/workflow_test/{workflow_test_id}/security` | Update security |
+
+## XanoScript Syntax
+
+```xanoscript
+workflow_test foo {
+  stack {
+    var $x1 {
+      value = 1 + 2 + 3
+    }
+  }
+}
+```

package/api_docs/workspace.md

@@ -0,0 +1,246 @@
+# Workspace API
+
+Workspaces are the primary container for all Xano resources including tables, APIs, functions, and more.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace` | List all workspaces |
+| GET | `/workspace/{workspace_id}` | Get workspace details |
+| POST | `/workspace/{workspace_id}/export` | Export workspace archive |
+| POST | `/workspace/{workspace_id}/export-schema` | Export schema only |
+| POST | `/workspace/{workspace_id}/import` | Import workspace archive |
+| POST | `/workspace/{workspace_id}/import-schema` | Import schema to new branch |
+| GET | `/workspace/{workspace_id}/openapi` | Get OpenAPI specification |
+| GET | `/workspace/{workspace_id}/context` | Get AI-consumable context |
+| GET | `/workspace/{workspace_id}/multidoc` | Export as XanoScript multidoc |
+| POST | `/workspace/{workspace_id}/convert/fromXS` | Convert XanoScript to JSON |
+| POST | `/workspace/{workspace_id}/convert/toXS` | Convert JSON to XanoScript |
+
+---
+
+## List Workspaces
+
+```
+GET /workspace
+```
+
+Returns array of workspace objects the authenticated user can access.
+
+---
+
+## Get Workspace
+
+```
+GET /workspace/{workspace_id}
+```
+
+**Path Parameters:**
+- `workspace_id` (int, required): Workspace ID
+
+**Response Fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | Workspace unique identifier |
+| `name` | text | Workspace name |
+| `branch` | text | Current live branch label |
+| `swagger` | bool | OpenAPI documentation enabled |
+| `documentation.link` | text | Link to OpenAPI spec |
+
+---
+
+## Export Workspace
+
+```
+POST /workspace/{workspace_id}/export
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label (empty = live) |
+| `password` | text | "" | Optional encryption password |
+
+Returns downloadable archive file.
+
+---
+
+## Export Schema Only
+
+```
+POST /workspace/{workspace_id}/export-schema
+```
+
+Same parameters as export. Returns schema and branch configuration only.
+
+---
+
+## Import Workspace
+
+```
+POST /workspace/{workspace_id}/import
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file` | file | Yes | Export archive file |
+| `password` | text | No | Decryption password |
+
+Replaces all content in target workspace.
+
+---
+
+## Import Schema
+
+```
+POST /workspace/{workspace_id}/import-schema
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file` | file | Yes | Schema export file |
+| `newbranch` | text | Yes | Name for new branch |
+| `setlive` | bool | No | Set new branch as live |
+| `password` | text | No | Decryption password |
+
+---
+
+## Get OpenAPI Spec
+
+```
+GET /workspace/{workspace_id}/openapi
+```
+
+**Parameters:**
+- `branch` (text): Branch label (empty = live)
+
+Returns OpenAPI specification as JSON.
+
+---
+
+## Get Workspace Context
+
+```
+GET /workspace/{workspace_id}/context
+```
+
+Generates AI/LLM-consumable workspace context.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `format` | enum | "yaml" | Output: "json" or "yaml" |
+| `include` | text | "" | Comma-separated resource list |
+
+---
+
+## Export as XanoScript Multidoc
+
+```
+GET /workspace/{workspace_id}/multidoc
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `env` | bool | false | Include environment variables |
+| `records` | bool | false | Include database records |
+
+Returns XanoScript multidoc (`text/x-xanoscript`).
+
+---
+
+## Convert XanoScript to JSON
+
+```
+POST /workspace/{workspace_id}/convert/fromXS
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+Body: XanoScript code to convert.
+
+---
+
+## Convert JSON to XanoScript
+
+```
+POST /workspace/{workspace_id}/convert/toXS
+```
+
+**Content-Type:** `application/json`
+
+**Body:**
+```json
+{
+  "kind": "object_type",
+  "data": "json_data"
+}
+```
+
+---
+
+# Branches
+
+## List Branches
+
+```
+GET /workspace/{workspace_id}/branch
+```
+
+**Response Example:**
+```json
+[
+  {"created_at": "2024-01-01T00:00:00Z", "label": "v1", "backup": false, "live": true},
+  {"created_at": "2024-01-15T00:00:00Z", "label": "dev", "backup": false}
+]
+```
+
+## Delete Branch
+
+```
+DELETE /workspace/{workspace_id}/branch/{branch_label}
+```
+
+Cannot delete `v1` (root) or currently live branch.
+
+---
+
+# Datasources
+
+External database connections.
+
+## List Datasources
+
+```
+GET /workspace/{workspace_id}/datasource
+```
+
+## Create Datasource
+
+```
+POST /workspace/{workspace_id}/datasource
+```
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `label` | text | Yes | - | Unique label |
+| `color` | text | No | "#ebc346" | Display color (hex) |
+
+## Update Datasource
+
+```
+PUT /workspace/{workspace_id}/datasource/{label}
+```
+
+## Delete Datasource
+
+```
+DELETE /workspace/{workspace_id}/datasource/{label}
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};