@xano/developer-mcp 1.0.34 → 1.0.36

package/dist/xanoscript_docs/mcp-servers.md

@@ -185,3 +185,13 @@ The MCP protocol handles:
 2. **Comprehensive instructions** - Guide AI on server's overall purpose
 3. **Logical tool grouping** - Group related tools in one server
 4. **Keep focused** - One domain per server (support, analytics, etc.)
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `tools` | AI tool definitions used by MCP servers |
+| `agents` | AI agent configuration |
+| `triggers` | MCP server triggers for connection events |

package/dist/xanoscript_docs/performance.md

@@ -6,6 +6,10 @@ applyTo: "function/**/*.xs, api/**/*.xs"
 
 Best practices for building fast, efficient XanoScript applications.
 
+> **TL;DR:** Index frequently queried fields. Use `select` to fetch only needed columns. Use `db.add_bulk`/`db.edit_bulk` for batch operations. Cache with Redis. Paginate large result sets.
+
+---
+
 ## Quick Reference
 
 | Area | Key Techniques |
@@ -387,3 +391,14 @@ conditional {
 8. **Filter early** - In database, not application code
 9. **Stream large responses** - Don't load into memory
 10. **Monitor performance** - Log slow operations
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `database` | Query optimization |
+| `integrations/redis` | Caching patterns |
+| `streaming` | Large data handling |
+| `debugging` | Performance monitoring |

package/dist/xanoscript_docs/quickstart.md

@@ -6,8 +6,66 @@ applyTo: "**/*.xs"
 
 Essential patterns for XanoScript development. Use this as a quick reference for frequently-used code patterns.
 
+> **TL;DR:** Quick reference for common patterns. Key rules: use `text` not `string`, `elseif` not `else if`, `params` not `body` for api.request, parentheses around filters in expressions.
+
 ## Quick Reference
 
+### Reserved Variable Names
+
+These variable names are reserved and cannot be used:
+
+| Variable | Description |
+|----------|-------------|
+| `$response` | API/function response (auto-populated) |
+| `$output` | Output value |
+| `$input` | Input parameters from request/function call |
+| `$auth` | Authenticated user context |
+| `$env` | Environment variables and request context |
+| `$db` | Database table reference for queries |
+| `$this` | Current context reference |
+| `$result` | Used in reduce operations |
+
+```xs
+// ❌ Wrong - using reserved variable name
+var $response { value = "test" }    // Error: $response is reserved
+
+// ✅ Correct - use a different name
+var $api_response { value = "test" }
+var $my_result { value = "test" }
+```
+
+### Type Names (Common Aliases)
+
+XanoScript uses specific type names. Common aliases from other languages won't work.
+
+> **Full reference:** For complete type details and validation, see `xanoscript_docs({ topic: "types" })`.
+
+| ❌ Wrong | ✅ Correct | Description |
+|----------|------------|-------------|
+| `boolean` | `bool` | Boolean true/false |
+| `integer` | `int` | 32-bit integer |
+| `string` | `text` | UTF-8 string |
+| `number` | `decimal` | Floating-point number |
+| `float` | `decimal` | Floating-point number |
+| `array` | `type[]` | Array (e.g., `text[]`, `int[]`) |
+| `list` | `type[]` | Array (e.g., `text[]`, `int[]`) |
+
+```xs
+// ❌ Wrong - invalid type names
+input {
+  boolean is_active    // Error: use "bool"
+  integer count        // Error: use "int"
+  string name          // Error: use "text"
+}
+
+// ✅ Correct - proper XanoScript types
+input {
+  bool is_active
+  int count
+  text name
+}
+```
+
 ### Variable Declaration
 ```xs
 var $name { value = "initial value" }
@@ -35,7 +93,7 @@ conditional {
 api.request {
   url = "https://api.example.com/data"
   method = "POST"
-  params = $payload
+  params = $payload   // Note: "params" is used for request body, NOT "body"
   headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
 } as $api_result
 
@@ -47,6 +105,27 @@ precondition ($api_result.response.status == 200) {
 var $data { value = $api_result.response.result }
 ```
 
+### api.request Response Structure
+The response object contains:
+```xs
+$result.response.status    // HTTP status code (200, 404, 500, etc.)
+$result.response.result    // Parsed response body (JSON decoded)
+$result.response.headers   // Response headers object
+```
+
+### While Loop
+```xs
+stack {
+  var $counter { value = 0 }
+  while ($counter < 10) {
+    each {
+      var.update $counter { value = $counter + 1 }
+      debug.log { value = "Iteration: " ~ ($counter|to_text) }
+    }
+  }
+}
+```
+
 ### String Concatenation
 ```xs
 var $greeting { value = "Hello, " ~ $input.name ~ "!" }
@@ -55,6 +134,70 @@ var $greeting { value = "Hello, " ~ $input.name ~ "!" }
 var $message { value = "Status: " ~ ($status|to_text) ~ " - " ~ ($data|json_encode) }
 ```
 
+### Input Block Syntax
+
+> **Full reference:** For complete input types and validation options, see `xanoscript_docs({ topic: "types" })`.
+
+```xs
+input {
+  // Required input
+  text name
+
+  // Optional input (can be omitted)
+  text nickname?
+
+  // Optional with default value
+  text role?="user"
+
+  // With filters applied
+  email contact filters=trim|lower
+
+  // Optional with default AND filters
+  text search?="" filters=trim
+
+  // Array type
+  text[] tags filters=trim
+
+  // Nested object with schema
+  object address {
+    schema {
+      text street
+      text city
+      text country?="US"
+    }
+  }
+}
+```
+
+### Error Types Reference
+
+> **Full reference:** For try-catch, throw, and preconditions, see `xanoscript_docs({ topic: "syntax" })`.
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 Bad Request | Invalid input data |
+| `accessdenied` | 403 Forbidden | Authorization failure |
+| `notfound` | 404 Not Found | Resource doesn't exist |
+| `standard` | 500 Internal Server Error | General errors |
+
+### Quick Filter Reference
+
+The most common filters at a glance:
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `trim` | `" hello "|trim` | `"hello"` |
+| `lower` | `"HELLO"|lower` | `"hello"` |
+| `first` | `[1,2,3]|first` | `1` |
+| `count` | `[1,2,3]|count` | `3` |
+| `to_int` | `"42"|to_int` | `42` |
+| `json_encode` | `{a:1}|json_encode` | `"{\"a\":1}"` |
+| `get` | `$obj|get:"key":"default"` | value or default |
+
+**Null handling:** `$val ?? "default"` or `$val|first_notnull:"default"`
+
+> **Full reference:** See `xanoscript_docs({ topic: "syntax" })` for all 100+ filters organized by category (string, array, object, type, date, encoding).
+
 ---
 
 ## Common Patterns
@@ -77,35 +220,15 @@ precondition ($input.email|contains:"@") {
 
 ### 2. Database CRUD
 
-```xs
-// Create
-db.add "user" {
-  data = { name: $input.name, email: $input.email }
-} as $new_user
-
-// Read one
-db.get "user" {
-  where = $db.user.id == $input.id
-} as $user
-
-// Read many
-db.query "user" {
-  where = $db.user.is_active == true
-  order = [{ field: created_at, direction: desc }]
-  paging = { limit: 10, offset: 0 }
-} as $users
-
-// Update
-db.edit "user" {
-  where = $db.user.id == $input.id
-  data = { name: $input.name }
-}
+| Operation | Use Case | Example |
+|-----------|----------|---------|
+| `db.get` | Single record by ID | `db.get "users" { field_name = "id" field_value = 1 } as $user` |
+| `db.query` | Filtered list | `db.query "users" { where = $db.users.active == true } as $users` |
+| `db.add` | Insert | `db.add "users" { data = { name: "John" } } as $new` |
+| `db.edit` | Update | `db.edit "users" { field_name = "id" field_value = 1 data = { name: "Jane" } }` |
+| `db.delete` | Delete | `db.delete "users" { field_name = "id" field_value = 1 }` |
 
-// Delete
-db.delete "user" {
-  where = $db.user.id == $input.id
-}
-```
+> **Full reference:** See `xanoscript_docs({ topic: "database" })` for joins, bulk operations, transactions, and more.
 
 ### 3. Optional Field Handling
 
@@ -142,6 +265,8 @@ var $active_items { value = $items|filter:$$.is_active == true }
 
 ### 5. Error Handling with Try-Catch
 
+> **Full reference:** For all error handling patterns, see `xanoscript_docs({ topic: "syntax" })`.
+
 ```xs
 try_catch {
   try {
@@ -159,6 +284,8 @@ try_catch {
 
 ### 6. Authentication Check
 
+> **Full reference:** For security best practices, see `xanoscript_docs({ topic: "security" })`.
+
 ```xs
 // Require authenticated user
 precondition ($auth.id != null) {
@@ -220,6 +347,8 @@ var $response {
 
 ### 9. Date/Time Operations
 
+> **Full reference:** For all date/time filters, see `xanoscript_docs({ topic: "syntax" })`.
+
 ```xs
 // Current timestamp
 var $now { value = now }
@@ -239,6 +368,8 @@ db.query "event" {
 
 ### 10. JSON API Response
 
+> **Full reference:** For external API patterns, see `xanoscript_docs({ topic: "integrations" })`.
+
 ```xs
 api.request {
   url = "https://api.openai.com/v1/chat/completions"
@@ -287,42 +418,104 @@ conditional {
 
 ### 2. Missing parentheses in filter concatenation
 ```xs
-// ❌ Wrong
+// ❌ Wrong - parse error
 var $msg { value = $status|to_text ~ " - " ~ $data|json_encode }
 
-// ✅ Correct
+// ✅ Correct - wrap filtered expressions in parentheses
 var $msg { value = ($status|to_text) ~ " - " ~ ($data|json_encode) }
 ```
 
-### 3. Using `body` instead of `params` for api.request
+### 3. Missing parentheses in filter comparisons
 ```xs
-// ❌ Wrong
+// ❌ Wrong - parse error
+if ($array|count > 0) { }
+
+// ✅ Correct - wrap filter expression in parentheses
+if (($array|count) > 0) { }
+```
+
+### 4. Using `body` instead of `params` for api.request
+```xs
+// ❌ Wrong - "body" is not valid
 api.request {
   url = "..."
   method = "POST"
-  body = $payload  // "body" is not valid!
+  body = $payload
 }
 
-// ✅ Correct
+// ✅ Correct - use "params" for request body
 api.request {
   url = "..."
   method = "POST"
-  params = $payload  // Use "params" for request body
+  params = $payload
 }
 ```
 
-### 4. Using `default` filter (doesn't exist)
+### 5. Using `default` filter (doesn't exist)
 ```xs
-// ❌ Wrong
+// ❌ Wrong - no "default" filter exists
 var $value { value = $input.optional|default:"fallback" }
 
-// ✅ Correct
+// ✅ Correct - use first_notnull or ?? operator
 var $value { value = $input.optional|first_notnull:"fallback" }
 // or
 var $value { value = $input.optional ?? "fallback" }
+
+// For object key access with default, use get with 3rd parameter
+var $val { value = $obj|get:"key":"default_value" }
+```
+
+### 6. Using reserved variable names
+```xs
+// ❌ Wrong - $response is reserved
+var $response { value = "test" }
+
+// ✅ Correct - use a different name
+var $api_response { value = "test" }
+```
+
+### 7. Wrong type names
+```xs
+// ❌ Wrong - invalid type names
+input {
+  boolean active      // Use "bool"
+  integer count       // Use "int"
+  string name         // Use "text"
+}
+
+// ✅ Correct
+input {
+  bool active
+  int count
+  text name
+}
+```
+
+### 8. Object literal syntax (using = instead of :)
+```xs
+// ❌ Wrong - object literals use : not =
+var $data { value = { customer = $id } }
+
+// ✅ Correct - use : for object properties
+var $data { value = { customer: $id } }
 ```
 
-### 5. Using $env in run.job input blocks
+### 9. Throw block with commas
+```xs
+// ❌ Wrong - throw blocks don't use commas
+throw {
+  name = "Error",
+  value = "message"
+}
+
+// ✅ Correct - no commas between properties
+throw {
+  name = "Error"
+  value = "message"
+}
+```
+
+### 10. Using $env in run.job input blocks
 ```xs
 // ❌ Wrong - $env not allowed in input blocks
 run.job "my_job" {
@@ -331,10 +524,64 @@ run.job "my_job" {
   }
 }
 
-// ✅ Correct - use $env in the stack
+// ✅ Correct - access $env in the stack instead
 run.job "my_job" {
   stack {
     var $api_key { value = $env.API_KEY }
   }
 }
 ```
+
+### 11. Using `object` type without schema
+```xs
+// ❌ Wrong - object requires a schema
+input {
+  object data        // Error: needs schema
+}
+
+// ✅ Correct - use json for arbitrary data
+input {
+  json data          // Accepts any JSON
+}
+
+// ✅ Or define a schema for object
+input {
+  object data {
+    schema {
+      text name
+      int id
+    }
+  }
+}
+```
+
+### 12. While loop outside of stack block
+```xs
+// ❌ Wrong - while must be inside stack
+while (true) {
+  each { ... }
+}
+
+// ✅ Correct - wrap in stack block
+stack {
+  while (true) {
+    each { ... }
+  }
+}
+```
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `syntax` | Complete filter reference, operators, system variables |
+| `types` | Data types, input validation, schema definitions |
+| `database` | All db.* operations: query, get, add, edit, delete |
+| `functions` | Reusable function stacks, async patterns, loops |
+| `apis` | HTTP endpoints, authentication, CRUD patterns |
+| `security` | Security best practices and authentication |
+| `integrations` | External API patterns (OpenAI, Stripe, etc.) |

package/dist/xanoscript_docs/run.md

@@ -366,3 +366,13 @@ query list verb=GET {
 3. **Keep self-contained** - Include all required tables and functions
 4. **Seed test data** - Use `items` in table definitions for testing
 5. **Validate inputs** - Use preconditions in functions for input validation
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `functions` | Function stacks run by jobs |
+| `tasks` | Scheduled task definitions |
+| `tables` | Database tables accessed by jobs |

package/dist/xanoscript_docs/security.md

@@ -6,6 +6,21 @@ applyTo: "function/**/*.xs, api/**/*.xs"
 
 Best practices for building secure XanoScript applications.
 
+> **TL;DR:** Always check `$auth.id` for protected endpoints. Use `security.create_auth_token` for JWT. Validate all inputs with `filters=`. Hash passwords with `password` type. Use `$env.SECRET_NAME` for secrets.
+
+## Section Index
+
+- [Authentication](#authentication) (L24) - Tokens, sessions, MFA
+- [Authorization](#authorization) (L186) - Role checks, ownership
+- [Input Validation](#input-validation) (L277) - Type enforcement, sanitization
+- [Data Protection](#data-protection) (L339) - Encryption, hashing, secrets
+- [Rate Limiting](#rate-limiting--abuse-prevention) (L427) - API limits, abuse prevention
+- [Security Headers](#security-headers) (L486) - CORS configuration
+- [Audit Logging](#audit-logging) (L504) - Security event tracking
+- [Best Practices Summary](#best-practices-summary) (L545) - Quick checklist
+
+---
+
 ## Quick Reference
 
 | Area | Key Practices |
@@ -550,3 +565,14 @@ function.run "audit_log" {
 8. **Log security events** - Audit trail for compliance
 9. **Use HTTPS** - Always (handled by platform)
 10. **Rotate tokens** - Implement refresh token flow
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `apis` | Endpoint authentication |
+| `types` | Input validation |
+| `middleware` | Request interceptors |
+| `integrations/redis` | Rate limiting |

package/dist/xanoscript_docs/streaming.md

@@ -338,3 +338,13 @@ query "stream_large_dataset" {
 3. **Handle errors gracefully** - Log failures without stopping stream
 4. **Set appropriate chunk sizes** - Balance memory and performance
 5. **Use JSONL for structured data** - Easier to parse than multi-line JSON
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `integrations` | Cloud storage for file sources |
+| `apis` | Streaming API responses |
+| `database` | Processing streamed data into tables |

package/dist/xanoscript_docs/syntax.md

@@ -6,6 +6,62 @@ applyTo: "**/*.xs"
 
 Complete reference for XanoScript expressions, operators, and filters.
 
+> **TL;DR:** XanoScript uses `|` for filters (`$text|trim`), `~` for string concat, and standard operators (`==`, `!=`, `&&`, `||`). Filters are chainable. Error handling uses `precondition`, `try_catch`, and `throw`.
+
+## Section Index
+
+| Section | Contents |
+|---------|----------|
+| [Operators](#quick-reference) | Comparison, logical, math, null-safe |
+| [Conditional Blocks](#conditional-blocks) | `conditional`, `if`/`elseif`/`else` |
+| [Expressions](#expressions) | Backtick syntax, comparisons |
+| [Math Filters](#math-filters) | `add`, `subtract`, `round`, `abs`, `ceil`, `floor` |
+| [String Filters](#string-filters) | `trim`, `to_lower`, `to_upper`, `substr`, `split`, `replace` |
+| [Array Filters](#array-filters) | `first`, `last`, `count`, `map`, `filter`, `reduce` |
+| [Object Filters](#object-filters) | `get`, `set`, `has`, `keys`, `values` |
+| [Type Filters](#type-filters) | `to_int`, `to_text`, `to_bool`, `json_encode` |
+| [Date/Time Filters](#datetime-filters) | `to_timestamp`, `format_timestamp` |
+| [Encoding Filters](#encoding-filters) | `url_encode`, `base64_encode`, `json_encode` |
+| [Security Filters](#security-filters) | `md5`, `sha256`, `encrypt`, `jws_encode` |
+| [DB Query Filters](#db-query-filters) | `contains`, `includes`, `between`, `within` |
+| [Error Handling](#error-handling) | `precondition`, `try_catch`, `throw` |
+| [System Variables](#system-variables) | `$env.*`, `$auth.*`, request context |
+
+## Choosing a Filter
+
+```
+Working with...
+├── Strings?
+│   ├── Clean whitespace? → trim, ltrim, rtrim
+│   ├── Change case? → to_lower, to_upper, capitalize
+│   ├── Extract part? → substr
+│   ├── Split to array? → split
+│   ├── Find/replace? → replace, contains
+│   └── Get length? → strlen
+├── Arrays?
+│   ├── Get element? → first, last, get
+│   ├── Count items? → count
+│   ├── Transform all? → map
+│   ├── Keep some? → filter
+│   ├── Find one? → find
+│   ├── Combine? → reduce
+│   └── Sort? → sort
+├── Objects?
+│   ├── Get value? → get
+│   ├── Set value? → set
+│   ├── Check key? → has
+│   └── Extract? → keys, values
+├── Convert type?
+│   ├── To number? → to_int, to_decimal
+│   ├── To string? → to_text
+│   ├── To boolean? → to_bool
+│   └── To/from JSON? → json_encode, json_decode
+└── Check value?
+    ├── Is null? → is_null
+    ├── Is empty? → is_empty
+    └── Get type? → is_array, is_object, is_int, is_text
+```
+
 ## Quick Reference
 
 ### Operators
@@ -280,6 +336,8 @@ Generate numeric ranges with the `..` operator:
 
 ## Type Filters
 
+> **Full reference:** For input types and validation, see `xanoscript_docs({ topic: "types" })`.
+
 | Filter | Example | Result |
 |--------|---------|--------|
 | `to_int` | `"123"\|to_int` | `123` |
@@ -343,6 +401,8 @@ $ts|timestamp_day_of_week    // Day (0=Sunday)
 
 ## Security Filters
 
+> **Full reference:** For security best practices, see `xanoscript_docs({ topic: "security" })`.
+
 | Filter | Example |
 |--------|---------|
 | `md5` | `"text"\|md5` |
@@ -359,6 +419,8 @@ $ts|timestamp_day_of_week    // Day (0=Sunday)
 
 ## DB Query Filters
 
+> **Full reference:** For complete database operations, see `xanoscript_docs({ topic: "database" })`.
+
 Used in `db.query` where clauses:
 
 | Filter | Example | Description |
@@ -731,6 +793,8 @@ $db.created_at|timestamp_epoch_ms            // Milliseconds since epoch
 
 ### Vector Operations (AI/ML)
 
+> **Full reference:** For AI agents and embeddings, see `xanoscript_docs({ topic: "agents" })`.
+
 Additional vector similarity functions:
 
 ```xs
@@ -741,3 +805,17 @@ $db.embedding|inner_product:$input.vector            // Inner product
 // Geo covers (for polygon containment)
 $db.boundary|covers:$input.point                     // Polygon covers point
 ```
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `quickstart` | Common patterns, examples, mistakes to avoid |
+| `types` | Data types, input validation, schema definitions |
+| `database` | All db.* operations with query examples |
+| `functions` | Reusable function stacks, async patterns |
+| `security` | Security best practices and authentication |

package/dist/xanoscript_docs/tables.md

@@ -6,6 +6,10 @@ applyTo: "table/**/*.xs"
 
 Database table definitions in XanoScript.
 
+> **TL;DR:** Every table needs `int id` as primary key. Use `auth = true` for user tables. Add indexes for frequently queried fields. Use `filters=` for validation on fields.
+
+---
+
 ## Quick Reference
 
 ```xs
@@ -311,3 +315,14 @@ table "order" {
 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
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `database` | CRUD operations on tables |
+| `types` | Data types and validation |
+| `triggers` | Table triggers for CRUD events |
+| `addons` | Reusable subqueries |

package/dist/xanoscript_docs/tasks.md

@@ -257,3 +257,14 @@ task "risky_sync" {
 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
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `functions` | Reusable function stacks |
+| `database` | Database operations in tasks |
+| `debugging` | Logging and debugging task execution |
+| `triggers` | Event-driven alternatives to scheduled tasks |