@xano/developer-mcp 1.0.7 → 1.0.9

package/README.md

@@ -39,6 +39,18 @@ Add to your Claude Desktop configuration file:
 }
 ```
 
+## Checking Your Version
+
+```bash
+npx @xano/developer-mcp --version
+```
+
+If installed from source:
+
+```bash
+node dist/index.js --version
+```
+
 ## Installation from Source
 
 ### Prerequisites
@@ -168,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 |
@@ -176,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:**
 ```
@@ -222,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 |
@@ -230,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

@@ -11,6 +11,12 @@ import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js"
 import { generateInitWorkspaceTemplate } from "./templates/init-workspace.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const SERVER_VERSION = pkg.version;
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+    console.log(SERVER_VERSION);
+    process.exit(0);
+}
 const XANOSCRIPT_DOCS_V2 = {
     readme: {
         file: "README.md",
@@ -92,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: {
@@ -357,7 +398,7 @@ function generateInitWorkspaceDoc() {
 // =============================================================================
 const server = new Server({
     name: "xano-developer-mcp",
-    version: "1.0.0",
+    version: SERVER_VERSION,
     description: "MCP server for Xano Headless API documentation and XanoScript code validation",
 }, {
     capabilities: {

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.7",
+  "version": "1.0.9",
   "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,285 @@
+---
+applyTo: "addons/*.xs, functions/**/*.xs, apis/**/*.xs"
+---
+
+# Addons
+
+Reusable subqueries for fetching related data in database queries.
+
+## Quick Reference
+
+```xs
+addon "<name>" {
+  description = "What this addon fetches"
+  input {
+    <type> <name>
+  }
+  stack {
+    // Query logic
+  }
+  response = $result
+}
+```
+
+---
+
+## Basic Structure
+
+Addons define reusable data fetching logic that can be attached to query results.
+
+```xs
+addon "comment_count" {
+  description = "Count of comments for a post"
+  input {
+    int post_id
+  }
+  stack {
+    db.query "comment" {
+      where = $db.comment.post_id == $input.post_id
+      return = { type: "count" }
+    } as $count
+  }
+  response = $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" {
+  description = "Get recent comments for a post"
+  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 }
+      }
+    } as $comments
+  }
+  response = $comments.items
+}
+```
+
+### Aggregation
+
+```xs
+addon "order_stats" {
+  description = "Order statistics for a user"
+  input {
+    int user_id
+  }
+  stack {
+    db.query "order" {
+      where = $db.order.user_id == $input.user_id
+    } as $orders
+
+    var $stats {
+      value = {
+        total_orders: $orders|count,
+        total_spent: $orders|map:$$.total|sum,
+        avg_order: $orders|map:$$.total|avg
+      }
+    }
+  }
+  response = $stats
+}
+```
+
+### Nested Object
+
+```xs
+addon "full_address" {
+  description = "Get formatted address for a user"
+  input {
+    int user_id
+  }
+  stack {
+    db.get "address" {
+      field_name = "user_id"
+      field_value = $input.user_id
+    } as $address
+
+    conditional {
+      if ($address != null) {
+        var $formatted {
+          value = {
+            street: $address.street,
+            city: $address.city,
+            state: $address.state,
+            zip: $address.zip,
+            full: $address.street ~ ", " ~ $address.city ~ ", " ~ $address.state ~ " " ~ $address.zip
+          }
+        }
+      }
+      else {
+        var $formatted { value = null }
+      }
+    }
+  }
+  response = $formatted
+}
+```
+
+### Boolean Check
+
+```xs
+addon "has_premium" {
+  description = "Check if user has premium subscription"
+  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" }
+    } as $has_premium
+  }
+  response = $has_premium
+}
+```
+
+---
+
+## 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_stats" {
+  input = { user_id: $auth.id }
+} as $my_stats
+
+// Conditional addon call
+conditional {
+  if ($input.include_stats) {
+    addon.call "detailed_stats" {
+      input = { entity_id: $entity.id }
+    } as $stats
+  }
+}
+```
+
+---
+
+## 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_stats.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. **Handle null cases** - Return sensible defaults
+4. **Cache expensive addons** - Use Redis for slow queries
+5. **Limit nested queries** - Avoid N+1 query patterns
+6. **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