@xano/developer-mcp 1.0.26 → 1.0.28

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

package/dist/xanoscript_docs/functions.md

@@ -19,7 +19,9 @@ function "<name>" {
   }
   response = $result
 }
+```
 
+```xs
 // Function with no inputs - IMPORTANT: braces must be on separate lines
 function "<name>" {
   description = "..."
@@ -31,6 +33,7 @@ function "<name>" {
 ```
 
 ### Calling Functions
+
 ```xs
 function.run "<name>" {
   input = { key: value }
@@ -55,7 +58,9 @@ function "calculate_total" {
 ```
 
 ### With Subfolders
+
 Functions can be organized in subfolders:
+
 ```
 functions/
 ├── math/
@@ -82,33 +87,6 @@ input {
 }
 ```
 
-### Empty Input Blocks
-
-**CRITICAL:** When a function has no input parameters, the input block braces MUST be on separate lines. This is a syntax requirement.
-
-```xs
-// CORRECT - braces on separate lines
-function "get_all_users" {
-  description = "Returns all users"
-  input {
-  }
-  stack {
-    db.query "user" {} as $users
-  }
-  response = $users
-}
-
-// WRONG - will cause parsing errors
-function "get_all_users" {
-  description = "Returns all users"
-  input {}    // <-- ERROR: braces must be on separate lines
-  stack {
-    db.query "user" {} as $users
-  }
-  response = $users
-}
-```
-
 ---
 
 ## Stack Block
@@ -116,6 +94,7 @@ function "get_all_users" {
 Contains the function logic using control flow, variables, and operations.
 
 ### Variables
+
 ```xs
 stack {
   var $counter { value = 0 }
@@ -127,6 +106,7 @@ stack {
 ```
 
 ### Conditionals
+
 ```xs
 stack {
   conditional {
@@ -144,6 +124,7 @@ stack {
 ```
 
 ### Loops
+
 ```xs
 stack {
   // For loop (count-based)
@@ -170,6 +151,7 @@ stack {
 ```
 
 ### Switch
+
 ```xs
 stack {
   switch ($input.status) {
@@ -208,6 +190,7 @@ response = null                      // No return value
 ## Calling Functions
 
 ### Basic Call
+
 ```xs
 function.run "calculate_total" {
   input = { quantity: 5, price: 10.50 }
@@ -215,6 +198,7 @@ function.run "calculate_total" {
 ```
 
 ### With Variables
+
 ```xs
 function.run "process_order" {
   input = {
@@ -226,6 +210,7 @@ function.run "process_order" {
 ```
 
 ### Nested Calls
+
 ```xs
 stack {
   function.run "validate_user" {
@@ -245,6 +230,7 @@ stack {
 ## Complete Examples
 
 ### Utility Function
+
 ```xs
 function "utils/format_currency" {
   description = "Format number as currency string"
@@ -265,6 +251,7 @@ function "utils/format_currency" {
 ```
 
 ### Data Processing
+
 ```xs
 function "process_order" {
   input {
@@ -305,6 +292,7 @@ function "process_order" {
 ```
 
 ### Validation Function
+
 ```xs
 function "validate_email_unique" {
   input {
@@ -346,65 +334,28 @@ stack {
 }
 ```
 
-### group (Parallel Execution)
+### group (Organizational Block)
 
-Execute multiple operations in parallel and wait for all to complete.
+Group related statements together for readability. The `group` block is purely organizational — it does **not** create parallel execution or a new scope.
 
 ```xs
 stack {
+  // Use group to visually organize related initialization
   group {
-    api.request {
-      url = "https://api.example.com/users"
-      method = "GET"
-    } as $users
-
-    api.request {
-      url = "https://api.example.com/products"
-      method = "GET"
-    } as $products
-
-    api.request {
-      url = "https://api.example.com/orders"
-      method = "GET"
-    } as $orders
-  }
+    stack {
+      var $total {
+        value = 0
+      }
 
-  // All three requests complete before continuing
-  var $combined {
-    value = {
-      users: $users.response.result,
-      products: $products.response.result,
-      orders: $orders.response.result
+      var $count {
+        value = 0
+      }
     }
   }
-}
-```
-
-### Parallel Database Queries
-
-```xs
-stack {
-  group {
-    db.query "user" {
-      where = $db.user.is_active == true
-      return = { type: "count" }
-    } as $active_users
-
-    db.query "order" {
-      where = $db.order.created_at >= $input.start_date
-      return = { type: "count" }
-    } as $order_count
-
-    db.query "product" {
-      where = $db.product.stock == 0
-      return = { type: "count" }
-    } as $out_of_stock
-  }
 
-  response = {
-    active_users: $active_users,
-    orders: $order_count,
-    out_of_stock: $out_of_stock
+  // Variables from the group are accessible here
+  var $average {
+    value = $total / $count
   }
 }
 ```
@@ -512,5 +463,5 @@ foreach ($items) {
 3. **Organize in folders** - Group related functions: `utils/`, `auth/`, `orders/`
 4. **Return early** - Use return for guard clauses
 5. **Keep stacks shallow** - Avoid deeply nested conditionals
-6. **Use group for parallel calls** - Improves performance for independent operations
+6. **Use group for organization** - Visually group related statements for readability
 7. **Use remove sparingly** - Consider filtering arrays instead

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

@@ -12,7 +12,7 @@ Best practices for building fast, efficient XanoScript applications.
 |------|----------------|
 | Database | Indexes, query optimization, pagination |
 | Caching | Redis, response caching |
-| Loops | Bulk operations, parallel execution |
+| Loops | Bulk operations, efficient iteration |
 | Filters | Efficient data transformations |
 
 ---
@@ -212,34 +212,25 @@ conditional {
 
 ---
 
-## Parallel Execution
+## Organizing with Group
 
-### Use Group for Independent Operations
+The `group` statement is an organizational block for visually grouping related statements. It does **not** create parallel execution or a new scope — variables declared inside a group are accessible outside it.
 
 ```xs
-// Execute in parallel
+// Use group to organize related variable initialization
 group {
-  db.query "user" { return = { type: "count" } } as $user_count
-  db.query "order" { return = { type: "count" } } as $order_count
-  db.query "product" { return = { type: "count" } } as $product_count
-}
+  stack {
+    var $total {
+      value = 0
+    }
 
-// All counts available after group completes
-response = {
-  users: $user_count,
-  orders: $order_count,
-  products: $product_count
+    var $count {
+      value = 0
+    }
+  }
 }
-```
-
-### Parallel API Calls
 
-```xs
-group {
-  api.request { url = "https://api1.example.com/data" } as $data1
-  api.request { url = "https://api2.example.com/data" } as $data2
-  api.request { url = "https://api3.example.com/data" } as $data3
-}
+// $total and $count are accessible here
 ```
 
 ---
@@ -285,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
 
@@ -401,7 +383,7 @@ conditional {
 4. **Avoid N+1 queries** - Use joins or batch fetching
 5. **Use bulk operations** - For batch inserts/updates
 6. **Cache expensive operations** - Redis with appropriate TTL
-7. **Execute in parallel** - Group independent operations
+7. **Use group for organization** - Group related statements for readability
 8. **Filter early** - In database, not application code
 9. **Stream large responses** - Don't load into memory
 10. **Monitor performance** - Log slow operations

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