@xano/developer-mcp 1.0.26 → 1.0.27

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,31 +87,25 @@ input {
 }
 ```
 
-### Empty Input Blocks
+### Empty and Single-Input Blocks
 
-**CRITICAL:** When a function has no input parameters, the input block braces MUST be on separate lines. This is a syntax requirement.
+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
-// CORRECT - braces on separate lines
-function "get_all_users" {
-  description = "Returns all users"
-  input {
-  }
-  stack {
-    db.query "user" {} as $users
-  }
-  response = $users
-}
+// OK - empty input as one-liner
+input {}
 
-// 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
+// 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 }
 ```
 
 ---
@@ -116,6 +115,7 @@ function "get_all_users" {
 Contains the function logic using control flow, variables, and operations.
 
 ### Variables
+
 ```xs
 stack {
   var $counter { value = 0 }
@@ -127,6 +127,7 @@ stack {
 ```
 
 ### Conditionals
+
 ```xs
 stack {
   conditional {
@@ -144,6 +145,7 @@ stack {
 ```
 
 ### Loops
+
 ```xs
 stack {
   // For loop (count-based)
@@ -170,6 +172,7 @@ stack {
 ```
 
 ### Switch
+
 ```xs
 stack {
   switch ($input.status) {
@@ -208,6 +211,7 @@ response = null                      // No return value
 ## Calling Functions
 
 ### Basic Call
+
 ```xs
 function.run "calculate_total" {
   input = { quantity: 5, price: 10.50 }
@@ -215,6 +219,7 @@ function.run "calculate_total" {
 ```
 
 ### With Variables
+
 ```xs
 function.run "process_order" {
   input = {
@@ -226,6 +231,7 @@ function.run "process_order" {
 ```
 
 ### Nested Calls
+
 ```xs
 stack {
   function.run "validate_user" {
@@ -245,6 +251,7 @@ stack {
 ## Complete Examples
 
 ### Utility Function
+
 ```xs
 function "utils/format_currency" {
   description = "Format number as currency string"
@@ -265,6 +272,7 @@ function "utils/format_currency" {
 ```
 
 ### Data Processing
+
 ```xs
 function "process_order" {
   input {
@@ -305,6 +313,7 @@ function "process_order" {
 ```
 
 ### Validation Function
+
 ```xs
 function "validate_email_unique" {
   input {
@@ -346,65 +355,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 +484,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/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
 ```
 
 ---
@@ -401,7 +392,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/tables.md

@@ -23,9 +23,11 @@ table "<name>" {
 ```
 
 ### Field Types
+
 `int`, `text`, `email`, `password`, `decimal`, `bool`, `timestamp`, `date`, `uuid`, `vector`, `json`, `image`, `video`, `audio`, `attachment`, `enum`
 
 ### Index Types
+
 `primary`, `btree`, `btree|unique`, `gin`
 
 ---
@@ -58,6 +60,7 @@ table "user" {
 ## Schema Fields
 
 ### Basic Fields
+
 ```xs
 schema {
   int id
@@ -70,6 +73,7 @@ schema {
 ```
 
 ### Optional & Defaults
+
 ```xs
 schema {
   text nickname?                   // Optional, no default
@@ -80,6 +84,7 @@ schema {
 ```
 
 ### With Filters
+
 ```xs
 schema {
   text name filters=trim
@@ -90,6 +95,7 @@ schema {
 ```
 
 ### With Metadata
+
 ```xs
 schema {
   text ssn {
@@ -104,6 +110,7 @@ schema {
 ```
 
 ### Foreign Keys
+
 ```xs
 schema {
   int user_id {
@@ -117,6 +124,7 @@ schema {
 ```
 
 ### Enum Fields
+
 ```xs
 schema {
   enum status {
@@ -129,6 +137,7 @@ schema {
 ```
 
 ### JSON Fields
+
 ```xs
 schema {
   json metadata
@@ -137,17 +146,24 @@ schema {
 ```
 
 ### Vector Fields
+
 ```xs
 schema {
-  vector embedding              // For AI/ML embeddings
+  vector embedding              // Required vector field
+  vector? embeddings? {         // Optional vector field with explicit size
+    size = 768
+  }
 }
 ```
 
+The `size` parameter specifies the vector dimensions (must match your embedding model's output). Pair with a vector index for similarity search (see [Vector Index](#vector-index) below).
+
 ---
 
 ## Indexes
 
 ### Primary Key
+
 ```xs
 index = [
   {type: "primary", field: [{name: "id"}]}
@@ -155,6 +171,7 @@ index = [
 ```
 
 ### B-tree Index
+
 ```xs
 index = [
   {type: "btree", field: [{name: "email", op: "asc"}]}
@@ -163,6 +180,7 @@ index = [
 ```
 
 ### Unique Index
+
 ```xs
 index = [
   {type: "btree|unique", field: [{name: "email"}]}
@@ -171,6 +189,7 @@ index = [
 ```
 
 ### Composite Index
+
 ```xs
 index = [
   {type: "btree", field: [{name: "user_id"}, {name: "created_at", op: "desc"}]}
@@ -178,6 +197,7 @@ index = [
 ```
 
 ### GIN Index (for JSON/arrays)
+
 ```xs
 index = [
   {type: "gin", field: [{name: "tags", op: "jsonb_path_op"}]}
@@ -185,11 +205,35 @@ index = [
 ]
 ```
 
+### Full-Text Search Index
+
+```xs
+index = [
+  {
+    name : "search_content"
+    lang : "english"
+    type : "search"
+    field: [{name: "searchable_content", op: "A"}]
+  }
+]
+```
+
+### Vector Index
+
+```xs
+index = [
+  {type: "vector", field: [{name: "embeddings", op: "vector_cosine_ops"}]}
+]
+```
+
+Required for vector similarity searches via `cosine_distance` in `db.query`. PostgreSQL vector indexes only support ascending scans, so queries must sort by distance `asc` to use the index. Sorting `desc` will bypass the index and trigger a full table scan. See [database.md](database.md) for query usage.
+
 ---
 
 ## Complete Examples
 
 ### User Table (with auth)
+
 ```xs
 table "user" {
   auth = true
@@ -212,6 +256,7 @@ table "user" {
 ```
 
 ### Product Table
+
 ```xs
 table "product" {
   auth = false
@@ -235,6 +280,7 @@ table "product" {
 ```
 
 ### Order with Foreign Keys
+
 ```xs
 table "order" {
   auth = false

package/dist/xanoscript_docs/tools.md

@@ -74,23 +74,25 @@ input {
 }
 ```
 
-### Empty Input Blocks
+### Empty and Single-Input Blocks
 
-**CRITICAL:** When a tool 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
 tool "get_system_status" {
   description = "Get current system status"
   instructions = "Use this to check if the system is healthy"
-  input {
-  }
+  input {}
   stack { ... }
   response = $status
 }
 
-// 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 }
 ```
 
 ---