@xano/developer-mcp 1.0.27 → 1.0.28

package/dist/xanoscript_docs/README.md

@@ -45,19 +45,9 @@ project/
 
 ## Environment Variables
 
-Access with `$env.<name>`. Built-in variables:
-
-| Variable                    | Description                   |
-| --------------------------- | ----------------------------- |
-| `$env.$remote_ip`           | Client IP address             |
-| `$env.$http_headers`        | Request headers array         |
-| `$env.$request_uri`         | Request URI                   |
-| `$env.$request_method`      | HTTP method (GET, POST, etc.) |
-| `$env.$request_querystring` | Query string                  |
-| `$env.$datasource`          | Current datasource            |
-| `$env.$branch`              | Current branch                |
-
-Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
+Access with `$env.<name>`. Common built-in variables include `$env.$remote_ip`, `$env.$http_headers`, `$env.$request_method`, `$env.$datasource`, and `$env.$branch`. Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
+
+For the complete list of system variables, see `xanoscript_docs({ topic: "syntax" })`.
 
 ## Core Syntax Patterns
 

package/dist/xanoscript_docs/ephemeral.md

@@ -0,0 +1,330 @@
+---
+applyTo: "ephemeral/**/*.xs"
+---
+
+# Ephemeral Environments
+
+Temporary Xano workspaces for testing and one-off operations.
+
+## Quick Reference
+
+| Type | Purpose | Lifecycle |
+|------|---------|-----------|
+| **Service** | Temporary workspace with DB/APIs | Runs until shut down |
+| **Job** | One-time operation | Executes once, then shuts down |
+
+### Directory Structure
+```
+ephemeral/
+├── my-service/
+│   ├── workspace.xs
+│   ├── tables/
+│   ├── functions/
+│   └── apis/
+└── my-job/
+    ├── workspace.xs
+    ├── tables/
+    └── functions/
+```
+
+---
+
+## Ephemeral Service
+
+A temporary workspace with database, functions, and API endpoints.
+
+### workspace.xs
+```xs
+workspace my_service {
+  env = {
+    api_key: "test-key"
+    debug: "true"
+  }
+}
+```
+
+### Table with Seed Data
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name filters=trim
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Event 1"}
+    {"id": 2, "name": "Event 2"}
+  ]
+}
+```
+
+### API Group
+```xs
+api_group events {
+  canonical = "events-api"
+}
+```
+
+### Endpoints
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+
+query add verb=POST {
+  api_group = "events"
+  input { text name filters=trim }
+  stack {
+    db.add event {
+      data = { name: $input.name }
+    } as $event
+  }
+  response = $event
+}
+```
+
+---
+
+## Ephemeral Job
+
+One-time operation with setup and cleanup hooks.
+
+### Reserved Functions
+| Function | Purpose | Required |
+|----------|---------|----------|
+| `$main` | Primary logic | Yes |
+| `$pre` | Setup/validation | No |
+| `$post` | Cleanup/notification | No |
+
+### Execution Order
+1. `$pre` (if defined)
+2. `$main`
+3. `$post` (if defined)
+4. Environment shuts down
+
+### $main Function
+```xs
+function "$main" {
+  input {
+    json args                   // Runtime arguments
+    json pre                    // Result from $pre
+  }
+  stack {
+    db.query authors {
+      return = { type: "count" }
+    } as $count
+
+    precondition ($count > 0) {
+      error = "No authors found"
+    }
+
+    db.add authors {
+      data = { name: "New Author" }
+    }
+  }
+  response = { processed: true }
+}
+```
+
+### $pre Function (optional)
+```xs
+function "$pre" {
+  input { json args }
+  stack {
+    // Validation or setup
+    precondition ($input.args.required_field != null) {
+      error = "Missing required field"
+    }
+  }
+  response = { validated: true }
+}
+```
+
+### $post Function (optional)
+```xs
+function "$post" {
+  input {
+    json args
+    json pre
+    json main
+  }
+  stack {
+    // Send notification or cleanup
+    api.request {
+      url = $env.WEBHOOK_URL
+      method = "POST"
+      params = {
+        status: "complete",
+        result: $input.main
+      }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Complete Service Example
+
+```
+ephemeral/event-tracker/
+├── workspace.xs
+├── tables/
+│   └── event.xs
+└── apis/
+    ├── api_group.xs
+    ├── list.xs
+    ├── add.xs
+    └── clear.xs
+```
+
+### workspace.xs
+```xs
+workspace event_tracker {
+  env = { api_key: "test" }
+}
+```
+
+### tables/event.xs
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = []
+}
+```
+
+### apis/list.xs
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      sort = { created_at: "desc" }
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+```
+
+---
+
+## Complete Job Example
+
+```
+ephemeral/data-migration/
+├── workspace.xs
+├── tables/
+│   └── users.xs
+└── functions/
+    ├── $main.xs
+    └── $post.xs
+```
+
+### workspace.xs
+```xs
+workspace data_migration {
+  env = { webhook_url: "https://webhook.site/xxx" }
+}
+```
+
+### tables/users.xs
+```xs
+table users {
+  auth = false
+  schema {
+    int id
+    text name
+    text email
+    timestamp migrated_at?
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Alice", "email": "alice@example.com"}
+    {"id": 2, "name": "Bob", "email": "bob@example.com"}
+  ]
+}
+```
+
+### functions/$main.xs
+```xs
+function "$main" {
+  input { json args, json pre }
+  stack {
+    db.query users {
+      where = $db.users.migrated_at == null
+    } as $pending
+
+    foreach ($pending) {
+      each as $user {
+        db.edit users {
+          field_name = "id"
+          field_value = $user.id
+          data = { migrated_at: now }
+        }
+      }
+    }
+  }
+  response = { migrated: $pending|count }
+}
+```
+
+### functions/$post.xs
+```xs
+function "$post" {
+  input { json args, json pre, json main }
+  stack {
+    api.request {
+      url = $env.webhook_url
+      method = "POST"
+      params = { result: $input.main }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Deploying
+
+### Deploy Service
+```
+publish_ephemeral_service name="my-api" directory="ephemeral/my-service" mode="service"
+```
+
+### Run Job
+```
+publish_ephemeral_service name="migration" directory="ephemeral/my-job" mode="job"
+```
+
+---
+
+## Best Practices
+
+1. **Keep isolated** - Self-contained with own tables/functions
+2. **Seed test data** - Use `items` in table definitions
+3. **Handle cleanup** - Use `$post` for notifications/cleanup
+4. **Validate in $pre** - Check preconditions before main logic
+5. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`

package/dist/xanoscript_docs/functions.md

@@ -87,27 +87,6 @@ input {
 }
 ```
 
-### Empty and Single-Input Blocks
-
-Empty input blocks and single-input blocks can be written as one-liners. However, when there are two or more inputs, each must be on its own line.
-
-```xs
-// OK - empty input as one-liner
-input {}
-
-// OK - single input as one-liner
-input { email email_input? filters=trim|lower }
-
-// OK - multiple inputs on separate lines
-input {
-  email email_input? filters=trim|lower
-  text name
-}
-
-// WRONG - multiple inputs on one line will cause parsing errors
-input { email email_input? filters=trim|lower text name }
-```
-
 ---
 
 ## Stack Block

package/dist/xanoscript_docs/integrations.md

@@ -506,16 +506,6 @@ security.check_password {
 } as $is_valid
 ```
 
-### Auth Tokens
-```xs
-security.create_auth_token {
-  table = "user"
-  id = $user.id
-  extras = { role: $user.role }
-  expiration = 86400
-} as $token
-```
-
 ### Encryption
 ```xs
 # Encrypt

package/dist/xanoscript_docs/performance.md

@@ -276,16 +276,7 @@ api.request {
 
 ## Rate Limiting
 
-### Protect Endpoints
-
-```xs
-redis.ratelimit {
-  key = "api:" ~ $auth.id
-  max = 100
-  ttl = 60
-  error = "Rate limit exceeded. Try again in 1 minute."
-}
-```
+For basic rate limiting setup, see `xanoscript_docs({ topic: "security" })`. Below are performance-focused patterns.
 
 ### Tiered Limits
 

package/dist/xanoscript_docs/realtime.md

@@ -261,54 +261,7 @@ api.realtime_event {
 
 ## Realtime Triggers
 
-Handle events from connected clients.
-
-### Basic Realtime Trigger
-
-```xs
-realtime_trigger "on_presence" {
-  channel = "room:*"
-  event = "join"
-  stack {
-    // $input contains event data
-    // $channel contains matched channel
-    db.add "presence" {
-      data = {
-        user_id: $auth.id,
-        room_id: $input.room_id,
-        joined_at: now
-      }
-    }
-
-    // Notify room members
-    api.realtime_event {
-      channel = $channel
-      event = "user_joined"
-      data = { user_id: $auth.id }
-    }
-  }
-}
-```
-
-### Channel Pattern Matching
-
-```xs
-realtime_trigger "document_cursor" {
-  channel = "document:*"               // Wildcard match
-  event = "cursor_move"
-  stack {
-    // Broadcast cursor position to other viewers
-    api.realtime_event {
-      channel = $channel
-      event = "cursor_update"
-      data = {
-        user_id: $auth.id,
-        position: $input.position
-      }
-    }
-  }
-}
-```
+Handle events from connected clients using `realtime_trigger`. For complete trigger syntax, input schemas, and configuration options, see `xanoscript_docs({ topic: "triggers" })`.
 
 ---
 

package/dist/xanoscript_docs/security.md

@@ -33,6 +33,8 @@ security.create_auth_token {
 } as $token
 ```
 
+**Note:** The `extras` parameter is required even if you don't need to store additional claims (`extras = { }`).
+
 ### Token Verification
 
 ```xs

package/dist/xanoscript_docs/tools.md

@@ -74,27 +74,6 @@ input {
 }
 ```
 
-### Empty and Single-Input Blocks
-
-Empty input blocks and single-input blocks can be written as one-liners. When there are two or more inputs, each must be on its own line.
-
-```xs
-// OK - empty input
-tool "get_system_status" {
-  description = "Get current system status"
-  instructions = "Use this to check if the system is healthy"
-  input {}
-  stack { ... }
-  response = $status
-}
-
-// OK - single input as one-liner
-input { text query filters=trim }
-
-// WRONG - multiple inputs on one line will cause parsing errors
-input { text query filters=trim int limit }
-```
-
 ---
 
 ## Tool-Specific Statements
@@ -275,6 +254,8 @@ tool "get_order_with_items" {
 
 ## Error Handling
 
+For complete error handling reference (preconditions, try-catch, throw, error types), see `xanoscript_docs({ topic: "syntax" })`.
+
 ```xs
 tool "cancel_order" {
   instructions = "Cancel an order. Only works for pending orders."

package/dist/xanoscript_docs/triggers.md

@@ -43,34 +43,9 @@ input {
 | `action` | enum | The action that triggered: `insert`, `update`, `delete`, or `truncate` |
 | `datasource` | text | The datasource name where the change occurred |
 
-### Agent Trigger Input
+### Agent Trigger Input / MCP Server Trigger Input
 
-```xs
-input {
-  object toolset {
-    schema {
-      int id
-      text name
-      text instructions
-    }
-  }
-
-  object[] tools {
-    schema {
-      int id
-      text name
-      text instructions
-    }
-  }
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `toolset` | object | The toolset configuration with id, name, and instructions |
-| `tools` | object[] | Array of available tools with their id, name, and instructions |
-
-### MCP Server Trigger Input
+Agent triggers and MCP server triggers share the same input schema:
 
 ```xs
 input {

package/dist/xanoscript_docs_auto/README.md

@@ -0,0 +1,119 @@
+# XanoScript Complete Reference
+
+XanoScript is a declarative, statically-typed scripting language for [Xano](https://xano.com). It enables developers to build API endpoints, functions, scheduled tasks, database operations, and AI agents with structured, readable syntax.
+
+## Quick Reference
+
+### Top-Level Object Types
+
+| Type | File Location | Purpose |
+|------|---------------|---------|
+| `query` | `apis/<group>/*.xs` | HTTP API endpoints with verbs, input, processing, response |
+| `function` | `functions/**/*.xs` | Reusable logic blocks with optional testing |
+| `task` | `tasks/*.xs` | Scheduled operations with cron-like triggers |
+| `table` | `tables/*.xs` | Database schema definitions |
+| `table_trigger` | `triggers/**/*.xs` | Trigger handlers for database events |
+| `agent` | `agents/**/*.xs` | AI agent definitions |
+| `tool` | `tools/**/*.xs` | Tool definitions for AI agents |
+| `mcp_server` | `mcp_servers/**/*.xs` | Model Context Protocol server definitions |
+| `middleware` | `middleware/**/*.xs` | Request/response interceptors |
+| `addon` | `addons/*.xs` | Subqueries for related data |
+| `branch` | `branch.xs` | Branch-level configuration |
+| `workspace` | `workspace.xs` | Workspace-level settings |
+| `realtime_channel` | Configuration | Real-time channel definitions |
+| `api_group` | `apis/<group>/` | Collections of related API endpoints |
+
+**Important:** Each `.xs` file must contain exactly one definition.
+
+### Block Structure
+
+```xs
+<construct> "<name>" {
+  input { ... }      // Parameters (optional)
+  stack { ... }      // Logic
+  response = $var    // Output
+}
+```
+
+### Variable Access
+
+```xs
+$input.field        // Input parameters
+$var.name           // Stack variables (in some contexts)
+$auth.id            // Authenticated user ID
+$env.MY_VAR         // Environment variable
+$db.table.field     // Database field reference (in queries)
+$this               // Current item in loops/maps
+$error              // Error information (in catch blocks)
+now                 // Current timestamp
+```
+
+### Language Blocks (Clauses)
+
+| Block | Purpose |
+|-------|---------|
+| `stack` | Container for sequential operations |
+| `input` | Define parameters with types and validation |
+| `schema` | Database table schema |
+| `response` | Specify output data |
+| `schedule` | Execution times for tasks |
+| `security` | Authentication and permissions |
+| `auth` | Authentication configuration |
+| `cache` | Caching configuration |
+| `history` | History tracking |
+| `index` | Database index definitions |
+| `test` | Test definitions |
+| `view` | View definitions |
+| `middleware` | Middleware configuration |
+
+## Workspace Structure
+
+```
+project/
+├── workspace.xs         // Workspace configuration
+├── branch.xs            // Branch configuration
+├── tables/              // Database table schemas
+├── functions/           // Reusable functions (supports subfolders)
+├── apis/
+│   └── <api-group>/     // API endpoints grouped by domain
+├── tasks/               // Scheduled jobs
+├── triggers/            // Event-driven handlers
+├── agents/              // AI agents
+├── tools/               // AI tools
+├── mcp_servers/         // MCP server definitions
+├── middleware/          // Request/response interceptors
+├── addons/              // Query addons
+├── static/              // Frontend files
+└── run/                 // Job and service configurations
+```
+
+## Comments
+
+```xs
+// Single-line comment
+/* Multi-line comment */
+var $total { value = 0 }  // Inline comment
+```
+
+## Documentation Topics
+
+| Topic | Description |
+|-------|-------------|
+| `syntax` | Expressions, operators, filters |
+| `types` | Data types and validation |
+| `operators` | Comparison, logical, math operators |
+| `filters` | Pipe filters for transformations |
+| `control-flow` | Conditionals, loops, error handling |
+| `functions` | Function definitions and calls |
+| `database` | All db.* operations |
+| `apis` | HTTP endpoint definitions |
+| `tables` | Database schema definitions |
+| `tasks` | Scheduled jobs |
+| `triggers` | Event-driven handlers |
+| `agents` | AI agent configuration |
+| `tools` | AI tools for agents |
+| `mcp-servers` | MCP server definitions |
+| `integrations` | Cloud storage, Redis, external APIs |
+| `security-functions` | Encryption, hashing, auth tokens |
+| `testing` | Unit tests and assertions |
+| `variables` | System and built-in variables |