@xano/developer-mcp 1.0.57 → 1.0.59

package/dist/xanoscript_docs/survival.md

@@ -0,0 +1,161 @@
+---
+applyTo: "**/*.xs"
+---
+
+# XanoScript Survival Kit
+
+> Minimal reference for writing valid XanoScript. For more: `xanoscript_docs({ topic: "<topic>" })`.
+
+## Quick Reference
+
+### Mental Model
+
+- Declarative block syntax, not imperative statements
+- One construct per `.xs` file (function, query, table, task, agent, tool, etc.)
+- Pipe `|` applies filters, `~` concatenates strings, `$input.x` accesses parameters
+
+### Type Names (CRITICAL)
+
+| Use This | NOT This |
+|----------|----------|
+| `text` | ~~string~~ |
+| `int` | ~~integer~~ |
+| `bool` | ~~boolean~~ |
+| `decimal` | ~~float/number~~ |
+| `type[]` | ~~array/list~~ |
+| `json` | ~~object/any~~ |
+
+### Reserved Names
+
+Cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`, `$index`
+
+### Variable Access
+
+```
+$input.field     — input parameters (ALWAYS use $input. prefix, never bare $field)
+$var.field        — stack variables (shorthand $field also works)
+$auth.id          — authenticated user
+$env.MY_VAR       — environment variable
+$db.table.field   — database field reference (in where clauses)
+$this             — current item in loops/maps
+```
+
+### Syntax Traps
+
+**Trap 1: `elseif` not `else if`**
+```xs
+// WRONG: conditional { if (...) { } else if (...) { } }
+// RIGHT:
+conditional {
+  if ($x > 0) { var $s { value = "positive" } }
+  elseif ($x == 0) { var $s { value = "zero" } }
+  else { var $s { value = "negative" } }
+}
+```
+
+**Trap 2: Parentheses around filters in expressions**
+```xs
+// WRONG: if ($arr|count > 0) { }
+// RIGHT:
+if (($arr|count) > 0) { }
+
+// WRONG: var $msg { value = $val|to_text ~ " items" }
+// RIGHT:
+var $msg { value = ($val|to_text) ~ " items" }
+```
+
+**Trap 3: Object literals use `:` — block properties use `=`**
+```xs
+// Object literal (data) — uses : with commas
+var $data { value = { name: "Alice", age: 30 } }
+
+// Block property (config) — uses = with NO commas, separate lines
+precondition ($data != null) {
+  error_type = "notfound"
+  error = "Not found"
+}
+```
+
+**Trap 4: `params` not `body` for api.request**
+```xs
+// WRONG: api.request { url = "..." method = "POST" body = $payload }
+// RIGHT:
+api.request { url = "..." method = "POST" params = $payload } as $result
+```
+
+**Trap 5: Wrong type names**
+```xs
+// WRONG: input { boolean active  integer count  string name }
+// RIGHT:
+input { bool active  int count  text name }
+```
+
+### Canonical Function Example
+
+```xs
+function "get_user_greeting" {
+  input {
+    int user_id
+    text? greeting?="Hello"
+  }
+  stack {
+    db.get "user" {
+      field_name = "id"
+      field_value = $input.user_id
+    } as $user
+
+    precondition ($user != null) {
+      error_type = "notfound"
+      error = "User not found"
+    }
+
+    var $message { value = ($input.greeting ?? "Hello") ~ ", " ~ $user.name ~ "!" }
+  }
+  response = $message
+}
+```
+
+### Canonical API Endpoint Example
+
+```xs
+query "users/{user_id}" verb=GET {
+  api_group = "users"
+  auth = "user"
+  input { int user_id }
+  stack {
+    db.get "user" { field_name = "id" field_value = $input.user_id } as $user
+    precondition ($user != null) { error_type = "notfound" error = "User not found" }
+  }
+  response = $user
+}
+```
+
+### Common Operations
+
+```xs
+db.get "table" { field_name = "id" field_value = $id } as $record
+db.query "table" { where = $db.table.active == true } as $records
+db.add "table" { data = { field: value } } as $new
+db.edit "table" { field_name = "id" field_value = $id data = { field: val } }
+db.del "table" { field_name = "id" field_value = $id }
+api.request { url = $url method = "POST" params = $data headers = ["Authorization: Bearer " ~ $env.KEY] } as $res
+function.run "my_func" { input = { param: value } } as $result
+foreach ($items) { each as $item { debug.log { value = $item } } }
+```
+
+### Input Modifiers
+
+```xs
+input {
+  text name                  // required, not nullable
+  text? bio                  // required, nullable (can send null)
+  text role?="user"          // optional with default
+  text? note?                // optional and nullable
+  email contact filters=trim // with validation filter
+  text[] tags                // array type
+}
+```
+
+### Available Topics
+
+essentials, syntax, types, database, functions, apis, tables, tasks, triggers, agents, tools, mcp-servers, security, performance, debugging, unit-testing, workflow-tests, middleware, addons, realtime, streaming, schema, integrations, workspace, branch, run, frontend

package/dist/xanoscript_docs/syntax.md

@@ -148,12 +148,6 @@ if (($arr|count) == 0) { ... }
 var $message {
   value = ($status|to_text) ~ ": " ~ ($data|json_encode)
 }
-
-// ✅ Correct — filter result used in arithmetic
-var $total { value = ($prices|sum) + $tax }
-
-// ✅ Correct — filter result compared
-var $is_long { value = ($text|strlen) > 100 }
 ```
 
 **Summary:** Any time you apply an operator (`>`, `<`, `==`, `!=`, `~`, `+`, `-`, etc.) to a filtered value, wrap the `$var|filter` portion in its own parentheses.

package/dist/xanoscript_docs/tables.md

@@ -319,11 +319,9 @@ table "order" {
 
 ## Best Practices
 
-1. **Always define `id`** - Every table needs a primary key named `id`
-2. **Use `auth = true`** only for authentication tables (typically just `user`)
-3. **Add indexes** for fields used in WHERE clauses and JOINs
-4. **Use appropriate types** - `email` for emails, `password` for credentials
-5. **Default timestamps** - Use `?=now` for created_at fields
+1. **Always define `int id`** - Every table requires a primary key field named `id`
+2. **Use `auth = true`** only for the authentication table (typically just `user`)
+3. **Add indexes** for fields used in `db.query` WHERE clauses and JOINs to avoid full table scans
 
 ---
 

package/dist/xanoscript_docs/tasks.md

@@ -254,9 +254,7 @@ task "risky_sync" {
 
 1. **Descriptive names** - Indicate what and when: `daily_cleanup`, `hourly_sync`
 2. **Handle errors** - Use try_catch for external dependencies
-3. **Consider timezone** - Schedule uses UTC (+0000)
-4. **Batch operations** - Process in chunks for large datasets
-5. **Set end dates** - Use ends_on for temporary schedules
+3. **Consider timezone** - Schedule uses UTC (+0000); use `ends_on` for temporary schedules
 
 ---
 

package/dist/xanoscript_docs/tools.md

@@ -298,9 +298,7 @@ tool "cancel_order" {
 
 1. **Write clear instructions** - This is what the AI reads to understand the tool
 2. **Describe all inputs** - Help AI construct valid requests
-3. **Use enums for fixed options** - Reduces AI errors
-4. **Keep tools focused** - One task per tool
-5. **Limit response size** - Don't return huge datasets
+3. **Use enums for fixed options** - Reduces AI errors; keep tools focused to one task
 
 ---
 

package/dist/xanoscript_docs/triggers.md

@@ -589,77 +589,11 @@ mcp_server_trigger "database_tool_handler" {
 
 ---
 
-## Common Patterns
-
-### Error Handling in Triggers
-
-```xs
-table_trigger "safe_audit" {
-  table = "sensitive_data"
-  actions = {insert: true, update: true, delete: true, truncate: false}
-
-  // Uses predefined Table Trigger Input - see Predefined Input Blocks section
-  input { ... }
-
-  stack {
-    try_catch {
-      try {
-        db.add "audit_log" {
-          data = {
-            action: $input.action,
-            new_data: $input.new,
-            old_data: $input.old,
-            timestamp: now
-          }
-        }
-      }
-      catch {
-        debug.log { value = "Audit logging failed" }
-      }
-    }
-  }
-}
-```
-
-### Conditional Trigger Logic
-
-```xs
-table_trigger "conditional_notification" {
-  table = "order"
-  actions = {insert: true, update: false, delete: false, truncate: false}
-
-  // Uses predefined Table Trigger Input - see Predefined Input Blocks section
-  input { ... }
-
-  stack {
-    conditional {
-      if ($input.new.total > 1000) {
-        util.send_email {
-          service_provider = "resend"
-          api_key = $env.RESEND_API_KEY
-          to = "sales@example.com"
-          from = "system@example.com"
-          subject = "High Value Order"
-          message = "Order #" ~ $input.new.id ~ " for $" ~ $input.new.total
-        }
-      }
-    }
-  }
-}
-```
-
----
-
 ## Best Practices
 
-1. **Use predefined input blocks as-is** - Each trigger type has a read-only input block that cannot be modified; use the exact structure provided
-2. **Use descriptive names** - Indicate the event and action: `user_audit_log`, `chat_message_handler`
-3. **Handle errors gracefully** - Use try_catch to prevent trigger failures from affecting the main operation
-4. **Keep triggers lightweight** - Offload heavy processing to functions or tasks
-5. **Set appropriate history** - Use `history = false` for high-frequency triggers to save storage
-6. **Use tags** - Organize triggers with meaningful tags for easier management
-7. **Document with description** - Always provide a description explaining the trigger's purpose
-8. **Test thoroughly** - Triggers execute automatically, so ensure they handle edge cases
+1. **Use predefined input blocks as-is** - Each trigger type has a read-only input block that cannot be modified
+2. **Handle errors gracefully** - Use try_catch to prevent trigger failures from affecting the main operation
+3. **Keep triggers lightweight** - Offload heavy processing to functions or tasks; use `history = false` for high-frequency triggers
 
 ---
 

package/dist/xanoscript_docs/types.md

@@ -390,10 +390,9 @@ precondition ($input.start_date < $input.end_date) {
 
 ## Best Practices
 
-1. **Always specify types** - Never leave inputs untyped
-2. **Use filters first** - Prefer declarative filters over stack validation
-3. **Mark sensitive data** - Use `sensitive = true` for PII/credentials
-4. **Validate at boundaries** - Validate user input, trust internal calls
+1. **Use filters first** - Prefer declarative `filters=` over stack-level preconditions for input validation
+2. **Mark sensitive data** - Use `sensitive = true` for PII/credentials to mask them in logs
+3. **Use `?` placement correctly** - `text?` = nullable, `name?` = optional; these are independent modifiers
 
 ---
 

package/dist/xanoscript_docs/unit-testing.md

@@ -370,65 +370,11 @@ For a full breakdown of what each required/optional/nullable combination accepts
 
 ---
 
-## Complete Example
-
-```xs
-function "calculate_discount" {
-  input {
-    decimal subtotal filters=min:0
-    enum customer_type { values = ["regular", "premium", "vip"] }
-    text coupon?
-  }
-  stack {
-    var $discount_rate { value = 0 }
-
-    switch ($input.customer_type) {
-      case ("premium") { var.update $discount_rate { value = 0.1 } } break
-      case ("vip") { var.update $discount_rate { value = 0.2 } } break
-      default { var.update $discount_rate { value = 0 } }
-    }
-
-    conditional {
-      if ($input.coupon == "SAVE10") {
-        math.add $discount_rate { value = 0.1 }
-      }
-    }
-
-    var $discount { value = $input.subtotal * $discount_rate }
-  }
-  response = { discount: $discount, rate: $discount_rate }
-
-  test "no discount for regular customer" {
-    input = { subtotal: 100, customer_type: "regular" }
-    expect.to_equal ($response.discount) { value = 0 }
-  }
-
-  test "10% discount for premium" {
-    input = { subtotal: 100, customer_type: "premium" }
-    expect.to_equal ($response.discount) { value = 10 }
-  }
-
-  test "20% discount for VIP" {
-    input = { subtotal: 100, customer_type: "vip" }
-    expect.to_equal ($response.discount) { value = 20 }
-  }
-
-  test "coupon stacks with VIP discount" {
-    input = { subtotal: 100, customer_type: "vip", coupon: "SAVE10" }
-    expect.to_equal ($response.rate) { value = 0.3 }
-  }
-}
-```
-
----
-
 ## Best Practices
 
 1. **Test happy paths, edge cases, and errors** - Cover expected, boundary, and failure scenarios
 2. **Use mocks** - Isolate from external dependencies
-3. **Descriptive test names** - Explain what's being tested
-4. **One assertion focus** - Each test verifies one behavior
-5. **Keep tests independent** - No shared state between tests
+3. **Descriptive test names** - Each test verifies one behavior
 
 ---
 

package/dist/xanoscript_docs/workflow-tests.md

@@ -181,44 +181,21 @@ expect.to_throw {
 
 ## Data Sources
 
-The `datasource` property controls which data source the test runs against.
-
-**Avoid using `datasource = "live"`.** When a workflow test runs, the entire datasource is cloned so that real data is not modified. This cloning step can be slow, especially for large datasources. Prefer running without a datasource or using a smaller custom datasource instead.
-
-### Default (No Data Source) — Recommended
+The `datasource` property controls which data source the test runs against. **Avoid `datasource = "live"`** — it clones the entire datasource before each run, which can be slow. Prefer omitting `datasource` or using a smaller custom datasource.
 
 ```xs
+// Recommended: no datasource
 workflow_test "basic_check" {
   stack {
     function.call "health_check" as $result
     expect.to_be_defined ($result)
   }
 }
-```
 
-### Custom Data Source
-
-```xs
-workflow_test "staging_data_check" {
+// Custom datasource
+workflow_test "staging_check" {
   datasource = "staging"
-  stack {
-    function.call "get_products" as $products
-    expect.to_be_defined ($products)
-  }
-}
-```
-
-### Live Data Source (Not Recommended)
-
-Using `datasource = "live"` clones the entire live datasource before running the test. Only use this when you specifically need to validate against production data.
-
-```xs
-workflow_test "live_data_check" {
-  datasource = "live"
-  stack {
-    function.call "get_active_users" as $users
-    expect.to_be_defined ($users)
-  }
+  stack { ... }
 }
 ```
 
@@ -317,13 +294,9 @@ workflow_test "comprehensive_test" {
 
 ## Best Practices
 
-1. **Use descriptive names** — Name tests after the workflow being tested: `user_signup_flow`, `checkout_process`
-2. **Tag for filtering** — Use tags like `critical`, `e2e`, `smoke` to organize test suites
-3. **Avoid `datasource = "live"`** — The entire datasource is cloned before each test run, which can be slow. Use no datasource or a smaller custom datasource instead
-4. **Keep tests independent** — Each workflow test should be self-contained and not depend on other tests
-5. **Use `function.call`, not `function.run`** — `function.call` handles errors so that `expect` assertions work correctly. `function.run` is for calling functions outside of workflow tests
-6. **Use assertions over preconditions** — Prefer `expect.*` assertions for clearer test intent
-7. **Don't test required fields with empty strings** — Required inputs reject both `null` and `""` at the platform level before your stack runs. If you send `""` to a required `text` field, you'll always get a platform validation error — never your custom logic. To test the empty/blank case, the input must be declared optional (`text name?`). See `xanoscript_docs({ topic: "types" })` for the full breakdown.
+1. **Use `function.call`, not `function.run`** — `function.call` handles errors so that `expect` assertions work correctly
+2. **Keep tests independent** — Each workflow test should be self-contained
+3. **Don't test required fields with empty strings** — Required inputs reject `""` at the platform level. Use optional fields (`text name?`) to test blank cases. See `xanoscript_docs({ topic: "types" })`
 
 ---