@xano/developer-mcp 1.0.20 → 1.0.22

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
@@ -73,6 +80,8 @@ $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.
+
 ### Comments
 ```xs
 // Single-line comment
@@ -103,54 +112,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/agents.md

@@ -60,7 +60,7 @@ agent "Customer Support" {
 ai.agent.run "Customer Support" {
   args = {}|set:"user_message":$input.message
   allow_tool_execution = true
-} as $response
+} as $agent_result
 ```
 
 ---

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" })`.
 
 ---
 
@@ -342,7 +342,7 @@ stack {
     async = true
   } as $request
 
-  await $request as $response
+  await $request as $result
 }
 ```
 
@@ -372,9 +372,9 @@ stack {
   // All three requests complete before continuing
   var $combined {
     value = {
-      users: $users.body,
-      products: $products.body,
-      orders: $orders.body
+      users: $users.response.result,
+      products: $products.response.result,
+      orders: $orders.response.result
     }
   }
 }

package/dist/xanoscript_docs/integrations.md

@@ -587,6 +587,8 @@ util.send_email {
 
 ## External APIs
 
+Make HTTP requests to external APIs.
+
 ```xs
 api.request {
   url = "https://api.example.com/data"
@@ -594,7 +596,47 @@ api.request {
   params = { key: "value" }
   headers = []|push:("Authorization: Bearer " ~ $env.API_KEY)
   timeout = 30
-} as $response
+} as $api_result
+```
+
+### Response Structure
+
+The `api.request` statement returns an object with both request and response details:
+
+```json
+{
+  "request": {
+    "url": "",       // The URL that was requested
+    "method": "",    // HTTP method used (GET, POST, etc.)
+    "headers": [],   // Array of request headers sent
+    "params": []     // Parameters sent with the request
+  },
+  "response": {
+    "headers": [],   // Array of response headers received
+    "result": "",    // Response body (can be any format: JSON, string, null, boolean, etc.)
+    "status": 200    // HTTP status code
+  }
+}
+```
+
+### Accessing Response Data
+
+```xs
+api.request {
+  url = "https://api.example.com/users"
+  method = "GET"
+} as $api_result
+
+// Access the response body
+var $data { value = $api_result.response.result }
+
+// Check status code
+if ($api_result.response.status != 200) {
+  precondition { false } with { message = "API request failed" }
+}
+
+// Access a specific header
+var $content_type { value = $api_result.response.headers|first }
 ```
 
 ---