@xano/developer-mcp 1.0.34 → 1.0.36

package/dist/xanoscript.js

@@ -16,6 +16,11 @@ export const XANOSCRIPT_DOCS_V2 = {
         applyTo: [],
         description: "XanoScript overview, workspace structure, and quick reference",
     },
+    cheatsheet: {
+        file: "cheatsheet.md",
+        applyTo: ["**/*.xs"],
+        description: "Quick reference for 20 most common XanoScript patterns",
+    },
     syntax: {
         file: "syntax.md",
         applyTo: ["**/*.xs"],
@@ -84,7 +89,32 @@ export const XANOSCRIPT_DOCS_V2 = {
     integrations: {
         file: "integrations.md",
         applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs"],
-        description: "Cloud storage, Redis, security, and external APIs",
+        description: "External service integrations index - see sub-topics for details",
+    },
+    "integrations/cloud-storage": {
+        file: "integrations/cloud-storage.md",
+        applyTo: [],
+        description: "AWS S3, Azure Blob, and GCP Storage operations",
+    },
+    "integrations/search": {
+        file: "integrations/search.md",
+        applyTo: [],
+        description: "Elasticsearch, OpenSearch, and Algolia search operations",
+    },
+    "integrations/redis": {
+        file: "integrations/redis.md",
+        applyTo: [],
+        description: "Redis caching, rate limiting, and queue operations",
+    },
+    "integrations/external-apis": {
+        file: "integrations/external-apis.md",
+        applyTo: [],
+        description: "HTTP requests with api.request patterns",
+    },
+    "integrations/utilities": {
+        file: "integrations/utilities.md",
+        applyTo: [],
+        description: "Local storage, email, zip, and Lambda utilities",
     },
     frontend: {
         file: "frontend.md",

package/dist/xanoscript.test.js

@@ -10,6 +10,7 @@ describe("xanoscript module", () => {
         it("should have all expected topics", () => {
             const expectedTopics = [
                 "readme",
+                "cheatsheet",
                 "syntax",
                 "quickstart",
                 "types",
@@ -24,6 +25,11 @@ describe("xanoscript module", () => {
                 "mcp-servers",
                 "testing",
                 "integrations",
+                "integrations/cloud-storage",
+                "integrations/search",
+                "integrations/redis",
+                "integrations/external-apis",
+                "integrations/utilities",
                 "frontend",
                 "run",
                 "addons",

package/dist/xanoscript_docs/README.md

@@ -108,7 +108,20 @@ $db.table.field     // Database field reference (in queries)
 $this               // Current item in loops/maps
 ```
 
-**Note:** `$response` is a reserved word and cannot be used as a variable name.
+**Reserved Variables:** The following cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`.
+
+### Type Names
+
+XanoScript uses specific type names:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | String (not "string") | `text name` |
+| `int` | Integer (not "integer") | `int count` |
+| `bool` | Boolean (not "boolean") | `bool active` |
+| `decimal` | Float/number | `decimal price` |
+| `type[]` | Array (not "array" or "list") | `text[] tags` |
+| `json` | Arbitrary JSON data | `json metadata` |
 
 ### Comments
 
@@ -164,69 +177,69 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
 
-| Topic        | Description                                          |
-| ------------ | ---------------------------------------------------- |
-| `quickstart` | Common patterns, quick examples, mistakes to avoid   |
-| `syntax`     | Expressions, operators, filters, system variables    |
-| `types`      | Data types, validation, input blocks                 |
-| `functions`  | Reusable function stacks, async, loops               |
-| `schema`     | Runtime schema parsing and validation                |
+| Topic        | Description                                          | Key Sections |
+| ------------ | ---------------------------------------------------- | ------------ |
+| `quickstart` | Common patterns, quick examples, mistakes to avoid   | Patterns, Common Mistakes |
+| `syntax`     | Expressions, operators, filters, system variables    | Filters (L179-275), Error Handling (L411-477) |
+| `types`      | Data types, validation, input blocks                 | Validation Filters, Input Blocks |
+| `functions`  | Reusable function stacks, async, loops               | Loops, Async Patterns |
+| `schema`     | Runtime schema parsing and validation                | parse.object, parse.array |
 
 ### Data
 
-| Topic       | Description                                                |
-| ----------- | ---------------------------------------------------------- |
-| `tables`    | Database schema definitions with indexes and relationships |
-| `database`  | All db.\* operations: query, get, add, edit, patch, delete |
-| `addons`    | Reusable subqueries for fetching related data              |
-| `streaming` | Streaming data from files, requests, and responses         |
+| Topic       | Description                                                | Key Sections |
+| ----------- | ---------------------------------------------------------- | ------------ |
+| `tables`    | Database schema definitions with indexes and relationships | Indexes, Foreign Keys |
+| `database`  | All db.\* operations: query, get, add, edit, patch, delete | Decision Tree (L11), Bulk Ops (L450-529) |
+| `addons`    | Reusable subqueries for fetching related data              | Usage Patterns |
+| `streaming` | Streaming data from files, requests, and responses         | File Streams, API Streams |
 
 ### APIs & Endpoints
 
-| Topic      | Description                                                     |
-| ---------- | --------------------------------------------------------------- |
-| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns |
-| `tasks`    | Scheduled and cron jobs                                         |
-| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP)  |
-| `realtime` | Real-time channels and events for push updates                  |
+| Topic      | Description                                                     | Key Sections |
+| ---------- | --------------------------------------------------------------- | ------------ |
+| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns | Decision Tree (L9), CRUD Examples (L220-350) |
+| `tasks`    | Scheduled and cron jobs                                         | Cron Syntax, Input Handling |
+| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP)  | Predefined Inputs, Event Types |
+| `realtime` | Real-time channels and events for push updates                  | Channels, Events |
 
 ### AI & Agents
 
-| Topic         | Description                                         |
-| ------------- | --------------------------------------------------- |
-| `agents`      | AI agent configuration with LLM providers and tools |
-| `tools`       | AI tools for agents and MCP servers                 |
-| `mcp-servers` | MCP server definitions exposing tools               |
+| Topic         | Description                                         | Key Sections |
+| ------------- | --------------------------------------------------- | ------------ |
+| `agents`      | AI agent configuration with LLM providers and tools | LLM Config, Tool Binding |
+| `tools`       | AI tools for agents and MCP servers                 | Tool Schema, Parameters |
+| `mcp-servers` | MCP server definitions exposing tools               | Server Config, Tool Exposure |
 
 ### Integrations
 
-| Topic          | Description                                       |
-| -------------- | ------------------------------------------------- |
-| `integrations` | Cloud storage, Redis, security, and external APIs |
+| Topic          | Description                                       | Sub-topics |
+| -------------- | ------------------------------------------------- | ---------- |
+| `integrations` | Cloud storage, Redis, security, and external APIs | cloud-storage, search, redis, external-apis, utilities |
 
 ### Configuration
 
-| Topic        | Description                                                            |
-| ------------ | ---------------------------------------------------------------------- |
-| `workspace`  | Workspace-level settings: environment variables, preferences, realtime |
-| `branch`     | Branch-level settings: middleware, history retention, visual styling   |
-| `middleware` | Request/response interceptors for functions, queries, tasks, and tools |
+| Topic        | Description                                                            | Key Sections |
+| ------------ | ---------------------------------------------------------------------- | ------------ |
+| `workspace`  | Workspace-level settings: environment variables, preferences, realtime | Env Variables, Preferences |
+| `branch`     | Branch-level settings: middleware, history retention, visual styling   | Middleware Config, History |
+| `middleware` | Request/response interceptors for functions, queries, tasks, and tools | Pre/Post Hooks |
 
 ### Development
 
-| Topic       | Description                                                |
-| ----------- | ---------------------------------------------------------- |
-| `testing`   | Unit tests, mocks, and assertions                          |
-| `debugging` | Logging, inspecting, and debugging XanoScript execution    |
-| `frontend`  | Static frontend development and deployment                 |
-| `run`       | Run job and service configurations for the Xano Job Runner |
+| Topic       | Description                                                | Key Sections |
+| ----------- | ---------------------------------------------------------- | ------------ |
+| `testing`   | Unit tests, mocks, and assertions                          | Test Syntax, Assertions |
+| `debugging` | Logging, inspecting, and debugging XanoScript execution    | debug.log, Inspection |
+| `frontend`  | Static frontend development and deployment                 | File Structure |
+| `run`       | Run job and service configurations for the Xano Job Runner | Jobs, Services |
 
 ### Best Practices
 
-| Topic         | Description                                                  |
-| ------------- | ------------------------------------------------------------ |
-| `performance` | Performance optimization best practices                      |
-| `security`    | Security best practices for authentication and authorization |
+| Topic         | Description                                                  | Key Sections |
+| ------------- | ------------------------------------------------------------ | ------------ |
+| `performance` | Performance optimization best practices                      | Caching, Query Optimization |
+| `security`    | Security best practices for authentication and authorization | Auth Patterns, Token Handling |
 
 ---
 

package/dist/xanoscript_docs/addons.md

@@ -254,3 +254,13 @@ addon/
 3. **Use appropriate return types** - `list`, `single`, `count`, `exists`
 4. **Limit nested queries** - Avoid N+1 query patterns
 5. **Document inputs** - Add descriptions to input fields
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `database` | db.query with addon usage |
+| `apis` | Using addons in API responses |
+| `functions` | Calling addons from functions |

package/dist/xanoscript_docs/agents.md

@@ -6,6 +6,10 @@ applyTo: "agent/**/*.xs"
 
 AI-powered agents that use LLMs to perform tasks autonomously.
 
+> **TL;DR:** Define with `agent "name" { llm = { type: "provider", system_prompt: "...", prompt: "..." } tools = [...] }`. Providers: `xano-free`, `openai`, `anthropic`, `google-genai`. Tools give agents capabilities.
+
+---
+
 ## Quick Reference
 
 ```xs
@@ -409,3 +413,14 @@ agent "Research Agent" {
 5. **Use environment variables** - Never hardcode API keys
 6. **Test with xano-free first** - Free for development
 7. **Validate external MCP servers** - Check server_details before using
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `tools` | Functions that agents can execute |
+| `mcp-servers` | MCP server configuration |
+| `triggers` | Agent triggers for events |
+| `security` | API key management |

package/dist/xanoscript_docs/apis.md

@@ -6,6 +6,30 @@ applyTo: "api/**/*.xs"
 
 HTTP endpoint definitions in XanoScript.
 
+> **TL;DR:** Use `query` to define endpoints. Require `api_group` for organization, `auth` for protected routes. Use appropriate HTTP verbs (GET/POST/PUT/PATCH/DELETE) and validate inputs with filters.
+
+## Choosing an Approach
+
+```
+Building...
+├── REST endpoint?
+│   ├── GET (read) → query with verb=GET
+│   ├── POST (create) → query with verb=POST
+│   ├── PUT/PATCH (update) → query with verb=PUT or verb=PATCH
+│   └── DELETE (remove) → query with verb=DELETE
+├── Protected endpoint?
+│   ├── Token auth? → auth = "user" (table with auth=true)
+│   └── Public? → omit auth attribute
+├── Input handling?
+│   ├── Path params? → query "path/{id}" + input { int id }
+│   ├── Query params? → GET with input block
+│   └── Body params? → POST/PUT/PATCH with input block
+├── Reusable logic?
+│   └── Use function, call with function.run
+└── Scheduled job?
+    └── Use task instead of query
+```
+
 ## Quick Reference
 
 ```xs
@@ -116,26 +140,18 @@ query "products" verb=GET {
 
 ## Input Block
 
-For complete type and filter reference, use `xanoscript_docs({ topic: "types" })`.
-
-### Empty and Single-Input Blocks
-
-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.
+> **Input block rules:** Empty and single-input blocks can be one-liners. Multiple inputs must be on separate lines. For complete type reference, validation filters, and schema definitions, see `xanoscript_docs({ topic: "types" })`.
 
 ```xs
-// OK - empty input
-query "health" verb=GET {
-  api_group = "System"
-  input {}
-  stack { ... }
-  response = { status: "ok" }
-}
-
-// OK - single input as one-liner
+// OK - empty or single input as one-liner
+input {}
 input { text query filters=trim }
 
-// WRONG - multiple inputs on one line will cause parsing errors
-input { text query filters=trim int limit }
+// Multiple inputs - each on own line
+input {
+  text query filters=trim
+  int limit?=10
+}
 ```
 
 ---
@@ -400,14 +416,7 @@ stack {
 
 ## Error Handling
 
-For complete error handling reference, use `xanoscript_docs({ topic: "syntax" })`.
-
-| Type           | HTTP Status |
-| -------------- | ----------- |
-| `inputerror`   | 400         |
-| `accessdenied` | 403         |
-| `notfound`     | 404         |
-| `standard`     | 500         |
+> **Error types:** Use `inputerror` (400), `accessdenied` (403), `notfound` (404), or `standard` (500). For complete error handling patterns including `precondition`, `try_catch`, and `throw`, see `xanoscript_docs({ topic: "syntax" })`.
 
 ---
 
@@ -437,3 +446,15 @@ When using `return = { type: "list", paging: {...} }`:
 4. **Paginate lists** - Never return unbounded result sets
 5. **Group by resource** - Organize endpoints in logical api groups
 6. **Use specific canonicals** - Prefix canonicals to avoid instance-level collisions (e.g., `myapp-users` not `users`)
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `types` | Input validation and filters |
+| `functions` | Reusable logic called from API stacks |
+| `database` | Database operations in API stacks |
+| `security` | Authentication and authorization |
+| `middleware` | Request interceptors |

package/dist/xanoscript_docs/cheatsheet.md

@@ -0,0 +1,252 @@
+---
+applyTo: "**/*.xs"
+---
+
+# XanoScript Cheat Sheet
+
+> **Purpose:** Quick reference for the 20 most common XanoScript patterns. For detailed documentation, use `xanoscript_docs({ topic: "<topic>" })`.
+
+## Variable Declaration
+
+```xs
+var $name { value = "initial" }
+var $count { value = 0 }
+var $items { value = [] }
+var $data { value = { key: "value" } }
+```
+
+## Conditionals
+
+```xs
+conditional {
+  if ($input.age >= 18) {
+    var $status { value = "adult" }
+  }
+  elseif ($input.age >= 13) {
+    var $status { value = "teen" }
+  }
+  else {
+    var $status { value = "child" }
+  }
+}
+```
+
+> **Note:** Use `elseif` (one word), not `else if`.
+
+## Loops
+
+```xs
+// For each loop
+each ($input.items as $item) {
+  debug.log { value = $item.name }
+}
+
+// While loop (must be inside stack block)
+stack {
+  var $counter { value = 0 }
+  while ($counter < 10) {
+    each {
+      var.update $counter { value = $counter + 1 }
+    }
+  }
+}
+
+// Map/filter for transformations
+var $names { value = $items|map:$$.name }
+var $active { value = $items|filter:$$.is_active }
+```
+
+## Database CRUD
+
+```xs
+// Get single record by field
+db.get "user" {
+  field_name = "id"
+  field_value = $input.user_id
+} as $user
+
+// Query with filters
+db.query "user" {
+  where = $db.user.is_active == true
+  sort = { created_at: "desc" }
+  return = { type: "list", paging: { page: 1, per_page: 25 } }
+} as $users
+
+// Insert record
+db.add "user" {
+  data = { name: $input.name, email: $input.email, created_at: now }
+} as $new_user
+
+// Update record
+db.edit "user" {
+  field_name = "id"
+  field_value = $input.user_id
+  data = { name: $input.name, updated_at: now }
+}
+
+// Delete record
+db.del "user" { field_name = "id", field_value = $input.user_id }
+```
+
+## API Requests
+
+```xs
+api.request {
+  url = "https://api.example.com/endpoint"
+  method = "POST"
+  params = { key: "value" }              // Note: "params" for body, NOT "body"
+  headers = [
+    "Content-Type: application/json",
+    "Authorization: Bearer " ~ $env.API_KEY
+  ]
+  timeout = 30
+} as $api_result
+
+// Response structure:
+// $api_result.response.status  → HTTP status code (200, 404, etc.)
+// $api_result.response.result  → Parsed response body
+// $api_result.response.headers → Response headers
+```
+
+## Error Handling
+
+```xs
+// Precondition (stops execution if false)
+precondition ($input.id > 0) {
+  error_type = "inputerror"
+  error = "ID must be positive"
+}
+
+// Try-catch
+try_catch {
+  try {
+    // risky operation
+  }
+  catch {
+    debug.log { value = "Operation failed" }
+  }
+}
+
+// Throw custom error
+throw {
+  name = "ValidationError"
+  value = "Custom error message"
+}
+```
+
+## Error Types
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 | Invalid input data |
+| `accessdenied` | 403 | Authorization failure |
+| `notfound` | 404 | Resource doesn't exist |
+| `standard` | 500 | General errors |
+
+## Common Filters
+
+```xs
+// String
+$text|trim                    // Remove whitespace
+$text|to_lower                // Lowercase
+$text|to_upper                // Uppercase
+$text|substr:0:10             // Substring
+$text|split:","               // Split to array
+$text|contains:"x"            // Check contains → bool
+
+// Array
+$arr|first                    // First element
+$arr|last                     // Last element
+$arr|count                    // Length
+$arr|map:$$.field             // Transform elements
+$arr|filter:$$.active         // Filter by condition
+$arr|find:$$.id == 5          // Find first match
+
+// Type conversion
+$val|to_text                  // To string
+$val|to_int                   // To integer
+$val|to_bool                  // To boolean
+$val|json_encode              // To JSON string
+$text|json_decode             // From JSON string
+
+// Object
+$obj|get:"key"                // Get property
+$obj|get:"key":"default"      // Get with default
+$obj|set:"key":"value"        // Set property
+$obj|has:"key"                // Check key exists
+
+// Null handling
+$val|first_notnull:"default"  // Default if null
+$val ?? "default"             // Nullish coalescing
+
+// Math
+$num|round:2                  // Round to 2 decimals
+$num|abs                      // Absolute value
+```
+
+## Authentication Check
+
+```xs
+precondition ($auth.id != null) {
+  error_type = "accessdenied"
+  error = "Authentication required"
+}
+```
+
+## Function Call
+
+```xs
+function.run "my_function" {
+  input = { param1: "value" }
+} as $result
+```
+
+## String Concatenation
+
+```xs
+// Basic
+var $msg { value = "Hello, " ~ $input.name ~ "!" }
+
+// With filters - MUST use parentheses
+var $msg { value = ($status|to_text) ~ ": " ~ ($data|json_encode) }
+```
+
+## Common Type Names
+
+| Use This | Not This |
+|----------|----------|
+| `text` | string |
+| `int` | integer |
+| `bool` | boolean |
+| `decimal` | float, number |
+| `type[]` | array, list |
+
+## Reserved Variables (Cannot Use)
+
+`$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`
+
+## Input Block Syntax
+
+```xs
+input {
+  text name                    // Required
+  text nickname?               // Optional (can be omitted)
+  text role?="user"            // Optional with default
+  email contact filters=trim   // With filters
+  text[] tags                  // Array type
+  object address {             // Nested object
+    schema {
+      text street
+      text city
+    }
+  }
+}
+```
+
+---
+
+**Related:** For detailed documentation, use:
+- `xanoscript_docs({ topic: "quickstart" })` - Common patterns and mistakes
+- `xanoscript_docs({ topic: "syntax" })` - All filters and operators
+- `xanoscript_docs({ topic: "database" })` - All db.* operations
+- `xanoscript_docs({ topic: "types" })` - Type validation and schemas

package/dist/xanoscript_docs/database.md

@@ -6,6 +6,29 @@ applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs, tool/**/*.xs"
 
 Complete reference for XanoScript database operations.
 
+> **TL;DR:** Use `db.get` for single record by ID, `db.query` for filtered lists, `db.has` to check existence, `db.add` to insert, `db.edit` for inline updates, `db.patch` for dynamic fields, `db.del` to delete.
+
+## Choosing an Operation
+
+```
+Need to...
+├── Read data?
+│   ├── Single record by ID? → db.get
+│   ├── Check if exists? → db.has
+│   └── Filtered list? → db.query
+├── Write data?
+│   ├── New record? → db.add
+│   ├── Update known fields? → db.edit
+│   └── Update dynamic fields? → db.patch
+├── Delete data?
+│   ├── Single record? → db.del
+│   └── All records? → db.truncate
+└── Complex query?
+    ├── Join tables? → db.query with join
+    ├── Aggregate? → db.query with evals
+    └── Transaction? → db.transaction
+```
+
 ## Quick Reference
 
 | Operation        | Purpose                       | Returns                  |
@@ -612,3 +635,17 @@ try_catch {
 5. **Use null-safe operators** - `==?` for optional filters
 6. **Use bulk operations for batch processing** - More efficient than loops
 7. **Handle deadlocks gracefully** - Implement retry logic for concurrent writes
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `tables` | Database schema definitions with indexes and relationships |
+| `syntax` | Query filters, operators, and expressions |
+| `quickstart` | Common CRUD patterns and examples |
+| `addons` | Reusable subqueries for fetching related data |
+| `performance` | Query optimization best practices |