@xano/developer-mcp 1.0.26 → 1.0.27

package/dist/xanoscript_docs/README.md

@@ -4,21 +4,21 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 
 ## Quick Reference
 
-| Construct | File Location | Purpose |
-|-----------|---------------|---------|
-| `table` | `tables/*.xs` | Database schema definition |
-| `function` | `functions/**/*.xs` | Reusable logic blocks |
-| `query` | `apis/<group>/*.xs` | HTTP API endpoints |
-| `task` | `tasks/*.xs` | Scheduled/cron jobs |
-| `*_trigger` | `triggers/**/*.xs` | Event-driven handlers |
-| `agent` | `agents/**/*.xs` | AI-powered agents |
-| `tool` | `tools/**/*.xs` | Tools for AI agents |
-| `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
-| `addon` | `addons/*.xs` | Subqueries for related data |
-| `middleware` | `middleware/**/*.xs` | Request/response interceptors |
-| `branch` | `branch.xs` | Branch-level configuration |
-| `workspace` | `workspace.xs` | Workspace-level configuration |
-| `realtime_channel` | Configuration | Realtime channel settings |
+| Construct          | File Location         | Purpose                       |
+| ------------------ | --------------------- | ----------------------------- |
+| `table`            | `tables/*.xs`         | Database schema definition    |
+| `function`         | `functions/**/*.xs`   | Reusable logic blocks         |
+| `query`            | `apis/<group>/*.xs`   | HTTP API endpoints            |
+| `task`             | `tasks/*.xs`          | Scheduled/cron jobs           |
+| `*_trigger`        | `triggers/**/*.xs`    | Event-driven handlers         |
+| `agent`            | `agents/**/*.xs`      | AI-powered agents             |
+| `tool`             | `tools/**/*.xs`       | Tools for AI agents           |
+| `mcp_server`       | `mcp_servers/**/*.xs` | MCP server definitions        |
+| `addon`            | `addons/*.xs`         | Subqueries for related data   |
+| `middleware`       | `middleware/**/*.xs`  | Request/response interceptors |
+| `branch`           | `branch.xs`           | Branch-level configuration    |
+| `workspace`        | `workspace.xs`        | Workspace-level configuration |
+| `realtime_channel` | Configuration         | Realtime channel settings     |
 
 **Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
 
@@ -47,21 +47,22 @@ project/
 
 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 |
+| 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`.
 
 ## Core Syntax Patterns
 
 ### Block Structure
+
 ```xs
 <construct> "<name>" {
   input { ... }      // Parameters (optional)
@@ -71,6 +72,7 @@ Custom environment variables are set in the Xano dashboard and accessed as `$env
 ```
 
 ### Variable Access
+
 ```xs
 $input.field        // Input parameters
 $var.field          // Stack variables
@@ -83,14 +85,18 @@ $this               // Current item in loops/maps
 **Note:** `$response` is a reserved word and cannot be used as a variable name.
 
 ### Comments
+
 ```xs
 // Single-line comment
-var $total { value = 0 }  // Inline comment
+var $total {
+  value = 0
+}
 ```
 
 **Note:** XanoScript only supports `//` for comments. Other comment styles like `#` are not supported.
 
 ### Filters (Pipe Syntax)
+
 ```xs
 $value|trim|lower                    // Chain filters
 $input.name|strlen                   // Get length
@@ -115,58 +121,66 @@ This helps AI tools apply the correct documentation based on the file being edit
 Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
-| Topic | Description |
-|-------|-------------|
-| `syntax` | Expressions, operators, filters, system variables |
-| `types` | Data types, validation, input blocks |
-| `functions` | Reusable function stacks, async, loops |
-| `schema` | Runtime schema parsing and validation |
+
+| Topic       | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `syntax`    | Expressions, operators, filters, system variables |
+| `types`     | Data types, validation, input blocks              |
+| `functions` | Reusable function stacks, async, loops            |
+| `schema`    | Runtime schema parsing and validation             |
 
 ### Data
-| Topic | Description |
-|-------|-------------|
-| `tables` | Database schema definitions with indexes and relationships |
-| `database` | All db.* operations: query, get, add, edit, patch, delete |
-| `addons` | Reusable subqueries for fetching related data |
-| `streaming` | Streaming data from files, requests, and responses |
+
+| Topic       | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| `tables`    | Database schema definitions with indexes and relationships |
+| `database`  | All db.\* operations: query, get, add, edit, patch, delete |
+| `addons`    | Reusable subqueries for fetching related data              |
+| `streaming` | Streaming data from files, requests, and responses         |
 
 ### APIs & Endpoints
-| Topic | Description |
-|-------|-------------|
-| `apis` | HTTP endpoint definitions with authentication and CRUD patterns |
-| `tasks` | Scheduled and cron jobs |
-| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
-| `realtime` | Real-time channels and events for push updates |
+
+| Topic      | Description                                                     |
+| ---------- | --------------------------------------------------------------- |
+| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns |
+| `tasks`    | Scheduled and cron jobs                                         |
+| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP)  |
+| `realtime` | Real-time channels and events for push updates                  |
 
 ### AI & Agents
-| Topic | Description |
-|-------|-------------|
-| `agents` | AI agent configuration with LLM providers and tools |
-| `tools` | AI tools for agents and MCP servers |
-| `mcp-servers` | MCP server definitions exposing tools |
+
+| Topic         | Description                                         |
+| ------------- | --------------------------------------------------- |
+| `agents`      | AI agent configuration with LLM providers and tools |
+| `tools`       | AI tools for agents and MCP servers                 |
+| `mcp-servers` | MCP server definitions exposing tools               |
 
 ### Integrations
-| Topic | Description |
-|-------|-------------|
+
+| Topic          | Description                                       |
+| -------------- | ------------------------------------------------- |
 | `integrations` | Cloud storage, Redis, security, and external APIs |
 
 ### Configuration
-| Topic | Description |
-|-------|-------------|
-| `workspace` | Workspace-level settings: environment variables, preferences, realtime |
-| `branch` | Branch-level settings: middleware, history retention, visual styling |
+
+| Topic        | Description                                                            |
+| ------------ | ---------------------------------------------------------------------- |
+| `workspace`  | Workspace-level settings: environment variables, preferences, realtime |
+| `branch`     | Branch-level settings: middleware, history retention, visual styling   |
 | `middleware` | Request/response interceptors for functions, queries, tasks, and tools |
 
 ### Development
-| Topic | Description |
-|-------|-------------|
-| `testing` | Unit tests, mocks, and assertions |
-| `debugging` | Logging, inspecting, and debugging XanoScript execution |
-| `frontend` | Static frontend development and deployment |
-| `run` | Run job and service configurations for the Xano Job Runner |
+
+| Topic       | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| `testing`   | Unit tests, mocks, and assertions                          |
+| `debugging` | Logging, inspecting, and debugging XanoScript execution    |
+| `frontend`  | Static frontend development and deployment                 |
+| `run`       | Run job and service configurations for the Xano Job Runner |
 
 ### Best Practices
-| Topic | Description |
-|-------|-------------|
-| `performance` | Performance optimization best practices |
-| `security` | Security best practices for authentication and authorization |
+
+| Topic         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `performance` | Performance optimization best practices                      |
+| `security`    | Security best practices for authentication and authorization |

package/dist/xanoscript_docs/apis.md

@@ -12,7 +12,7 @@ HTTP endpoint definitions in XanoScript.
 query "endpoint-path" verb=<METHOD> {
   api_group = "<GroupName>"     // Required: API group for organization
   description = "What this endpoint does"
-  auth = "<table>"              // Optional: require authentication
+  auth = "<table>"              // Optional: table with auth = true (usually "user")
   input { ... }
   stack { ... }
   response = $result
@@ -24,16 +24,19 @@ query "endpoint-path" verb=<METHOD> {
 The query name is **required** and **must be a non-empty string**. Empty names (`query "" verb=...`) are invalid. The name defines the endpoint path after the API group canonical.
 
 **Full URL path structure:**
+
 ```
 /<api_group canonical>/<query name>
 ```
 
 The query name can include slashes for nested paths:
+
 - `query "list" verb=GET` → `/<canonical>/list`
 - `query "users/{id}" verb=GET` → `/<canonical>/users/{id}`
 - `query "admin/reports/daily" verb=GET` → `/<canonical>/admin/reports/daily`
 
 ### HTTP Methods
+
 `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
 
 ### API Groups (Required)
@@ -41,25 +44,50 @@ The query name can include slashes for nested paths:
 Every endpoint must belong to an API group. Each group is a folder with an `api_group.xs` file:
 
 ```xs
+// Minimal definition
 api_group "users" {
-  canonical = "users"                // Required: URL path segment
+  canonical = "myapp-users"          // Required: URL path segment (unique at instance level)
   description = "User management"    // Optional
 }
 ```
 
+**Full definition with all options:**
+
+```xs
+api_group Authentication {
+  active = false                     // Disable group (cannot be externally invoked)
+  canonical = "plmgzl-s"            // Required: unique at instance level
+  swagger = {token: "cbO83nMTt7BVgq3QcQgKikDfHeo"}  // Protect Swagger docs behind a token (plain text)
+  tags = ["auth", "security", "encrypted"]           // Tags for organization
+  history = 100                      // Request history: up to 100 statements per request
+}
+```
+
+| Property      | Type   | Required | Description                                                                 |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `canonical`   | text   | Yes      | URL path segment, must be unique at the instance level                      |
+| `description` | text   | No       | Human-readable description                                                  |
+| `active`      | bool   | No       | Whether the group accepts external requests (default: `true`)               |
+| `swagger`     | object | No       | Swagger documentation settings. `token` protects access (stored plain text) |
+| `tags`        | list   | No       | Tags for organization and filtering                                         |
+| `history`     | int    | No       | Max number of statements recorded per request for debugging                 |
+
+**Canonical uniqueness:** A Xano instance can host multiple workspaces. The `canonical` is used to route requests between workspaces and must be **unique at the instance level**, not just within your workspace. Use a descriptive, project-specific prefix to avoid collisions (e.g., `myapp-users` instead of `users`). A generic name like `user` is likely to conflict with another workspace's canonical on the same instance.
+
 ### File Structure
+
 ```
 apis/
 ├── users/
-│   ├── api_group.xs            // Defines group (canonical = "users")
-│   ├── list.xs                 // GET /users/list
-│   └── by-id.xs                // GET/PATCH/DELETE /users/{id}
+│   ├── api_group.xs            // Defines group (canonical = "myapp-users")
+│   ├── list.xs                 // GET /myapp-users/list
+│   └── by-id.xs                // GET/PATCH/DELETE /myapp-users/{id}
 └── products/
-    ├── api_group.xs            // Defines group (canonical = "products")
-    └── search.xs               // GET /products/search
+    ├── api_group.xs            // Defines group (canonical = "myapp-products")
+    └── search.xs               // GET /myapp-products/search
 ```
 
-Full URL: `/<canonical>/<query name>` (e.g., `/users/profile`)
+Full URL: `/<canonical>/<query name>` (e.g., `/myapp-users/profile`)
 
 ---
 
@@ -88,22 +116,24 @@ query "products" verb=GET {
 
 For complete type and filter reference, use `xanoscript_docs({ topic: "types" })`.
 
-### Empty Input Blocks
+### Empty and Single-Input Blocks
 
-**CRITICAL:** When an endpoint has no input parameters, the input block braces MUST be on separate lines. `input {}` on a single line will cause parsing errors.
+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
-// CORRECT - braces on separate lines
+// OK - empty input
 query "health" verb=GET {
   api_group = "System"
-  input {
-  }
+  input {}
   stack { ... }
   response = { status: "ok" }
 }
 
-// WRONG - causes parsing errors
-input {}
+// 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 }
 ```
 
 ---
@@ -111,6 +141,7 @@ input {}
 ## Authentication
 
 ### Public Endpoint (default)
+
 ```xs
 query "status" verb=GET {
   api_group = "System"
@@ -120,10 +151,13 @@ query "status" verb=GET {
 ```
 
 ### Authenticated Endpoint
+
+The `auth` attribute references a table that has `auth = true` in its definition (see [tables.md](tables.md)). This is typically the `user` table. While multiple auth tables are supported, it's recommended to use a single auth table and control access levels with a role flag or RBAC pattern.
+
 ```xs
 query "profile" verb=GET {
   api_group = "Users"
-  auth = "user"                 // Requires valid JWT
+  auth = "user"                 // Must reference a table with auth = true
   stack {
     db.get "user" {
       field_name = "id"
@@ -135,6 +169,8 @@ query "profile" verb=GET {
 ```
 
 When `auth` is set:
+
+- The referenced table must have `auth = true` in its table definition
 - Endpoint requires Bearer token in `Authorization` header
 - `$auth.id` contains authenticated user's ID
 - Invalid/missing token returns 401
@@ -143,21 +179,26 @@ When `auth` is set:
 
 ## Path Parameters
 
-Use `{param}` in the path:
+Use `{param}` in the path and capture its value in the input block:
 
 ```xs
 query "users/{user_id}" verb=GET {
-  api_group = "Users"
+  api_group = "Authentication"
   auth = "user"
+
   input {
-    int user_id { table = "user" }
+    int user_id {
+      table = "user"
+    }
   }
+
   stack {
     db.get "user" {
       field_name = "id"
       field_value = $input.user_id
     } as $user
   }
+
   response = $user
 }
 ```
@@ -167,6 +208,7 @@ query "users/{user_id}" verb=GET {
 ## CRUD Examples
 
 ### List (GET)
+
 ```xs
 query "products" verb=GET {
   api_group = "Products"
@@ -187,6 +229,7 @@ query "products" verb=GET {
 ```
 
 ### Create (POST)
+
 ```xs
 query "products" verb=POST {
   api_group = "Products"
@@ -213,6 +256,7 @@ query "products" verb=POST {
 ```
 
 ### Read (GET with ID)
+
 ```xs
 query "products/{product_id}" verb=GET {
   api_group = "Products"
@@ -235,6 +279,7 @@ query "products/{product_id}" verb=GET {
 ```
 
 ### Update (PATCH)
+
 ```xs
 query "products/{product_id}" verb=PATCH {
   api_group = "Products"
@@ -250,15 +295,19 @@ query "products/{product_id}" verb=PATCH {
 
     conditional {
       if ($input.name != null) {
-        var.update $updates { value = $updates|set:"name":$input.name }
+        var.update $updates.name { value = $input.name }
       }
     }
     conditional {
       if ($input.price != null) {
-        var.update $updates { value = $updates|set:"price":$input.price }
+        var.update $updates.price { value = $input.price }
       }
     }
 
+    precondition (($updates|is_empty) == false) {
+      error = "No updates provided"
+    }
+
     db.patch "product" {
       field_name = "id"
       field_value = $input.product_id
@@ -270,6 +319,7 @@ query "products/{product_id}" verb=PATCH {
 ```
 
 ### Delete (DELETE)
+
 ```xs
 query "products/{product_id}" verb=DELETE {
   api_group = "Products"
@@ -292,11 +342,13 @@ query "products/{product_id}" verb=DELETE {
 ## Response Types
 
 ### JSON (default)
+
 ```xs
 response = $data
 ```
 
 ### HTML
+
 ```xs
 stack {
   util.set_header {
@@ -316,6 +368,7 @@ response = $html
 ```
 
 ### Streaming
+
 ```xs
 stack {
   api.stream { value = $processed_data }
@@ -347,12 +400,12 @@ stack {
 
 For complete error handling reference, use `xanoscript_docs({ topic: "syntax" })`.
 
-| Type | HTTP Status |
-|------|-------------|
-| `inputerror` | 400 |
-| `accessdenied` | 403 |
-| `notfound` | 404 |
-| `standard` | 500 |
+| Type           | HTTP Status |
+| -------------- | ----------- |
+| `inputerror`   | 400         |
+| `accessdenied` | 403         |
+| `notfound`     | 404         |
+| `standard`     | 500         |
 
 ---
 
@@ -381,3 +434,4 @@ When using `return = { type: "list", paging: {...} }`:
 3. **Authenticate writes** - Always require auth for POST/PATCH/DELETE
 4. **Paginate lists** - Never return unbounded result sets
 5. **Group by resource** - Organize endpoints in logical api groups
+6. **Use specific canonicals** - Prefix canonicals to avoid instance-level collisions (e.g., `myapp-users` not `users`)

package/dist/xanoscript_docs/branch.md

@@ -89,7 +89,7 @@ branch "production" {
 
 ## History Configuration
 
-Control how many historical executions are retained for debugging and auditing.
+Control how many statements from the execution trace are retained per request. Execution traces are kept for 24 hours; this setting limits how many stack statements are recorded in each trace.
 
 ### Syntax
 
@@ -112,23 +112,23 @@ branch "production" {
 
 | Value | Description |
 |-------|-------------|
-| `false` | Disable history (no retention) |
-| `10` | Keep last 10 executions |
-| `100` | Keep last 100 executions |
-| `1000` | Keep last 1000 executions |
-| `10000` | Keep last 10000 executions |
-| `"all"` | Keep all executions (use with caution) |
+| `false` | Disable history (no statements recorded) |
+| `10` | Record up to 10 statements per trace |
+| `100` | Record up to 100 statements per trace |
+| `1000` | Record up to 1000 statements per trace |
+| `10000` | Record up to 10000 statements per trace |
+| `"all"` | Record all statements (use with caution) |
 
 ### History Targets
 
 | Target | Description |
 |--------|-------------|
-| `function` | Function execution history |
-| `query` | API endpoint request history |
-| `task` | Scheduled task execution history |
-| `tool` | AI tool invocation history |
-| `trigger` | Trigger execution history |
-| `middleware` | Middleware execution history |
+| `function` | Statement limit for function traces |
+| `query` | Statement limit for API endpoint traces |
+| `task` | Statement limit for scheduled task traces |
+| `tool` | Statement limit for AI tool traces |
+| `trigger` | Statement limit for trigger traces |
+| `middleware` | Statement limit for middleware traces |
 
 ---