@xano/developer-mcp 1.0.8 → 1.0.10

package/README.md

@@ -180,6 +180,7 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | `functions` | Reusable function stacks with inputs and responses |
 | `apis` | HTTP endpoint definitions with authentication and CRUD patterns |
 | `tasks` | Scheduled and cron jobs |
+| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
 | `database` | All db.* operations: query, get, add, edit, patch, delete |
 | `agents` | AI agent configuration with LLM providers and tools |
 | `tools` | AI tools for agents and MCP servers |
@@ -188,6 +189,13 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | `integrations` | Cloud storage, Redis, security, and external APIs |
 | `frontend` | Static frontend development and deployment |
 | `ephemeral` | Temporary test environments |
+| `addons` | Reusable subqueries for fetching related data |
+| `debugging` | Logging, inspecting, and debugging XanoScript execution |
+| `performance` | Performance optimization best practices |
+| `realtime` | Real-time channels and events for push updates |
+| `schema` | Runtime schema parsing and validation |
+| `security` | Security best practices for authentication and authorization |
+| `streaming` | Streaming data from files, requests, and responses |
 
 **Examples:**
 ```
@@ -234,6 +242,7 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `xanoscript://docs/functions` | Reusable function stacks |
 | `xanoscript://docs/apis` | HTTP endpoint definitions |
 | `xanoscript://docs/tasks` | Scheduled and cron jobs |
+| `xanoscript://docs/triggers` | Event-driven handlers |
 | `xanoscript://docs/database` | Database operations |
 | `xanoscript://docs/agents` | AI agent configuration |
 | `xanoscript://docs/tools` | AI tools for agents |
@@ -242,6 +251,13 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `xanoscript://docs/integrations` | External service integrations |
 | `xanoscript://docs/frontend` | Static frontend development |
 | `xanoscript://docs/ephemeral` | Temporary test environments |
+| `xanoscript://docs/addons` | Reusable subqueries for related data |
+| `xanoscript://docs/debugging` | Logging and debugging tools |
+| `xanoscript://docs/performance` | Performance optimization |
+| `xanoscript://docs/realtime` | Real-time channels and events |
+| `xanoscript://docs/schema` | Runtime schema parsing |
+| `xanoscript://docs/security` | Security best practices |
+| `xanoscript://docs/streaming` | Data streaming operations |
 
 ## npm Scripts
 

package/dist/index.js

@@ -98,6 +98,41 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["ephemeral/**/*.xs"],
         description: "Temporary test environments",
     },
+    addons: {
+        file: "addons.md",
+        applyTo: ["addons/*.xs", "functions/**/*.xs", "apis/**/*.xs"],
+        description: "Reusable subqueries for fetching related data",
+    },
+    debugging: {
+        file: "debugging.md",
+        applyTo: ["**/*.xs"],
+        description: "Logging, inspecting, and debugging XanoScript execution",
+    },
+    performance: {
+        file: "performance.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        description: "Performance optimization best practices",
+    },
+    realtime: {
+        file: "realtime.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "triggers/**/*.xs"],
+        description: "Real-time channels and events for push updates",
+    },
+    schema: {
+        file: "schema.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        description: "Runtime schema parsing and validation",
+    },
+    security: {
+        file: "security.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        description: "Security best practices for authentication and authorization",
+    },
+    streaming: {
+        file: "streaming.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        description: "Streaming data from files, requests, and responses",
+    },
 };
 const XANO_OBJECT_TYPES = {
     function: {

package/dist/templates/xanoscript-index.js

@@ -53,8 +53,15 @@ ${formatRow("task_workflow", "AI workflow for creating tasks")}
 
 | 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("ephemeral", "Ephemeral environment setup")}

package/package.json

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

package/xanoscript_docs/README.md

@@ -105,19 +105,52 @@ This helps AI tools apply the correct documentation based on the file being edit
 
 Use `xanoscript_docs({ keyword: "<keyword>" })` to retrieve documentation.
 
+### Core Language
 | Topic | Keyword | Description |
 |-------|---------|-------------|
-| Syntax Reference | `syntax` | Expressions, operators, filters |
+| 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 |
+
+### Data
+| Topic | Keyword | Description |
+|-------|---------|-------------|
 | Tables | `table` | Database schema definitions |
-| Functions | `function` | Reusable function stacks |
+| Database Operations | `db_query` | Query, add, edit, delete, bulk operations |
+| Addons | `addon` | Reusable subqueries for related data |
+| Streaming | `streaming` | Stream processing for large files |
+
+### APIs & Endpoints
+| Topic | Keyword | Description |
+|-------|---------|-------------|
 | APIs | `api_query` | HTTP endpoint definitions |
 | Tasks | `task` | Scheduled jobs |
-| Triggers | `trigger` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
-| Database Operations | `db_query` | Query, add, edit, delete |
+| Triggers | `trigger` | Event-driven handlers |
+| Realtime | `realtime` | Push events and channels |
+
+### AI & Agents
+| Topic | Keyword | Description |
+|-------|---------|-------------|
 | Agents | `agent` | AI agent configuration |
 | Tools | `tool` | AI tools for agents |
 | MCP Servers | `mcp_server` | Model Context Protocol servers |
+
+### Integrations
+| Topic | Keyword | Description |
+|-------|---------|-------------|
+| Integrations | `integrations` | Cloud storage, search, Redis, zip, Lambda |
+
+### Development
+| Topic | Keyword | Description |
+|-------|---------|-------------|
 | Testing | `testing` | Unit tests and mocking |
+| Debugging | `debugging` | Logging and inspection tools |
 | Frontend | `frontend` | Static frontend development |
-| Ephemeral | `ephemeral` | Temporary environments
+| Ephemeral | `ephemeral` | Temporary environments |
+
+### Best Practices
+| Topic | Keyword | Description |
+|-------|---------|-------------|
+| Performance | `performance` | Query optimization, caching, parallelism |
+| Security | `security` | Authentication, authorization, encryption |

package/xanoscript_docs/addons.md

@@ -0,0 +1,256 @@
+---
+applyTo: "addons/*.xs, functions/**/*.xs, apis/**/*.xs"
+---
+
+# Addons
+
+Reusable subqueries for fetching related data in database queries.
+
+## Quick Reference
+
+```xs
+addon <name> {
+  input {
+    <type> <name>
+  }
+
+  stack {
+    db.query <tableName> {
+      return = {type: "<return_type>"}
+    }
+  }
+}
+```
+
+---
+
+## Basic Structure
+
+Addons define reusable data fetching logic that can be attached to query results. The stack can only contain a `db.query` block.
+
+```xs
+addon comment_count {
+  input {
+    int post_id
+  }
+
+  stack {
+    db.query comment {
+      where = $db.comment.post_id == $input.post_id
+      return = {type: "count"}
+    }
+  }
+}
+```
+
+---
+
+## Using Addons in Queries
+
+### In db.query
+
+```xs
+db.query post {
+  where = $db.post.author_id == $auth.id
+  addon = [
+    {
+      name: "comment_count",
+      input: {post_id: $output.id},
+      as: "items.comment_count"
+    }
+  ]
+} as $posts
+```
+
+### Result Structure
+
+```json
+{
+  "items": [
+    {
+      "id": 1,
+      "title": "My Post",
+      "comment_count": 42
+    }
+  ]
+}
+```
+
+### Multiple Addons
+
+```xs
+db.query post {
+  where = $db.post.is_published == true
+  addon = [
+    {
+      name: "comment_count",
+      input: {post_id: $output.id},
+      as: "items.comments"
+    },
+    {
+      name: "like_count",
+      input: {post_id: $output.id},
+      as: "items.likes"
+    },
+    {
+      name: "author_details",
+      input: {user_id: $output.author_id},
+      as: "items.author"
+    }
+  ]
+} as $posts
+```
+
+---
+
+## Addon Examples
+
+### Related List
+
+```xs
+addon recent_comments {
+  input {
+    int post_id
+    int limit?=5
+  }
+
+  stack {
+    db.query comment {
+      where = $db.comment.post_id == $input.post_id
+      sort = {created_at: "desc"}
+      return = {
+        type: "list",
+        paging: {per_page: $input.limit}
+      }
+    }
+  }
+}
+```
+
+### Count
+
+```xs
+addon order_count {
+  input {
+    int user_id
+  }
+
+  stack {
+    db.query order {
+      where = $db.order.user_id == $input.user_id
+      return = {type: "count"}
+    }
+  }
+}
+```
+
+### Boolean Check (Exists)
+
+```xs
+addon has_premium {
+  input {
+    int user_id
+  }
+
+  stack {
+    db.query subscription {
+      where = $db.subscription.user_id == $input.user_id
+            && $db.subscription.status == "active"
+            && $db.subscription.expires_at > now
+      return = {type: "exists"}
+    }
+  }
+}
+```
+
+### Single Record
+
+```xs
+addon author_details {
+  input {
+    int user_id
+  }
+
+  stack {
+    db.query user {
+      where = $db.user.id == $input.user_id
+      return = {type: "single"}
+    }
+  }
+}
+```
+
+---
+
+## addon.call
+
+Call an addon directly from a function or API.
+
+```xs
+addon.call comment_count {
+  input = {post_id: $input.post_id}
+} as $count
+```
+
+### Use Cases
+
+```xs
+// Get stats for single record
+addon.call order_count {
+  input = {user_id: $auth.id}
+} as $my_order_count
+
+// Conditional addon call
+conditional {
+  if ($input.include_stats) {
+    addon.call order_count {
+      input = {user_id: $entity.id}
+    } as $count
+  }
+}
+```
+
+---
+
+## Database Addon Attributes
+
+Use `dbAddonAttr` for computed fields in queries.
+
+```xs
+db.query product {
+  eval = {
+    discount_price: dbAddonAttr("calculate_discount", {product_id: $db.product.id})
+  }
+} as $products
+```
+
+---
+
+## Organization
+
+### File Structure
+
+```
+addons/
+├── comment_count.xs
+├── like_count.xs
+├── author_details.xs
+├── order_count.xs
+└── has_premium.xs
+```
+
+### Naming Conventions
+
+- Use descriptive names: `comment_count`, not `cc`
+- Use verb_noun for actions: `calculate_discount`
+- Use has_ prefix for boolean checks: `has_premium`
+
+---
+
+## Best Practices
+
+1. **Keep addons focused** - One purpose per addon
+2. **Use input parameters** - Make addons reusable
+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

package/xanoscript_docs/agents.md

@@ -317,6 +317,89 @@ agent "Research Assistant" {
 
 ---
 
+## External MCP Tools
+
+Integrate external MCP (Model Context Protocol) servers to extend agent capabilities.
+
+### ai.external.mcp.tool.list
+
+List available tools from an external MCP server.
+
+```xs
+ai.external.mcp.tool.list {
+  server_url = "https://mcp.example.com"
+  api_key = $env.MCP_API_KEY
+} as $tools
+
+// $tools = [
+//   { name: "search_web", description: "Search the web", inputSchema: {...} },
+//   { name: "fetch_page", description: "Fetch webpage content", inputSchema: {...} }
+// ]
+```
+
+### ai.external.mcp.tool.run
+
+Execute a tool on an external MCP server.
+
+```xs
+ai.external.mcp.tool.run {
+  server_url = "https://mcp.example.com"
+  api_key = $env.MCP_API_KEY
+  tool_name = "search_web"
+  arguments = { query: "latest AI news" }
+} as $result
+```
+
+### ai.external.mcp.server_details
+
+Get metadata about an external MCP server.
+
+```xs
+ai.external.mcp.server_details {
+  server_url = "https://mcp.example.com"
+  api_key = $env.MCP_API_KEY
+} as $details
+
+// $details = {
+//   name: "Web Tools",
+//   version: "1.0.0",
+//   capabilities: ["tools", "resources"],
+//   tools: [...]
+// }
+```
+
+### Using External Tools in Agents
+
+```xs
+agent "Research Agent" {
+  canonical = "research-v1"
+  llm = {
+    type: "openai"
+    api_key: "{{ $env.OPENAI_API_KEY }}"
+    model: "gpt-5"
+    system_prompt: """
+      You are a research assistant with access to web search
+      and document analysis tools. Use them to find and analyze information.
+    """
+    prompt: "{{ $args.query }}"
+    max_steps: 8
+  }
+  tools = [
+    { name: "search_web" },
+    { name: "fetch_page" },
+    { name: "summarize_document" }
+  ]
+  external_mcp_servers = [
+    {
+      url: "{{ $env.WEB_MCP_URL }}",
+      api_key: "{{ $env.WEB_MCP_KEY }}"
+    }
+  ]
+}
+```
+
+---
+
 ## Best Practices
 
 1. **Clear system prompts** - Define persona, capabilities, and constraints
@@ -325,3 +408,4 @@ agent "Research Assistant" {
 4. **Don't repeat tool descriptions** - They're auto-injected
 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

package/xanoscript_docs/database.md

@@ -405,6 +405,164 @@ db.external.oracle.direct_query { ... }
 
 ---
 
+## Bulk Operations
+
+Perform batch operations on multiple records efficiently.
+
+### db.bulk.add
+
+Insert multiple records in a single operation.
+
+```xs
+db.bulk.add "product" {
+  data = [
+    { name: "Product A", price: 10.00, sku: "SKU-A" },
+    { name: "Product B", price: 20.00, sku: "SKU-B" },
+    { name: "Product C", price: 30.00, sku: "SKU-C" }
+  ]
+} as $inserted
+```
+
+### db.bulk.update
+
+Update multiple records matching conditions.
+
+```xs
+db.bulk.update "product" {
+  where = $db.product.category_id == $input.category_id
+  data = {
+    is_featured: true,
+    updated_at: now
+  }
+} as $count
+```
+
+### db.bulk.patch
+
+Patch multiple records with variable data.
+
+```xs
+var $updates { value = { updated_at: now } }
+
+conditional {
+  if ($input.discount != null) {
+    var.update $updates { value = $updates|set:"discount":$input.discount }
+  }
+}
+
+db.bulk.patch "product" {
+  where = $db.product.category_id == $input.category_id
+  data = $updates
+} as $count
+```
+
+### db.bulk.delete
+
+Delete multiple records matching conditions.
+
+```xs
+db.bulk.delete "temp_session" {
+  where = $db.temp_session.expires_at < now
+} as $deleted_count
+```
+
+### Bulk with Transaction
+
+```xs
+db.transaction {
+  stack {
+    db.bulk.delete "order_item" {
+      where = $db.order_item.order_id == $input.order_id
+    }
+
+    db.bulk.add "order_item" {
+      data = $input.items|map:{
+        order_id: $input.order_id,
+        product_id: $$.product_id,
+        quantity: $$.quantity
+      }
+    }
+  }
+}
+```
+
+---
+
+## Advanced Features
+
+### db.set_datasource
+
+Switch to a different data source within a function.
+
+```xs
+db.set_datasource {
+  name = "analytics_db"
+}
+
+db.query "metrics" {
+  where = $db.metrics.date >= $input.start_date
+} as $metrics
+
+db.set_datasource {
+  name = "default"
+}
+```
+
+### db.schema
+
+Get schema information for a table.
+
+```xs
+db.schema {
+  table = "user"
+} as $schema
+
+// $schema contains:
+// - columns: array of column definitions
+// - indexes: array of index definitions
+// - constraints: array of constraints
+```
+
+### Transaction Isolation Levels
+
+```xs
+db.transaction {
+  isolation = "serializable"      // serializable, repeatable_read, read_committed
+  stack {
+    // Operations run with specified isolation
+  }
+}
+```
+
+### Deadlock Handling
+
+```xs
+try_catch {
+  try {
+    db.transaction {
+      stack {
+        db.edit "inventory" { ... }
+        db.edit "order" { ... }
+      }
+    }
+  }
+  catch {
+    conditional {
+      if ($error.name == "DeadlockError") {
+        // Retry logic
+        util.sleep { value = 100 }
+        function.run "retry_transaction" { input = $input }
+      }
+      else {
+        throw { name = $error.name, value = $error.message }
+      }
+    }
+  }
+}
+```
+
+---
+
 ## Best Practices
 
 1. **Use db.query for searches** - Flexible filtering and pagination
@@ -412,3 +570,5 @@ db.external.oracle.direct_query { ... }
 3. **Use db.patch for dynamic updates** - Accepts variable data
 4. **Use transactions for atomicity** - Ensure all-or-nothing operations
 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