@xano/developer-mcp 1.0.19 → 1.0.21

package/README.md

@@ -1,6 +1,28 @@
-# Xano Developer MCP
+<div align="center">
 
-A Model Context Protocol (MCP) server that provides AI assistants with comprehensive documentation and tools for developing applications on the Xano Headless API platform.
+# 🚀 Xano Developer MCP
+
+**Supercharge your AI with the power of Xano**
+
+[![npm version](https://img.shields.io/npm/v/@xano/developer-mcp.svg)](https://www.npmjs.com/package/@xano/developer-mcp)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+🤖 **AI-Powered** · 📚 **Comprehensive Docs** · ⚡ **Instant Setup** · 🔧 **Built-in Tools**
+
+---
+
+</div>
+
+An MCP server that gives AI assistants superpowers for developing on [Xano](https://xano.com) — complete with documentation, code validation, and workflow guides.
+
+> 💡 **What's Xano?** The fastest way to build a scalable backend for your app — no code required. Build APIs, manage databases, and deploy instantly.
+
+### 🔗 Quick Links
+
+| 🌐 [Website](https://xano.com) | 📖 [Docs](https://docs.xano.com/) | 📝 [Blog](https://www.xano.com/blog/) | 💬 [Community](https://community.xano.com/) | 📦 [npm](https://www.npmjs.com/package/@xano/developer-mcp) |
+|:---:|:---:|:---:|:---:|:---:|
 
 ## Overview
 
@@ -22,6 +44,20 @@ claude mcp add xano-developer -- npx -y @xano/developer-mcp
 
 That's it! The MCP server will be automatically installed and configured.
 
+### Install via npm
+
+You can also install the package globally from npm:
+
+```bash
+npm install -g @xano/developer-mcp
+```
+
+Then add to Claude Code:
+
+```bash
+claude mcp add xano-developer -- xano-developer-mcp
+```
+
 ### Claude Desktop
 
 Add to your Claude Desktop configuration file:

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" })`.
 
 ---