@xano/developer-mcp 1.0.33 → 1.0.35

package/dist/xanoscript_docs/syntax.md

@@ -21,12 +21,67 @@ Complete reference for XanoScript expressions, operators, and filters.
 | Filter | Purpose | Example |
 |--------|---------|---------|
 | `trim` | Remove whitespace | `$s\|trim` |
-| `lower` / `upper` | Case conversion | `$s\|to_lower` |
+| `to_lower` / `to_upper` | Case conversion | `$s\|to_lower` |
 | `first` / `last` | Array endpoints | `$arr\|first` |
 | `count` | Array/object length | `$arr\|count` |
 | `get` | Object property | `$obj\|get:"key"` |
 | `set` | Set property | `$obj\|set:"key":"val"` |
 | `json_encode` / `json_decode` | JSON conversion | `$obj\|json_encode` |
+| `to_text` / `to_int` | Type conversion | `$num\|to_text` |
+
+> **Note:** There is no `default` filter. Use conditional blocks or `first_notnull`/`first_notempty` instead.
+
+### String Concatenation with Filters
+
+When concatenating strings that use filters, wrap each filtered expression in parentheses:
+
+```xs
+// ✅ Correct - parentheses around filtered expressions
+var $message {
+  value = ($status|to_text) ~ ": " ~ ($data|json_encode)
+}
+
+// ❌ Incorrect - missing parentheses causes parse error
+var $message {
+  value = $status|to_text ~ ": " ~ $data|json_encode
+}
+```
+
+---
+
+## Conditional Blocks
+
+Use `conditional` blocks for if/elseif/else logic:
+
+```xs
+conditional {
+  if (`$status == "success"`) {
+    var $message { value = "All good!" }
+  }
+  elseif (`$status == "pending"`) {
+    var $message { value = "Please wait..." }
+  }
+  else {
+    var $message { value = "Unknown status" }
+  }
+}
+```
+
+> **Important:** Use `elseif` (one word), not `else if` or `else { if (...) }`. Nested `if` inside `else` blocks is not supported.
+
+### Conditional as Expression
+
+Use conditional blocks inline to return values:
+
+```xs
+var $tier_limit {
+  value = conditional {
+    if ($auth.tier == "premium") { 1000 }
+    elseif ($auth.tier == "pro") { 500 }
+    else { 100 }
+  }
+}
+```
 
 ---
 
@@ -225,6 +280,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` |
@@ -288,6 +345,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` |
@@ -304,6 +363,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 |
@@ -431,6 +492,32 @@ var $client_ip { value = $env.$remote_ip }
 var $method { value = $env.$request_method }
 var $headers { value = $env.$http_headers }
 var $current_branch { value = $env.$branch }
+
+// Custom environment variables (set in Xano dashboard)
+var $api_key { value = $env.MY_API_KEY }
+```
+
+### $env Limitations
+
+> **Important:** `$env` variables cannot be used in `run.job` or `run.service` input blocks. Input values must be constants.
+
+```xs
+// ❌ Invalid - $env not allowed in run.job input
+run.job "my_job" {
+  input {
+    text api_key = $env.API_KEY    // Error!
+  }
+}
+
+// ✅ Valid - access $env inside the stack instead
+run.job "my_job" {
+  input {
+    text api_key                   // No default value
+  }
+  stack {
+    var $key { value = $env.API_KEY }
+  }
+}
 ```
 
 ---
@@ -650,6 +737,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
@@ -660,3 +749,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/types.md

@@ -362,3 +362,17 @@ precondition ($input.start_date < $input.end_date) {
 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
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `schema` | Runtime schema parsing and validation |
+| `syntax` | All filters, operators, and error handling |
+| `quickstart` | Common patterns and mistakes to avoid |
+| `functions` | Using input blocks in functions |
+| `apis` | Using input blocks in API endpoints |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "MCP server and library for Xano development - XanoScript validation, Meta API, Run API, and CLI documentation",
   "type": "module",
   "main": "dist/lib.js",