@xano/developer-mcp 1.0.47 → 1.0.49

package/dist/xanoscript.js

@@ -178,7 +178,7 @@ export const XANOSCRIPT_DOCS_V2 = {
     },
     workspace: {
         file: "workspace.md",
-        applyTo: ["workspace.xs"],
+        applyTo: ["workspace/**/*.xs"],
         description: "Workspace-level settings: environment variables, preferences, realtime",
     },
 };

package/dist/xanoscript_docs/quickstart.md

@@ -611,6 +611,28 @@ stack {
 }
 ```
 
+### 13. Multiple constructs in one file
+Each `.xs` file must contain exactly **one** construct. Placing two constructs in the same file causes a parse error.
+
+```xs
+// ❌ Wrong - two constructs in one file
+function "helper_a" {
+  stack { ... }
+  response = $result
+}
+
+function "helper_b" {
+  stack { ... }
+  response = $result
+}
+```
+
+```
+// ✅ Correct - one construct per file
+// function/helper_a.xs  → contains only "helper_a"
+// function/helper_b.xs  → contains only "helper_b"
+```
+
 ---
 
 ## Related Topics

package/dist/xanoscript_docs/syntax.md

@@ -112,22 +112,42 @@ Working with...
 
 > **Note:** There is no `default` filter. Use conditional blocks or `first_notnull`/`first_notempty` instead.
 
-### String Concatenation with Filters
+### Parentheses and Filter Precedence
 
-When concatenating strings that use filters, wrap each filtered expression in parentheses:
+> **Rule:** Filters bind greedily to the left. Without parentheses, the parser extends the filter expression into the operator that follows — producing invalid or unexpected results. **When in doubt, wrap `$var|filter` in parentheses.**
+
+The filter `|` grabs everything to its right until it hits a boundary. This means `$arr|count > 3` is parsed as `$arr | (length > 3)` — treating `count > 3` as the filter argument, which is invalid.
 
 ```xs
-// ✅ Correct - parentheses around filtered expressions
+// ❌ Wrong — parser reads filter argument as "count == 0" (invalid)
+if ($arr|count == 0) { ... }
+
+// ❌ Wrong — parse error in concatenation
 var $message {
-  value = ($status|to_text) ~ ": " ~ ($data|json_encode)
+  value = $status|to_text ~ ": " ~ $data|json_encode
 }
+```
 
-// ❌ Incorrect - missing parentheses causes parse error
+```xs
+// ✅ Correct — evaluate filter first, then apply operator
+
+// ✅ Correct
+if (($arr|count) == 0) { ... }
+
+// ✅ Correct — wrap each filtered expression for concatenation
 var $message {
-  value = $status|to_text ~ ": " ~ $data|json_encode
+  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.
+
 ---
 
 ## Conditional Blocks
@@ -285,7 +305,7 @@ $db.post.date >=? $input.start_date
 | `unique` | `[1,1,2]\|unique` | `[1,2]` |
 | `flatten` | `[[1,2],[3]]\|flatten` | `[1,2,3]` |
 | `shuffle` | `[1,2,3]\|shuffle` | Random order |
-| `slice` | `[1,2,3,4]\|slice:1:2` | `[2,3]` |
+| `slice` | `[1,2,3,4]\|slice:1:2` | `[2,3]` — offset 1, length 2 |
 | `push` | `[1,2]\|push:3` | `[1,2,3]` |
 | `pop` | `[1,2,3]\|pop` | `3` |
 | `shift` | `[1,2,3]\|shift` | `1` |
@@ -331,6 +351,30 @@ Generate numeric ranges with the `..` operator:
 [1,2,3,4]|reduce:$$+$result:0               // 10
 ```
 
+### Array Element Access: `|get` vs `|slice`
+
+> **`|get:N`** returns a **single element** by zero-based index.
+> **`|slice:offset:length`** returns a **sub-array**, skipping `offset` elements and returning the next `length` elements.
+
+| Method | Use For | Example | Result |
+|--------|---------|---------|--------|
+| `\|get:N` | Single element by index (0-based) | `[10,20,30]\|get:0` | `10` |
+| `\|slice:offset:length` | Sub-array — skip N, take M | `[10,20,30,40]\|slice:1:2` | `[20,30]` |
+| `\|first` | First element | `[10,20,30]\|first` | `10` |
+| `\|last` | Last element | `[10,20,30]\|last` | `30` |
+
+```xs
+// Single element by index
+var $third { value = $items|get:2 }             // 0-based: 3rd element
+
+// Sub-array: skip first 10, return the next 5
+var $page { value = $items|slice:10:5 }
+
+// ⚠️ slice:offset:length — NOT slice:start:end
+// $arr|slice:2:3 → skip 2, return 3 elements (indices 2, 3, 4)
+// NOT "from index 2 to index 3"
+```
+
 ### Grouping & Indexing
 ```xs
 // Group by property

package/dist/xanoscript_docs/types.md

@@ -325,6 +325,19 @@ input {
 }
 ```
 
+### Required Fields Also Reject Empty Strings
+
+> **Important for testing:** A required `text` field (no `?` after the name) rejects both `null` **and** empty strings (`""`). Sending `""` triggers a platform-level validation error **before your stack runs** — your preconditions and custom error handling never execute.
+
+| Value sent | `text name` | `text? name` | `text name?` | `text? name?` |
+|------------|-------------|--------------|--------------|---------------|
+| `"Alice"` | ✅ valid | ✅ valid | ✅ valid | ✅ valid |
+| `""` | ❌ validation error | ❌ validation error | ✅ valid (empty) | ✅ valid (empty) |
+| `null` | ❌ validation error | ✅ valid | ❌ validation error | ✅ valid |
+| *(omitted)* | ❌ validation error | ❌ validation error | ✅ valid | ✅ valid |
+
+To test the "empty input" scenario for a text field, the field must be declared optional (`text name?`). Testing a required field with `""` will always produce a validation error — never your custom logic.
+
 ---
 
 ## Foreign Key References

package/dist/xanoscript_docs/unit-testing.md

@@ -35,6 +35,46 @@ function "<name>" {
 
 ---
 
+## Scope Limitations
+
+> **Unit tests can only access `$response`** — the value declared in the construct's `response = ...` field. Tests do **not** have access to intermediate stack variables.
+
+```xs
+function "calculate" {
+  input { int x }
+  stack {
+    var $doubled { value = $input.x * 2 }    // NOT accessible in tests
+    var $result  { value = $doubled + 1 }    // NOT accessible in tests
+  }
+  response = $result                          // This becomes $response in tests
+
+  test "doubles and adds one" {
+    input = { x: 5 }
+    // ✅ Can access $response (the declared response)
+    expect.to_equal ($response) { value = 11 }
+
+    // ❌ Stack variables are not in scope — this will fail
+    // expect.to_equal ($doubled) { value = 10 }
+  }
+}
+```
+
+To assert on intermediate values, expose them through the response:
+
+```xs
+response = { result: $result, doubled: $doubled }
+
+test "intermediate values" {
+  input = { x: 5 }
+  expect.to_equal ($response.doubled) { value = 10 }
+  expect.to_equal ($response.result) { value = 11 }
+}
+```
+
+> **Note:** Function stack variables (variables defined in other functions called via `function.run`) are also not accessible — tests are fully isolated to the construct's own declared response.
+
+---
+
 ## Basic Test
 
 ```xs
@@ -271,6 +311,65 @@ function "validate_age" {
 
 ---
 
+## Common Mistakes
+
+### Testing Required Fields with Empty Strings
+
+A required input field (no `?` after the name) rejects both `null` and empty strings at the platform level — **before your stack runs**. Writing a test that sends `""` to a required field will always get a validation error, never your custom precondition or error logic.
+
+❌ **Wrong — will always throw a validation error, not your custom error:**
+```xs
+function "create_user" {
+  input { text name }  // required: rejects null AND ""
+  stack {
+    precondition ($input.name != "") {
+      error_type = "inputerror"
+      error = "Name cannot be blank"
+    }
+  }
+  response = { ok: true }
+
+  // This test gets a validation error from the input layer, not "Name cannot be blank"
+  test "rejects empty name" {
+    input = { name: "" }
+    expect.to_throw { value = "Name cannot be blank" }
+  }
+}
+```
+
+✅ **Correct — use an optional field if you need to test the empty/omitted case:**
+```xs
+function "create_user" {
+  input { text name? }  // optional: accepts "", null, or omission
+  stack {
+    precondition ($input.name != null && $input.name != "") {
+      error_type = "inputerror"
+      error = "Name cannot be blank"
+    }
+  }
+  response = { ok: true }
+
+  test "rejects empty name" {
+    input = { name: "" }
+    expect.to_throw { value = "Name cannot be blank" }
+  }
+
+  test "rejects null name" {
+    input = { name: null }
+    expect.to_throw { value = "Name cannot be blank" }
+  }
+
+  test "accepts valid name" {
+    input = { name: "Alice" }
+    expect.to_equal ($response.ok) { value = true }
+  }
+}
+```
+
+For a full breakdown of what each required/optional/nullable combination accepts, see `xanoscript_docs({ topic: "types" })`.
+
+---
+
 ## Complete Example
 
 ```xs

package/dist/xanoscript_docs/workflow-tests.md

@@ -323,6 +323,7 @@ workflow_test "comprehensive_test" {
 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.
 
 ---
 

package/dist/xanoscript_docs/workspace.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "workspace.xs"
+applyTo: "workspace/**/*.xs"
 ---
 
 # Workspace Configuration
@@ -21,6 +21,7 @@ workspace "<name>" {
 ### Attributes
 | Attribute | Type | Required | Description |
 |-----------|------|----------|-------------|
+| `name` | text | **Yes** | Workspace name (matches the filename, e.g. `workspace/my_project.xs` → `"my_project"`) |
 | `description` | text | No | Human-readable workspace description |
 | `env` | object | No | Environment variable definitions |
 | `acceptance` | object | No | Terms and acceptance settings |
@@ -171,7 +172,7 @@ workspace "ecommerce_platform" {
 
 ## File Location
 
-Workspace configuration is stored in `workspace.xs` at the root of your project.
+Workspace configuration is stored as `workspace/<name>.xs`, where `<name>` matches the name declared in the `workspace` block.
 
 ```
 project/

package/package.json

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