@xano/developer-mcp 1.0.20 → 1.0.21

package/dist/index.js

@@ -134,6 +134,21 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
         description: "Streaming data from files, requests, and responses",
     },
+    middleware: {
+        file: "middleware.md",
+        applyTo: ["middleware/**/*.xs"],
+        description: "Request/response interceptors for functions, queries, tasks, and tools",
+    },
+    branch: {
+        file: "branch.md",
+        applyTo: ["branch.xs"],
+        description: "Branch-level settings: middleware, history retention, visual styling",
+    },
+    workspace: {
+        file: "workspace.md",
+        applyTo: ["workspace.xs"],
+        description: "Workspace-level settings: environment variables, preferences, realtime",
+    },
 };
 // =============================================================================
 // Path Resolution

package/dist/templates/init-workspace.js

@@ -260,10 +260,10 @@ const response = await fetch(
 For writing XanoScript code, use:
 
 - \`xanoscript_docs()\` - Full documentation index
-- \`xanoscript_docs({ keyword: "function" })\` - Function syntax
-- \`xanoscript_docs({ keyword: "table" })\` - Table schema syntax
-- \`xanoscript_docs({ keyword: "api_query" })\` - API endpoint syntax
-- \`xanoscript_docs({ keyword: "syntax" })\` - Language reference
+- \`xanoscript_docs({ topic: "functions" })\` - Function syntax
+- \`xanoscript_docs({ topic: "tables" })\` - Table schema syntax
+- \`xanoscript_docs({ topic: "apis" })\` - API endpoint syntax
+- \`xanoscript_docs({ topic: "syntax" })\` - Language reference
 
 ## Validating XanoScript
 

package/dist/templates/xanoscript-index.d.ts

@@ -1,9 +1,11 @@
 /**
  * Template for xanoscript_docs index documentation
  * Edit this file to update the XanoScript documentation index
+ *
+ * NOTE: This template is currently unused. The actual documentation is served
+ * directly from the XANOSCRIPT_DOCS_V2 config in index.ts.
  */
 export interface XanoscriptIndexParams {
     version: string;
-    aliasLookup: Record<string, string[]>;
 }
 export declare function generateXanoscriptIndexTemplate(params: XanoscriptIndexParams): string;

package/dist/templates/xanoscript-index.js

@@ -1,69 +1,72 @@
 /**
  * Template for xanoscript_docs index documentation
  * Edit this file to update the XanoScript documentation index
+ *
+ * NOTE: This template is currently unused. The actual documentation is served
+ * directly from the XANOSCRIPT_DOCS_V2 config in index.ts.
  */
 export function generateXanoscriptIndexTemplate(params) {
-    const { version, aliasLookup } = params;
-    const formatRow = (keyword, description) => {
-        const aliases = aliasLookup[keyword]?.slice(0, 3).join(", ") || "";
-        return `| \`${keyword}\` | ${aliases ? aliases : "-"} | ${description} |`;
-    };
+    const { version } = params;
     return `# XanoScript Documentation Index
 Version: ${version}
 
-Use \`xanoscript_docs\` with a keyword to retrieve documentation.
+Use \`xanoscript_docs({ topic: "<topic>" })\` to retrieve documentation.
 
-## Core Concepts
-These return guidelines + examples for writing XanoScript code.
+## Core Language
+| Topic | Description |
+|-------|-------------|
+| \`syntax\` | Expressions, operators, filters, system variables |
+| \`types\` | Data types, validation, input blocks |
+| \`functions\` | Reusable function stacks, async, loops |
+| \`schema\` | Runtime schema parsing and validation |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("function", "Custom reusable functions in `functions/`")}
-${formatRow("api_query", "HTTP API endpoints in `apis/`")}
-${formatRow("table", "Database table schemas in `tables/`")}
-${formatRow("task", "Scheduled background tasks in `tasks/`")}
-${formatRow("triggers", "Event-driven handlers in `triggers/`")}
-${formatRow("tool", "AI-callable tools in `tools/`")}
-${formatRow("agent", "AI agents in `agents/`")}
-${formatRow("mcp_server", "MCP servers in `mcp_servers/`")}
+## 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 |
 
-## Language Reference
-Core syntax and operators.
+## 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 |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("syntax", "Complete XanoScript syntax (stack, var, conditional, foreach, etc.)")}
-${formatRow("expressions", "Pipe operators and filters (string, math, array, date)")}
-${formatRow("input", "Input definition syntax (types, filters, validation)")}
-${formatRow("db_query", "Database query patterns (query, add, edit, delete)")}
-${formatRow("query_filter", "WHERE clause and filter syntax")}
+## 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 |
 
-## Development Workflows
-AI agent development strategies and phases.
+## Integrations
+| Topic | Description |
+|-------|-------------|
+| \`integrations\` | Cloud storage, Redis, security, and external APIs |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("workflow", "Overall XanoScript development workflow")}
-${formatRow("function_workflow", "AI workflow for creating functions")}
-${formatRow("api_workflow", "AI workflow for creating API endpoints")}
-${formatRow("table_workflow", "AI workflow for creating tables")}
-${formatRow("task_workflow", "AI workflow for creating tasks")}
+## 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 |
 
-## Specialized Topics
+## 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 |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("addons", "Reusable subqueries for related data")}
-${formatRow("debugging", "Logging and debugging tools")}
-${formatRow("frontend", "Frontend development with Xano")}
-${formatRow("lovable", "Building from Lovable-generated websites")}
-${formatRow("performance", "Performance optimization best practices")}
-${formatRow("realtime", "Real-time channels and events")}
-${formatRow("schema", "Runtime schema parsing and validation")}
-${formatRow("security", "Security best practices")}
-${formatRow("streaming", "Streaming data from files and responses")}
-${formatRow("testing", "Unit testing XanoScript code")}
-${formatRow("tips", "Tips and tricks")}
-${formatRow("run", "Run job and service configurations")}
+## Best Practices
+| Topic | Description |
+|-------|-------------|
+| \`performance\` | Performance optimization best practices |
+| \`security\` | Security best practices for authentication and authorization |
 `;
 }

package/dist/xanoscript_docs/README.md

@@ -15,6 +15,10 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 | `tool` | `tools/**/*.xs` | Tools for AI agents |
 | `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
 | `addon` | `addons/*.xs` | Subqueries for related data |
+| `middleware` | `middleware/**/*.xs` | Request/response interceptors |
+| `branch` | `branch.xs` | Branch-level configuration |
+| `workspace` | `workspace.xs` | Workspace-level configuration |
+| `realtime_channel` | Configuration | Realtime channel settings |
 
 **Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
 
@@ -22,6 +26,8 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 
 ```
 project/
+├── workspace.xs         // Workspace configuration (env vars, preferences)
+├── branch.xs            // Branch configuration (middleware, history)
 ├── tables/              // Database table schemas
 ├── functions/           // Reusable functions (supports subfolders)
 ├── apis/
@@ -31,6 +37,7 @@ project/
 ├── agents/              // AI agents
 ├── tools/               // AI tools
 ├── mcp_servers/         // MCP server definitions
+├── middleware/          // Request/response interceptors
 ├── addons/              // Query addons
 ├── static/              // Frontend files (HTML, CSS, JS)
 └── run/                 // Job and service configurations
@@ -103,54 +110,61 @@ This helps AI tools apply the correct documentation based on the file being edit
 
 ## Documentation Index
 
-Use `xanoscript_docs({ keyword: "<keyword>" })` to retrieve documentation.
+Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Syntax Reference | `syntax` | Expressions, operators, filters, system variables |
-| Types & Inputs | `input` | Data types, validation, input blocks |
-| Functions | `function` | Reusable function stacks, async, loops |
-| Schema | `schema` | Runtime schema parsing and validation |
+| Topic | Description |
+|-------|-------------|
+| `syntax` | Expressions, operators, filters, system variables |
+| `types` | Data types, validation, input blocks |
+| `functions` | Reusable function stacks, async, loops |
+| `schema` | Runtime schema parsing and validation |
 
 ### Data
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Tables | `table` | Database schema definitions |
-| Database Operations | `db_query` | Query, add, edit, delete, bulk operations |
-| Addons | `addon` | Reusable subqueries for related data |
-| Streaming | `streaming` | Stream processing for large files |
+| 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 |
 
 ### APIs & Endpoints
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| APIs | `api_query` | HTTP endpoint definitions |
-| Tasks | `task` | Scheduled jobs |
-| Triggers | `trigger` | Event-driven handlers |
-| Realtime | `realtime` | Push events and channels |
+| 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 |
 
 ### AI & Agents
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Agents | `agent` | AI agent configuration |
-| Tools | `tool` | AI tools for agents |
-| MCP Servers | `mcp_server` | Model Context Protocol servers |
+| 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 |
 
 ### Integrations
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Integrations | `integrations` | Cloud storage, search, Redis, zip, Lambda |
+| Topic | Description |
+|-------|-------------|
+| `integrations` | Cloud storage, Redis, security, and external APIs |
+
+### 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 |
 
 ### Development
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Testing | `testing` | Unit tests and mocking |
-| Debugging | `debugging` | Logging and inspection tools |
-| Frontend | `frontend` | Static frontend development |
-| Run | `run` | Job and service configurations |
+| 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 |
 
 ### Best Practices
-| Topic | Keyword | Description |
-|-------|---------|-------------|
-| Performance | `performance` | Query optimization, caching, parallelism |
-| Security | `security` | Authentication, authorization, encryption |
+| Topic | Description |
+|-------|-------------|
+| `performance` | Performance optimization best practices |
+| `security` | Security best practices for authentication and authorization |

package/dist/xanoscript_docs/apis.md

@@ -86,7 +86,7 @@ query "products" verb=GET {
 
 ## Input Block
 
-For complete type and filter reference, use `xanoscript_docs({ keyword: "input" })`.
+For complete type and filter reference, use `xanoscript_docs({ topic: "types" })`.
 
 ### Empty Input Blocks
 
@@ -345,11 +345,14 @@ stack {
 
 ## Error Handling
 
-For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
+For complete error handling reference, use `xanoscript_docs({ topic: "syntax" })`.
 
 | Type | HTTP Status |
 |------|-------------|
-| `inputerror` | 400 | `accessdenied` | 403 | `notfound` | 404 | `standard` | 500 |
+| `inputerror` | 400 |
+| `accessdenied` | 403 |
+| `notfound` | 404 |
+| `standard` | 500 |
 
 ---
 

package/dist/xanoscript_docs/branch.md

@@ -0,0 +1,239 @@
+---
+applyTo: "branch.xs"
+---
+
+# Branch Configuration
+
+Configure branch-level settings including middleware, history retention, and visual styling.
+
+## Quick Reference
+
+```xs
+branch "<name>" {
+  color = "#hex"
+  description = "Branch description"
+  middleware = { ... }
+  history = { ... }
+}
+```
+
+### Attributes
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `color` | text | Yes | Hex color code for branch identification |
+| `description` | text | No | Human-readable branch description |
+| `middleware` | object | No | Pre/post middleware configuration |
+| `history` | object | No | Request history retention settings |
+
+---
+
+## Basic Structure
+
+```xs
+branch "production" {
+  color = "#22c55e"
+  description = "Production environment"
+}
+```
+
+---
+
+## Middleware Configuration
+
+Configure middleware to run before (pre) and after (post) different construct types.
+
+### Syntax
+
+```xs
+branch "production" {
+  color = "#22c55e"
+
+  middleware = {
+    function: {
+      pre: ["auth_check", "rate_limit"],
+      post: ["audit_log"]
+    },
+    query: {
+      pre: ["auth_check", "rate_limit"],
+      post: ["audit_log", "cache_response"]
+    },
+    task: {
+      pre: ["task_lock"],
+      post: ["task_cleanup"]
+    },
+    tool: {
+      pre: ["tool_auth"],
+      post: ["tool_log"]
+    }
+  }
+}
+```
+
+### Middleware Targets
+
+| Target | Description |
+|--------|-------------|
+| `function` | Applies to all function calls |
+| `query` | Applies to all API endpoints |
+| `task` | Applies to scheduled tasks |
+| `tool` | Applies to AI agent tools |
+
+### Pre vs Post Middleware
+
+| Type | Execution | Use Cases |
+|------|-----------|-----------|
+| `pre` | Before main logic | Authentication, rate limiting, validation |
+| `post` | After main logic | Logging, caching, response transformation |
+
+---
+
+## History Configuration
+
+Control how many historical executions are retained for debugging and auditing.
+
+### Syntax
+
+```xs
+branch "production" {
+  color = "#22c55e"
+
+  history = {
+    function: 100,
+    query: 1000,
+    task: 100,
+    tool: 100,
+    trigger: 100,
+    middleware: 10
+  }
+}
+```
+
+### History Values
+
+| Value | Description |
+|-------|-------------|
+| `false` | Disable history (no retention) |
+| `10` | Keep last 10 executions |
+| `100` | Keep last 100 executions |
+| `1000` | Keep last 1000 executions |
+| `10000` | Keep last 10000 executions |
+| `"all"` | Keep all executions (use with caution) |
+
+### History Targets
+
+| Target | Description |
+|--------|-------------|
+| `function` | Function execution history |
+| `query` | API endpoint request history |
+| `task` | Scheduled task execution history |
+| `tool` | AI tool invocation history |
+| `trigger` | Trigger execution history |
+| `middleware` | Middleware execution history |
+
+---
+
+## Common Patterns
+
+### Development Branch
+
+```xs
+branch "development" {
+  color = "#3b82f6"
+  description = "Development environment with full debugging"
+
+  history = {
+    function: "all",
+    query: "all",
+    task: "all",
+    tool: "all",
+    trigger: "all",
+    middleware: "all"
+  }
+}
+```
+
+### Staging Branch
+
+```xs
+branch "staging" {
+  color = "#f59e0b"
+  description = "Staging environment for testing"
+
+  middleware = {
+    query: {
+      pre: ["auth_check"],
+      post: ["audit_log"]
+    }
+  }
+
+  history = {
+    function: 1000,
+    query: 1000,
+    task: 100,
+    tool: 100,
+    trigger: 100,
+    middleware: 100
+  }
+}
+```
+
+### Production Branch
+
+```xs
+branch "production" {
+  color = "#22c55e"
+  description = "Production environment"
+
+  middleware = {
+    function: {
+      pre: ["auth_check", "rate_limit"],
+      post: ["audit_log"]
+    },
+    query: {
+      pre: ["auth_check", "rate_limit", "security_check"],
+      post: ["audit_log", "cache_response"]
+    },
+    task: {
+      pre: ["task_lock"],
+      post: ["audit_log"]
+    },
+    tool: {
+      pre: ["auth_check"],
+      post: ["audit_log"]
+    }
+  }
+
+  history = {
+    function: 100,
+    query: 100,
+    task: 100,
+    tool: 100,
+    trigger: 100,
+    middleware: false
+  }
+}
+```
+
+---
+
+## File Location
+
+Branch configuration files are typically named `branch.xs` and placed at the workspace root or in a dedicated configuration directory.
+
+```
+project/
+├── branch.xs              // Branch configuration
+├── tables/
+├── functions/
+└── apis/
+```
+
+---
+
+## Best Practices
+
+1. **Use descriptive colors** - Green for production, blue for development, yellow for staging
+2. **Limit production history** - Excessive history impacts performance and storage
+3. **Apply security middleware in production** - Rate limiting, auth checks, audit logging
+4. **Disable middleware history in production** - Reduces noise and storage
+5. **Enable full history in development** - Aids debugging and testing

package/dist/xanoscript_docs/functions.md

@@ -72,7 +72,7 @@ Reference with path: `function.run "math/add" { ... }`
 
 ## Input Block
 
-For complete type and filter reference, use `xanoscript_docs({ keyword: "input" })`.
+For complete type and filter reference, use `xanoscript_docs({ topic: "types" })`.
 
 ```xs
 input {
@@ -188,7 +188,7 @@ stack {
 
 ### Error Handling
 
-For complete error handling reference (preconditions, try-catch, throw, early return), use `xanoscript_docs({ keyword: "syntax" })`.
+For complete error handling reference (preconditions, try-catch, throw, early return), use `xanoscript_docs({ topic: "syntax" })`.
 
 ---
 

package/dist/xanoscript_docs/middleware.md

@@ -0,0 +1,321 @@
+---
+applyTo: "middleware/**/*.xs"
+---
+
+# Middleware
+
+Middleware intercepts and processes requests before and after your functions, queries, tasks, and tools execute.
+
+## Quick Reference
+
+```xs
+middleware "<name>" {
+  description = "What this middleware does"
+  exception_policy = "silent" | "rethrow" | "critical"
+  response_strategy = "merge" | "replace"
+  input { ... }
+  stack { ... }
+  response = $result
+}
+```
+
+### Required Blocks
+| Block | Purpose |
+|-------|---------|
+| `input` | Define parameters passed to middleware |
+| `stack` | Processing logic |
+| `response` | Output returned to caller |
+
+### Optional Attributes
+| Attribute | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `description` | text | - | Documents middleware purpose |
+| `exception_policy` | `silent`, `rethrow`, `critical` | `rethrow` | How to handle errors |
+| `response_strategy` | `merge`, `replace` | `merge` | How response combines with original |
+
+---
+
+## Basic Structure
+
+```xs
+middleware "log_request" {
+  description = "Logs all incoming requests"
+
+  input {
+    json request_data
+  }
+
+  stack {
+    debug.log {
+      value = {
+        timestamp: now,
+        data: $input.request_data
+      }
+    }
+  }
+
+  response = null
+}
+```
+
+---
+
+## Exception Policies
+
+Control how middleware handles errors:
+
+### silent
+Errors are caught and ignored. Execution continues normally.
+
+```xs
+middleware "optional_enrichment" {
+  exception_policy = "silent"
+
+  input {
+    int user_id
+  }
+
+  stack {
+    // If this fails, request continues without enrichment
+    api.call "external_service" {
+      url = "https://api.example.com/enrich/" ~ $input.user_id
+    } as $enriched
+  }
+
+  response = $enriched
+}
+```
+
+### rethrow (default)
+Errors are passed through to the caller. Standard error handling applies.
+
+```xs
+middleware "validate_token" {
+  exception_policy = "rethrow"
+
+  input {
+    text token
+  }
+
+  stack {
+    precondition ($input.token|strlen > 0) {
+      error_type = "accessdenied"
+      error = "Token required"
+    }
+  }
+
+  response = { valid: true }
+}
+```
+
+### critical
+Errors are treated as critical failures. Request is immediately terminated.
+
+```xs
+middleware "security_check" {
+  exception_policy = "critical"
+
+  input {
+    text ip_address
+  }
+
+  stack {
+    db.query "blocked_ips" {
+      where = $db.blocked_ips.ip == $input.ip_address
+      return = { type: "exists" }
+    } as $is_blocked
+
+    precondition (!$is_blocked) {
+      error_type = "accessdenied"
+      error = "Access denied"
+    }
+  }
+
+  response = { allowed: true }
+}
+```
+
+---
+
+## Response Strategies
+
+Control how middleware response combines with the original response:
+
+### merge (default)
+Middleware response is merged with original response.
+
+```xs
+middleware "add_metadata" {
+  response_strategy = "merge"
+
+  input {
+  }
+
+  stack {
+    var $meta {
+      value = {
+        server_time: now,
+        version: "1.0.0"
+      }
+    }
+  }
+
+  response = { _meta: $meta }
+}
+// Original: { data: [...] }
+// Result: { data: [...], _meta: { server_time: ..., version: "1.0.0" } }
+```
+
+### replace
+Middleware response completely replaces original response.
+
+```xs
+middleware "transform_response" {
+  response_strategy = "replace"
+
+  input {
+    json original_response
+  }
+
+  stack {
+    var $transformed {
+      value = {
+        success: true,
+        payload: $input.original_response
+      }
+    }
+  }
+
+  response = $transformed
+}
+```
+
+---
+
+## Common Patterns
+
+### Request Logging
+
+```xs
+middleware "audit_log" {
+  description = "Logs all API requests for audit trail"
+  exception_policy = "silent"
+
+  input {
+    text endpoint
+    text method
+    json request_body?
+    int user_id?
+  }
+
+  stack {
+    db.add "audit_log" {
+      data = {
+        endpoint: $input.endpoint,
+        method: $input.method,
+        request_body: $input.request_body,
+        user_id: $input.user_id,
+        ip_address: $env.$remote_ip,
+        created_at: now
+      }
+    }
+  }
+
+  response = null
+}
+```
+
+### Rate Limiting
+
+```xs
+middleware "rate_limit" {
+  description = "Enforces rate limits per user"
+  exception_policy = "rethrow"
+
+  input {
+    int user_id
+    int max_requests?=100
+    int window_seconds?=60
+  }
+
+  stack {
+    var $key { value = "ratelimit:" ~ $input.user_id }
+
+    redis.incr {
+      key = $key
+    } as $count
+
+    conditional {
+      if ($count == 1) {
+        redis.expire {
+          key = $key
+          seconds = $input.window_seconds
+        }
+      }
+    }
+
+    precondition ($count <= $input.max_requests) {
+      error_type = "standard"
+      error = "Rate limit exceeded"
+    }
+  }
+
+  response = { remaining: $input.max_requests - $count }
+}
+```
+
+### Response Caching
+
+```xs
+middleware "cache_response" {
+  description = "Caches responses in Redis"
+  exception_policy = "silent"
+
+  input {
+    text cache_key
+    int ttl_seconds?=300
+    json response_data
+  }
+
+  stack {
+    redis.set {
+      key = $input.cache_key
+      value = $input.response_data|json_encode
+      expire = $input.ttl_seconds
+    }
+  }
+
+  response = null
+}
+```
+
+---
+
+## Applying Middleware
+
+Middleware is configured at the branch level. See `xanoscript_docs({ topic: "branch" })` for configuration details.
+
+```xs
+branch "production" {
+  middleware = {
+    query: {
+      pre: ["validate_token", "rate_limit"],
+      post: ["audit_log", "cache_response"]
+    },
+    function: {
+      pre: ["validate_token"],
+      post: ["audit_log"]
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Keep middleware focused** - Each middleware should do one thing well
+2. **Use appropriate exception policies** - Critical for security, silent for optional enrichment
+3. **Consider performance** - Middleware runs on every request
+4. **Log failures** - Even silent failures should be logged for debugging
+5. **Test independently** - Middleware should be testable in isolation

package/dist/xanoscript_docs/realtime.md

@@ -42,11 +42,123 @@ api.realtime_event {
 
 ---
 
+## Realtime Channel Configuration
+
+Define channel settings at the workspace level using `realtime_channel`.
+
+```xs
+realtime_channel "<channel_pattern>" {
+  description = "Channel description"
+  active = true
+
+  public_messaging = {
+    active: true,
+    auth: false
+  }
+
+  private_messaging = {
+    active: true,
+    auth: true
+  }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: true,
+    message_history: 100,
+    auth_channel: true,
+    presence: true
+  }
+}
+```
+
+### Channel Configuration Options
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `description` | text | Human-readable channel description |
+| `active` | boolean | Enable/disable the channel |
+
+### Messaging Options
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `public_messaging.active` | boolean | Allow public messages |
+| `public_messaging.auth` | boolean | Require authentication for public messages |
+| `private_messaging.active` | boolean | Allow private messages |
+| `private_messaging.auth` | boolean | Require authentication for private messages |
+
+### Settings Options
+
+| Setting | Type | Values | Description |
+|---------|------|--------|-------------|
+| `anonymous_clients` | boolean | true/false | Allow unauthenticated clients |
+| `nested_channels` | boolean | true/false | Allow sub-channel patterns |
+| `message_history` | number | 0, 25, 50, 100, 250, 1000 | Messages to retain |
+| `auth_channel` | boolean | true/false | Require channel-level auth |
+| `presence` | boolean | true/false | Track client presence |
+
+### Example Configurations
+
+```xs
+// Chat room channel with presence
+realtime_channel "room:*" {
+  description = "Chat room channels"
+  active = true
+
+  public_messaging = { active: true, auth: true }
+  private_messaging = { active: true, auth: true }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: false,
+    message_history: 100,
+    auth_channel: true,
+    presence: true
+  }
+}
+
+// Global announcements (read-only for clients)
+realtime_channel "announcements" {
+  description = "System-wide announcements"
+  active = true
+
+  public_messaging = { active: true, auth: false }
+  private_messaging = { active: false, auth: false }
+
+  settings = {
+    anonymous_clients: true,
+    nested_channels: false,
+    message_history: 25,
+    auth_channel: false,
+    presence: false
+  }
+}
+
+// User-specific notifications
+realtime_channel "user:*" {
+  description = "User notification channels"
+  active = true
+
+  public_messaging = { active: false, auth: false }
+  private_messaging = { active: true, auth: true }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: false,
+    message_history: 50,
+    auth_channel: true,
+    presence: false
+  }
+}
+```
+
+---
+
 ## Channel Patterns
 
 ### Public Channels
 
-Available to all authenticated clients.
+Accessible to all authenticated clients. When you send to a public channel, all clients currently subscribed to that channel receive the message.
 
 ```xs
 // Global announcements

package/dist/xanoscript_docs/tools.md

@@ -62,7 +62,7 @@ tool "get_user_by_email" {
 
 ## Input Block
 
-For complete type reference, use `xanoscript_docs({ keyword: "input" })`. For tools, input `description` fields are sent to the AI, so write them clearly:
+For complete type reference, use `xanoscript_docs({ topic: "types" })`. For tools, input `description` fields are sent to the AI, so write them clearly:
 
 ```xs
 input {

package/dist/xanoscript_docs/types.md

@@ -62,7 +62,13 @@ input {
 
 ### Empty Input Blocks
 
-**CRITICAL:** When an input block has no parameters, the braces MUST be on separate lines. This is a strict syntax requirement - `input {}` on a single line will cause parsing errors.
+**SYNTAX REQUIREMENT:** When an input block has no parameters, the braces MUST be on separate lines.
+
+**Why:** The XanoScript parser requires whitespace between braces to distinguish empty input blocks from inline objects.
+
+**Impact:** Using `input {}` on a single line will cause:
+- Syntax error during compilation
+- Function/API/tool will fail to deploy
 
 ```xs
 // CORRECT - braces on separate lines
@@ -109,6 +115,21 @@ email contact filters=trim|lower {
 password secret filters=min:8          // Minimum 8 characters
 ```
 
+#### Password Complexity Filters
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `min:<n>` | Minimum total length | `password pwd filters=min:8` |
+| `minAlpha:<n>` | Minimum letters (a-zA-Z) | `password pwd filters=minAlpha:2` |
+| `minLowerAlpha:<n>` | Minimum lowercase letters | `password pwd filters=minLowerAlpha:1` |
+| `minUpperAlpha:<n>` | Minimum uppercase letters | `password pwd filters=minUpperAlpha:1` |
+| `minDigit:<n>` | Minimum digits (0-9) | `password pwd filters=minDigit:1` |
+| `minSymbol:<n>` | Minimum special characters | `password pwd filters=minSymbol:1` |
+
+```xs
+// Strong password: 8+ chars, 1 upper, 1 lower, 1 digit, 1 symbol
+password strong_pwd filters=min:8|minUpperAlpha:1|minLowerAlpha:1|minDigit:1|minSymbol:1
+```
+
 ### timestamp / date
 ```xs
 timestamp created_at?=now              // Defaults to current time
@@ -199,10 +220,8 @@ Filters validate and transform input values. Chain with `|`.
 | `ok:<chars>` | Allow only specified characters | `text hex filters=ok:0123456789abcdef` |
 | `prevent:<str>` | Block specific substrings | `text name filters=prevent:admin` |
 | `startsWith:<prefix>` | Require prefix | `text sku filters=startsWith:SKU-` |
-| `endsWith:<suffix>` | Require suffix | `text file filters=endsWith:.pdf` |
 | `alphaOk` | Allow only letters (a-zA-Z) | `text name filters=alphaOk` |
 | `digitOk` | Allow only digits (0-9) | `text code filters=digitOk` |
-| `alphaNumOk` | Allow letters and digits | `text username filters=alphaNumOk` |
 | `pattern:<regex>` | Match regex pattern | `text phone filters=pattern:^\+?[0-9]+$` |
 
 ### Numeric Filters
@@ -210,14 +229,12 @@ Filters validate and transform input values. Chain with `|`.
 |--------|-------------|---------|
 | `min:<n>` | Minimum value | `int age filters=min:0` |
 | `max:<n>` | Maximum value | `int age filters=max:150` |
-| `between:<a>:<b>` | Value between a and b | `int score filters=between:0:100` |
 
 ### Array Filters
 | Filter | Description | Example |
 |--------|-------------|---------|
 | `min:<n>` | Minimum array length | `text[] tags filters=min:1` |
 | `max:<n>` | Maximum array length | `text[] tags filters=max:10` |
-| `unique` | Remove duplicates | `int[] ids filters=unique` |
 
 ### Character Set Filters
 
@@ -255,11 +272,11 @@ input {
 ### Combined Examples
 ```xs
 input {
-  text username filters=trim|lower|min:3|max:20|alphaNumOk
+  text username filters=trim|lower|min:3|max:20|ok:abcdefghijklmnopqrstuvwxyz0123456789_
   email contact filters=trim|lower
   int age filters=min:0|max:150
   text hex_code filters=ok:abcdef0123456789|min:6|max:6
-  text[] tags filters=trim|lower|max:50|unique
+  text[] tags filters=trim|lower|max:50
   text phone filters=trim|pattern:^\+?[0-9\s-]+$
   int quantity filters=min:1|max:100
 }
@@ -326,7 +343,7 @@ input {
 
 ## Validation with Preconditions
 
-For complex validation beyond filters, use preconditions. For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
+For complex validation beyond filters, use preconditions. For complete error handling reference, use `xanoscript_docs({ topic: "syntax" })`.
 
 ```xs
 precondition ($input.start_date < $input.end_date) {

package/dist/xanoscript_docs/workspace.md

@@ -0,0 +1,209 @@
+---
+applyTo: "workspace.xs"
+---
+
+# Workspace Configuration
+
+Configure workspace-level settings including environment variables, preferences, and realtime configuration.
+
+## Quick Reference
+
+```xs
+workspace "<name>" {
+  description = "Workspace description"
+  env = { ... }
+  acceptance = { ... }
+  preferences = { ... }
+  realtime = { ... }
+}
+```
+
+### Attributes
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `description` | text | No | Human-readable workspace description |
+| `env` | object | No | Environment variable definitions |
+| `acceptance` | object | No | Terms and acceptance settings |
+| `preferences` | object | No | Workspace behavior preferences |
+| `realtime` | object | No | Realtime channel configuration |
+
+---
+
+## Basic Structure
+
+```xs
+workspace "my_project" {
+  description = "My XanoScript project workspace"
+}
+```
+
+---
+
+## Environment Variables
+
+Define environment variables accessible via `$env.<name>` in your code.
+
+```xs
+workspace "my_project" {
+  env = {
+    API_KEY: "your-api-key",
+    DATABASE_URL: "postgresql://...",
+    REDIS_URL: "redis://...",
+    ENVIRONMENT: "production"
+  }
+}
+```
+
+### Accessing Environment Variables
+
+```xs
+// In any function, query, or task
+stack {
+  var $key { value = $env.API_KEY }
+
+  api.call "external_api" {
+    url = $env.DATABASE_URL ~ "/endpoint"
+    headers = {
+      "Authorization": "Bearer " ~ $env.API_KEY
+    }
+  }
+}
+```
+
+---
+
+## Acceptance Settings
+
+Configure terms and acceptance requirements.
+
+```xs
+workspace "my_project" {
+  acceptance = {
+    ai_terms: true
+  }
+}
+```
+
+### Acceptance Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `ai_terms` | boolean | Accept AI feature terms of service |
+
+---
+
+## Preferences
+
+Configure workspace behavior and features.
+
+```xs
+workspace "my_project" {
+  preferences = {
+    internal_docs: true,
+    sql_columns: true,
+    sql_names: true,
+    track_performance: true
+  }
+}
+```
+
+### Preference Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `internal_docs` | boolean | false | Enable internal documentation generation |
+| `sql_columns` | boolean | false | Include SQL column names in output |
+| `sql_names` | boolean | false | Include SQL table names in output |
+| `track_performance` | boolean | false | Enable performance tracking and metrics |
+
+---
+
+## Realtime Configuration
+
+Configure realtime channel settings.
+
+```xs
+workspace "my_project" {
+  realtime = {
+    canonical: "my-project"
+  }
+}
+```
+
+### Realtime Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `canonical` | text | Base URL path for realtime channels |
+
+---
+
+## Complete Example
+
+```xs
+workspace "ecommerce_platform" {
+  description = "E-commerce backend workspace"
+
+  env = {
+    STRIPE_KEY: "sk_live_...",
+    SENDGRID_KEY: "SG...",
+    AWS_REGION: "us-east-1",
+    S3_BUCKET: "ecommerce-assets",
+    REDIS_URL: "redis://cache.example.com:6379"
+  }
+
+  acceptance = {
+    ai_terms: true
+  }
+
+  preferences = {
+    internal_docs: true,
+    track_performance: true
+  }
+
+  realtime = {
+    canonical: "ecommerce"
+  }
+}
+```
+
+---
+
+## File Location
+
+Workspace configuration is stored in `workspace.xs` at the root of your project.
+
+```
+project/
+├── workspace.xs           // Workspace configuration
+├── branch.xs              // Branch configuration
+├── tables/
+├── functions/
+└── apis/
+```
+
+---
+
+## Built-in Environment Variables
+
+These variables are automatically available without configuration:
+
+| Variable | Description |
+|----------|-------------|
+| `$env.$remote_ip` | Client IP address |
+| `$env.$http_headers` | Request headers array |
+| `$env.$request_uri` | Request URI |
+| `$env.$request_method` | HTTP method (GET, POST, etc.) |
+| `$env.$request_querystring` | Query string |
+| `$env.$datasource` | Current datasource |
+| `$env.$branch` | Current branch name |
+
+---
+
+## Best Practices
+
+1. **Never commit secrets** - Use environment variables for API keys and credentials
+2. **Use descriptive names** - Environment variable names should be self-documenting
+3. **Enable performance tracking** - Helps identify bottlenecks in production
+4. **Set meaningful canonical paths** - Makes realtime channel URLs predictable
+5. **Document your workspace** - Use the description field for team reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "MCP server for Xano Headless API documentation and XanoScript code validation",
   "type": "module",
   "main": "dist/index.js",