@xano/developer-mcp 1.0.25 → 1.0.27

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 |
 
 ---
 

package/dist/xanoscript_docs/database.md

@@ -8,17 +8,17 @@ Complete reference for XanoScript database operations.
 
 ## Quick Reference
 
-| Operation | Purpose | Returns |
-|-----------|---------|---------|
-| `db.query` | Query multiple records | List/single/count/exists |
-| `db.get` | Get single record by field | Record or null |
-| `db.has` | Check if record exists | Boolean |
-| `db.add` | Insert new record | Created record |
-| `db.edit` | Update record (inline data) | Updated record |
-| `db.patch` | Update record (variable data) | Updated record |
-| `db.add_or_edit` | Upsert record | Record |
-| `db.del` | Delete record | None |
-| `db.truncate` | Delete all records | None |
+| Operation        | Purpose                       | Returns                  |
+| ---------------- | ----------------------------- | ------------------------ |
+| `db.query`       | Query multiple records        | List/single/count/exists |
+| `db.get`         | Get single record by field    | Record or null           |
+| `db.has`         | Check if record exists        | Boolean                  |
+| `db.add`         | Insert new record             | Created record           |
+| `db.edit`        | Update record (inline data)   | Updated record           |
+| `db.patch`       | Update record (variable data) | Updated record           |
+| `db.add_or_edit` | Upsert record                 | Record                   |
+| `db.del`         | Delete record                 | None                     |
+| `db.truncate`    | Delete all records            | None                     |
 
 ---
 
@@ -27,6 +27,7 @@ Complete reference for XanoScript database operations.
 Query multiple records with filters, sorting, and pagination.
 
 ### Basic Query
+
 ```xs
 db.query "product" {
   where = $db.product.is_active == true
@@ -34,6 +35,7 @@ db.query "product" {
 ```
 
 ### Where Operators
+
 ```xs
 // Comparison
 $db.product.price == 100
@@ -62,13 +64,14 @@ $db.product.category == "electronics" || $db.product.featured == true
 ```
 
 ### Return Types
+
 ```xs
-// List (default)
+// returns an array of products (default)
 db.query "product" {
   return = { type: "list" }
 } as $products
 
-// With pagination
+// Returns a paginated list of products
 db.query "product" {
   return = {
     type: "list",
@@ -76,19 +79,19 @@ db.query "product" {
   }
 } as $products
 
-// Single record
+// Returns a single record
 db.query "product" {
   where = $db.product.sku == $input.sku
   return = { type: "single" }
 } as $product
 
-// Count
+// Returns a count (number)
 db.query "product" {
   where = $db.product.is_active == true
   return = { type: "count" }
 } as $count
 
-// Exists
+// Returns a boolean indicating existence
 db.query "product" {
   where = $db.product.email == $input.email
   return = { type: "exists" }
@@ -96,6 +99,7 @@ db.query "product" {
 ```
 
 ### Sorting
+
 ```xs
 db.query "product" {
   sort = { created_at: "desc" }         // Descending
@@ -105,6 +109,7 @@ db.query "product" {
 ```
 
 ### Joins
+
 ```xs
 db.query "comment" {
   join = {
@@ -114,11 +119,15 @@ db.query "comment" {
       where: $db.comment.post_id == $db.post.id
     }
   }
+  eval = {
+    post_title: $db.post.title
+  }
   where = $db.post.author_id == $auth.id
 } as $comments
 ```
 
 ### Eval (Computed Fields)
+
 ```xs
 db.query "order" {
   join = {
@@ -132,6 +141,7 @@ db.query "order" {
 ```
 
 ### Addons (Related Data)
+
 ```xs
 db.query "post" {
   where = $db.post.author_id == $auth.id
@@ -141,6 +151,30 @@ db.query "post" {
 } as $posts
 ```
 
+### Vector Search (Similarity)
+
+Search by vector similarity using embeddings. Requires a `vector` column with a `vector` index on the table (see [tables.md](tables.md)).
+
+```xs
+// Embeddings from an LLM engine
+var $embeddings {
+  value = [0.345, 0.1553, ...]
+}
+
+db.query agent_message {
+  sort = {distance: "asc"}
+  eval = {
+    distance: $db.agent_message.embeddings|cosine_distance:$embeddings
+  }
+  return = {
+    type  : "list"
+    paging: {page: 1, per_page: 5, metadata: false}
+  }
+} as $search_results
+```
+
+The `cosine_distance` filter computes the distance between the row's vector and the provided embeddings. Sort by `distance` ascending (smallest distance = most similar) — this ordering is required to leverage the PostgreSQL vector index.
+
 ---
 
 ## db.get
@@ -338,6 +372,7 @@ db.transaction {
 Filters for use in `where` clauses:
 
 ### String/Text
+
 ```xs
 $db.name|to_lower                       // Case conversion
 $db.name|concat:" "                     // Concatenation
@@ -345,6 +380,7 @@ $db.text|substr:0:100                   // Substring
 ```
 
 ### Numeric
+
 ```xs
 $db.price|round:2
 $db.price|floor
@@ -354,6 +390,7 @@ $db.price|mul:1.1
 ```
 
 ### Timestamp
+
 ```xs
 $db.created_at|timestamp_year
 $db.created_at|timestamp_month
@@ -362,18 +399,21 @@ $db.created_at|timestamp_subtract_hours:24
 ```
 
 ### Geographic
+
 ```xs
 $db.location|distance:$input.point      // Distance in meters
 $db.location|within:$input.point:1000   // Within radius
 ```
 
 ### Vector (AI/ML)
+
 ```xs
-$db.embedding|cosine_similarity:$input.vector
+$db.embedding|cosine_distance:$input.vector
 $db.embedding|l2_distance_euclidean:$input.vector
 ```
 
 ### Full-Text Search
+
 ```xs
 $db.content|search_rank:$input.query
 ```