@xano/developer-mcp 1.0.5 → 1.0.7

package/dist/index.js

@@ -47,6 +47,11 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["tasks/*.xs"],
         description: "Scheduled and cron jobs",
     },
+    triggers: {
+        file: "triggers.md",
+        applyTo: ["triggers/**/*.xs"],
+        description: "Event-driven handlers (table, realtime, workspace, agent, MCP)",
+    },
     database: {
         file: "database.md",
         applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs", "tools/**/*.xs"],

package/dist/templates/xanoscript-index.js

@@ -22,6 +22,7 @@ ${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/`")}

package/package.json

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

package/xanoscript_docs/README.md

@@ -10,26 +10,30 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 | `function` | `functions/**/*.xs` | Reusable logic blocks |
 | `query` | `apis/<group>/*.xs` | HTTP API endpoints |
 | `task` | `tasks/*.xs` | Scheduled/cron jobs |
+| `*_trigger` | `triggers/**/*.xs` | Event-driven handlers |
 | `agent` | `agents/**/*.xs` | AI-powered agents |
 | `tool` | `tools/**/*.xs` | Tools for AI agents |
 | `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
 | `addon` | `addons/*.xs` | Subqueries for related data |
 
+**Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
+
 ## Workspace Structure
 
 ```
 project/
-├── tables/              # Database table schemas
-├── functions/           # Reusable functions (supports subfolders)
+├── tables/              // Database table schemas
+├── functions/           // Reusable functions (supports subfolders)
 ├── apis/
-│   └── <api-group>/     # API endpoints grouped by domain
-├── tasks/               # Scheduled jobs
-├── agents/              # AI agents
-├── tools/               # AI tools
-├── mcp_servers/         # MCP server definitions
-├── addons/              # Query addons
-├── static/              # Frontend files (HTML, CSS, JS)
-└── ephemeral/           # Temporary test environments
+│   └── <api-group>/     // API endpoints grouped by domain
+├── tasks/               // Scheduled jobs
+├── triggers/            // Event-driven handlers
+├── agents/              // AI agents
+├── tools/               // AI tools
+├── mcp_servers/         // MCP server definitions
+├── addons/              // Query addons
+├── static/              // Frontend files (HTML, CSS, JS)
+└── ephemeral/           // Temporary test environments
 ```
 
 ## Environment Variables
@@ -53,28 +57,36 @@ Custom environment variables are set in the Xano dashboard and accessed as `$env
 ### Block Structure
 ```xs
 <construct> "<name>" {
-  input { ... }      # Parameters (optional)
-  stack { ... }      # Logic
-  response = $var    # Output
+  input { ... }      // Parameters (optional)
+  stack { ... }      // Logic
+  response = $var    // Output
 }
 ```
 
 ### Variable Access
 ```xs
-$input.field        # Input parameters
-$var.field          # Stack variables
-$auth.id            # Authenticated user ID
-$env.MY_VAR         # Environment variable
-$db.table.field     # Database field reference (in queries)
-$this               # Current item in loops/maps
+$input.field        // Input parameters
+$var.field          // Stack variables
+$auth.id            // Authenticated user ID
+$env.MY_VAR         // Environment variable
+$db.table.field     // Database field reference (in queries)
+$this               // Current item in loops/maps
 ```
 
+### Comments
+```xs
+// Single-line comment
+var $total { value = 0 }  // Inline comment
+```
+
+**Note:** XanoScript only supports `//` for comments. Other comment styles like `#` are not supported.
+
 ### Filters (Pipe Syntax)
 ```xs
-$value|trim|lower                    # Chain filters
-$input.name|strlen                   # Get length
-$array|first                         # First element
-($a + $b)|round:2                    # Math with precision
+$value|trim|lower                    // Chain filters
+$input.name|strlen                   // Get length
+$array|first                         // First element
+($a + $b)|round:2                    // Math with precision
 ```
 
 ## File Frontmatter
@@ -91,17 +103,21 @@ This helps AI tools apply the correct documentation based on the file being edit
 
 ## Documentation Index
 
-1. [Syntax Reference](syntax.md) - Expressions, operators, filters
-2. [Types & Inputs](types.md) - Data types, validation, input blocks
-3. [Tables](tables.md) - Database schema definitions
-4. [Functions](functions.md) - Reusable function stacks
-5. [APIs](apis.md) - HTTP endpoint definitions
-6. [Tasks](tasks.md) - Scheduled jobs
-7. [Database Operations](database.md) - Query, add, edit, delete
-8. [Agents](agents.md) - AI agent configuration
-9. [Tools](tools.md) - AI tools for agents
-10. [MCP Servers](mcp-servers.md) - Model Context Protocol servers
-11. [Testing](testing.md) - Unit tests and mocking
-12. [Integrations](integrations.md) - Cloud services, Redis, security
-13. [Frontend](frontend.md) - Static frontend development
-14. [Ephemeral](ephemeral.md) - Temporary environments
+Use `xanoscript_docs({ keyword: "<keyword>" })` to retrieve documentation.
+
+| Topic | Keyword | Description |
+|-------|---------|-------------|
+| Syntax Reference | `syntax` | Expressions, operators, filters |
+| Types & Inputs | `input` | Data types, validation, input blocks |
+| Tables | `table` | Database schema definitions |
+| Functions | `function` | Reusable function stacks |
+| 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 |
+| Agents | `agent` | AI agent configuration |
+| Tools | `tool` | AI tools for agents |
+| MCP Servers | `mcp_server` | Model Context Protocol servers |
+| Testing | `testing` | Unit tests and mocking |
+| Frontend | `frontend` | Static frontend development |
+| Ephemeral | `ephemeral` | Temporary environments

package/xanoscript_docs/agents.md

@@ -71,10 +71,10 @@ ai.agent.run "Customer Support" {
 
 ```xs
 llm = {
-  type: "<provider>"                    # Required
-  system_prompt: "..."                  # Agent persona and rules
-  prompt: "{{ $args.input }}"           # User input template
-  max_steps: 5                          # Max LLM calls per run
+  type: "<provider>"                    // Required
+  system_prompt: "..."                  // Agent persona and rules
+  prompt: "{{ $args.input }}"           // User input template
+  max_steps: 5                          // Max LLM calls per run
 }
 ```
 
@@ -94,7 +94,7 @@ llm = {
   prompt: "{{ $args.message }}"
   max_steps: 3
   temperature: 0
-  search_grounding: false               # Google Search grounding
+  search_grounding: false               // Google Search grounding
 }
 ```
 
@@ -108,7 +108,7 @@ llm = {
   prompt: "{{ $args.message }}"
   max_steps: 5
   temperature: 0.2
-  thinking_tokens: 10000                # Extended thinking
+  thinking_tokens: 10000                // Extended thinking
   include_thoughts: true
 }
 ```
@@ -123,7 +123,7 @@ llm = {
   prompt: "{{ $args.message }}"
   max_steps: 5
   temperature: 0.8
-  reasoning_effort: "medium"            # low, medium, high
+  reasoning_effort: "medium"            // low, medium, high
 }
 ```
 
@@ -134,7 +134,7 @@ llm = {
   api_key: "{{ $env.GROQ_API_KEY }}"
   baseURL: "https://api.groq.com/openai/v1"
   model: "llama-3.3-70b-versatile"
-  compatibility: "compatible"           # Required for non-OpenAI
+  compatibility: "compatible"           // Required for non-OpenAI
   ...
 }
 ```
@@ -151,7 +151,7 @@ llm = {
   prompt: "{{ $args.message }}"
   max_steps: 8
   temperature: 0.3
-  send_reasoning: true                  # Include thinking blocks
+  send_reasoning: true                  // Include thinking blocks
 }
 ```
 
@@ -218,9 +218,9 @@ llm = {
 
 ### Available Variables
 ```xs
-{{ $args.any_arg }}                     # Runtime arguments
-{{ $env.MY_VAR }}                       # Environment variables
-{{ "now"|date("Y-m-d") }}               # Current date
+{{ $args.any_arg }}                     // Runtime arguments
+{{ $env.MY_VAR }}                       // Environment variables
+{{ "now"|date("Y-m-d") }}               // Current date
 ```
 
 ---
@@ -324,6 +324,4 @@ agent "Research Assistant" {
 3. **Limit max_steps** - Prevent infinite loops (3-10 typical)
 4. **Don't repeat tool descriptions** - They're auto-injected
 5. **Use environment variables** - Never hardcode API keys
-6. **Keep prompts focused** - One task per agent
-7. **Test with xano-free first** - Free for development
-8. **Use structured outputs** - When you need consistent JSON
+6. **Test with xano-free first** - Free for development

package/xanoscript_docs/apis.md

@@ -9,19 +9,19 @@ HTTP endpoint definitions in XanoScript.
 ## Quick Reference
 
 ```xs
-query "<name>" verb=<METHOD> {
-  api_group = "<GroupName>"     # Required: API group for organization
+query "endpoint-path" verb=<METHOD> {
+  api_group = "<GroupName>"     // Required: API group for organization
   description = "What this endpoint does"
-  auth = "<table>"              # Optional: require authentication
+  auth = "<table>"              // Optional: require authentication
   input { ... }
   stack { ... }
   response = $result
 }
 ```
 
-### Query Name (Required)
+### Query Name (Required, Non-Empty)
 
-The query name is **required** and cannot be empty. It defines the endpoint path after the API group canonical.
+The query name is **required** and **must be a non-empty string**. Empty names (`query "" verb=...`) are invalid. The name defines the endpoint path after the API group canonical.
 
 **Full URL path structure:**
 ```
@@ -38,61 +38,28 @@ The query name can include slashes for nested paths:
 
 ### API Groups (Required)
 
-Every API endpoint **must** belong to an API group. API groups organize related endpoints together.
-
-**Two requirements for API groups:**
-1. Each `query` definition **must** include an `api_group` property specifying which group it belongs to
-2. API groups are organized as folders within `apis/`, each with an `api_group.xs` file
-
-- API groups appear as top-level folders under `apis/`
-- Each group **must** have an `api_group.xs` file that defines the group
-- The group contains `.xs` files defining individual endpoints
-- The group name becomes part of the endpoint URL path
-- You cannot create endpoints directly in the `apis/` root folder
-
-#### Defining an API Group
-
-Create an `api_group.xs` file in the group folder:
+Every endpoint must belong to an API group. Each group is a folder with an `api_group.xs` file:
 
 ```xs
 api_group "users" {
-  canonical = "users"                # Required: the URL path segment
-  description = "User management endpoints"
+  canonical = "users"                // Required: URL path segment
+  description = "User management"    // Optional
 }
 ```
 
-#### API Group Properties
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| `canonical` | **Yes** | The URL path segment for this group. You cannot access a Xano API without it. |
-| `description` | No | What this API group contains |
-
-```xs
-api_group "events" {
-  canonical = "events-api"           # Required: URL will use /events-api
-  description = "Event management"
-}
-```
-
-> **Important:** The `canonical` property is required. It defines the base path for all endpoints in this group.
-
 ### File Structure
 ```
 apis/
-├── users/                      # API group folder
-│   ├── api_group.xs            # Required: defines the group (canonical = "users")
-│   ├── list.xs                 # GET /users/list
-│   ├── create.xs               # POST /users/create
-│   └── by-id.xs                # GET/PATCH/DELETE /users/{id}
-└── products/                   # Another API group
-    ├── api_group.xs            # Required: defines the group (canonical = "products")
-    └── search.xs               # GET /products/search
+├── users/
+│   ├── api_group.xs            // Defines group (canonical = "users")
+│   ├── list.xs                 // GET /users/list
+│   └── by-id.xs                // GET/PATCH/DELETE /users/{id}
+└── products/
+    ├── api_group.xs            // Defines group (canonical = "products")
+    └── search.xs               // GET /products/search
 ```
 
-> **URL Path:** The full endpoint URL is always `/<canonical>/<query name>`. For example, if `api_group.xs` has `canonical = "users"` and a query has `query "profile" verb=GET`, the endpoint URL is `/users/profile`.
-
-> **Note:** Files placed directly in `apis/` without a group folder are invalid. Each API group folder must contain an `api_group.xs` file.
+Full URL: `/<canonical>/<query name>` (e.g., `/users/profile`)
 
 ---
 
@@ -132,11 +99,11 @@ query "status" verb=GET {
 ```xs
 query "profile" verb=GET {
   api_group = "Users"
-  auth = "user"                 # Requires valid JWT
+  auth = "user"                 // Requires valid JWT
   stack {
     db.get "user" {
       field_name = "id"
-      field_value = $auth.id    # User ID from token
+      field_value = $auth.id    // User ID from token
     } as $user
   }
   response = $user
@@ -354,33 +321,11 @@ stack {
 
 ## Error Handling
 
-### Preconditions
-```xs
-stack {
-  precondition ($input.amount > 0) {
-    error_type = "inputerror"
-    error = "Amount must be positive"
-  }
-
-  precondition ($user != null) {
-    error_type = "notfound"
-    error = "User not found"
-  }
-
-  precondition ($user.id == $auth.id) {
-    error_type = "accessdenied"
-    error = "Not authorized"
-  }
-}
-```
+For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
 
-### Error Types
 | Type | HTTP Status |
 |------|-------------|
-| `inputerror` | 400 Bad Request |
-| `accessdenied` | 403 Forbidden |
-| `notfound` | 404 Not Found |
-| `standard` | 500 Internal Server Error |
+| `inputerror` | 400 | `accessdenied` | 403 | `notfound` | 404 | `standard` | 500 |
 
 ---
 
@@ -404,13 +349,8 @@ When using `return = { type: "list", paging: {...} }`:
 
 ## Best Practices
 
-1. **Always set canonical** - Every `api_group` requires a `canonical` property
-2. **Always name queries** - Every `query` requires a non-empty name
-3. **RESTful design** - Use appropriate HTTP methods
-4. **Consistent naming** - Use lowercase, hyphens for multi-word paths
-5. **Authenticate sensitive operations** - Always auth for writes
-6. **Validate inputs** - Use filters and preconditions
-7. **Return appropriate errors** - Use correct error types
-8. **Paginate lists** - Never return unbounded lists
-9. **Document with description** - Explain what endpoint does
-10. **Group related endpoints** - Organize by resource in api groups
+1. **RESTful design** - Use appropriate HTTP methods for operations
+2. **Consistent naming** - Use lowercase, hyphens for multi-word paths
+3. **Authenticate writes** - Always require auth for POST/PATCH/DELETE
+4. **Paginate lists** - Never return unbounded result sets
+5. **Group by resource** - Organize endpoints in logical api groups

package/xanoscript_docs/database.md

@@ -35,7 +35,7 @@ db.query "product" {
 
 ### Where Operators
 ```xs
-# Comparison
+// Comparison
 $db.product.price == 100
 $db.product.price != 0
 $db.product.price > 50
@@ -43,32 +43,32 @@ $db.product.price >= 50
 $db.product.price < 100
 $db.product.price <= 100
 
-# Null-safe (ignore if value is null)
+// Null-safe (ignore if value is null)
 $db.product.category ==? $input.category
 $db.product.price >=? $input.min_price
 
-# String matching
-$db.product.name includes "phone"       # Contains substring
-$db.product.tags contains "featured"    # Array contains value
+// String matching
+$db.product.name includes "phone"       // Contains substring
+$db.product.tags contains "featured"    // Array contains value
 $db.product.tags not contains "hidden"
 
-# Array overlap
+// Array overlap
 $db.product.tags overlaps ["a", "b"]
 $db.product.tags not overlaps ["x", "y"]
 
-# Combining conditions
+// Combining conditions
 $db.product.is_active == true && $db.product.price > 0
 $db.product.category == "electronics" || $db.product.featured == true
 ```
 
 ### Return Types
 ```xs
-# List (default)
+// List (default)
 db.query "product" {
   return = { type: "list" }
 } as $products
 
-# With pagination
+// With pagination
 db.query "product" {
   return = {
     type: "list",
@@ -76,19 +76,19 @@ db.query "product" {
   }
 } as $products
 
-# Single record
+// Single record
 db.query "product" {
   where = $db.product.sku == $input.sku
   return = { type: "single" }
 } as $product
 
-# Count
+// Count
 db.query "product" {
   where = $db.product.is_active == true
   return = { type: "count" }
 } as $count
 
-# Exists
+// Exists
 db.query "product" {
   where = $db.product.email == $input.email
   return = { type: "exists" }
@@ -98,9 +98,9 @@ db.query "product" {
 ### Sorting
 ```xs
 db.query "product" {
-  sort = { created_at: "desc" }         # Descending
-  sort = { name: "asc" }                # Ascending
-  sort = { id: "rand" }                 # Random
+  sort = { created_at: "desc" }         // Descending
+  sort = { name: "asc" }                // Ascending
+  sort = { id: "rand" }                 // Random
 } as $products
 ```
 
@@ -110,7 +110,7 @@ db.query "comment" {
   join = {
     post: {
       table: "post",
-      type: "inner",                    # inner, left, right
+      type: "inner",                    // inner, left, right
       where: $db.comment.post_id == $db.post.id
     }
   }
@@ -279,7 +279,7 @@ Delete all records from a table.
 
 ```xs
 db.truncate "temp_data" {
-  reset = true                          # Reset auto-increment
+  reset = true                          // Reset auto-increment
 }
 ```
 
@@ -293,7 +293,7 @@ Execute raw SQL (use sparingly).
 db.direct_query {
   sql = "SELECT * FROM users WHERE email = ? AND status = ?"
   arg = [$input.email, "active"]
-  response_type = "list"                # list or single
+  response_type = "list"                // list or single
 } as $results
 ```
 
@@ -339,9 +339,9 @@ Filters for use in `where` clauses:
 
 ### String/Text
 ```xs
-$db.name|to_lower                       # Case conversion
-$db.name|concat:" "                     # Concatenation
-$db.text|substr:0:100                   # Substring
+$db.name|to_lower                       // Case conversion
+$db.name|concat:" "                     // Concatenation
+$db.text|substr:0:100                   // Substring
 ```
 
 ### Numeric
@@ -363,8 +363,8 @@ $db.created_at|timestamp_subtract_hours:24
 
 ### Geographic
 ```xs
-$db.location|distance:$input.point      # Distance in meters
-$db.location|within:$input.point:1000   # Within radius
+$db.location|distance:$input.point      // Distance in meters
+$db.location|within:$input.point:1000   // Within radius
 ```
 
 ### Vector (AI/ML)
@@ -385,7 +385,7 @@ $db.content|search_rank:$input.query
 Connect to external databases:
 
 ```xs
-# PostgreSQL
+// PostgreSQL
 db.external.postgres.direct_query {
   connection_string = $env.EXTERNAL_PG_URL
   sql = "SELECT * FROM users WHERE id = ?"
@@ -393,13 +393,13 @@ db.external.postgres.direct_query {
   response_type = "single"
 } as $user
 
-# MySQL
+// MySQL
 db.external.mysql.direct_query { ... }
 
-# MS SQL
+// MS SQL
 db.external.mssql.direct_query { ... }
 
-# Oracle
+// Oracle
 db.external.oracle.direct_query { ... }
 ```
 
@@ -411,7 +411,4 @@ db.external.oracle.direct_query { ... }
 2. **Use db.get for single lookups** - Simpler than db.query with single return
 3. **Use db.patch for dynamic updates** - Accepts variable data
 4. **Use transactions for atomicity** - Ensure all-or-nothing operations
-5. **Add indexes** - Index fields used in where clauses
-6. **Use null-safe operators** - `==?` for optional filters
-7. **Paginate results** - Never return unbounded lists
-8. **Validate before delete** - Check ownership/permissions
+5. **Use null-safe operators** - `==?` for optional filters

package/xanoscript_docs/ephemeral.md

@@ -116,8 +116,8 @@ One-time operation with setup and cleanup hooks.
 ```xs
 function "$main" {
   input {
-    json args                   # Runtime arguments
-    json pre                    # Result from $pre
+    json args                   // Runtime arguments
+    json pre                    // Result from $pre
   }
   stack {
     db.query authors {
@@ -325,9 +325,6 @@ publish_ephemeral_service name="migration" directory="ephemeral/my-job" mode="jo
 
 1. **Keep isolated** - Self-contained with own tables/functions
 2. **Seed test data** - Use `items` in table definitions
-3. **Use environment variables** - Store config in workspace `env`
-4. **Handle cleanup** - Use `$post` for notifications/cleanup
-5. **Validate in $pre** - Check preconditions before main logic
-6. **Use preconditions** - Verify expected outcomes in jobs
-7. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`
-8. **Set end dates** - Use `ends_on` for temporary schedules
+3. **Handle cleanup** - Use `$post` for notifications/cleanup
+4. **Validate in $pre** - Check preconditions before main logic
+5. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`

package/xanoscript_docs/frontend.md

@@ -11,10 +11,10 @@ Static frontend development and Lovable/Supabase migration.
 ### Directory Structure
 ```
 static/
-├── index.html              # Main entry point
+├── index.html              // Main entry point
 ├── css/
 ├── js/
-│   └── api.js              # Centralized API calls
+│   └── api.js              // Centralized API calls
 └── assets/
 ```
 
@@ -284,8 +284,5 @@ The tool will:
 
 1. **Get API specs first** - Use `get_xano_api_specifications` before coding
 2. **Centralize API calls** - Single `api.js` file
-3. **Handle errors** - Show user-friendly messages
-4. **Store tokens securely** - localStorage for web, secure storage for mobile
-5. **Validate before submit** - Client-side validation before API calls
-6. **Use loading states** - Show progress during API calls
-7. **Test incrementally** - Migrate one feature at a time
+3. **Store tokens securely** - localStorage for web, secure storage for mobile
+4. **Test incrementally** - Migrate one feature at a time