@xano/developer-mcp 1.0.15 → 1.0.16

package/README.md

@@ -7,6 +7,7 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
 This MCP server acts as a bridge between AI models and Xano's developer ecosystem, offering:
 
 - **Meta API Documentation** - Programmatically manage Xano workspaces, databases, APIs, functions, and more
+- **Run API Documentation** - Runtime execution, session management, and XanoScript execution
 - **XanoScript Documentation** - Language reference with context-aware docs based on file type
 - **Code Validation** - Syntax checking with the official XanoScript language server
 - **Workflow Guides** - Step-by-step guides for common development tasks
@@ -157,7 +158,7 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | `testing` | Unit tests, mocks, and assertions |
 | `integrations` | Cloud storage, Redis, security, and external APIs |
 | `frontend` | Static frontend development and deployment |
-| `ephemeral` | Temporary test environments |
+| `run` | Run job and service configurations |
 | `addons` | Reusable subqueries for fetching related data |
 | `debugging` | Logging, inspecting, and debugging XanoScript execution |
 | `performance` | Performance optimization best practices |
@@ -181,6 +182,45 @@ xanoscript_docs({ file_path: "apis/users/create.xs" })
 xanoscript_docs({ topic: "database", mode: "quick_reference" })
 ```
 
+### 3. `run_api_docs`
+
+Get documentation for Xano's Run API. Use this to understand runtime execution, session management, and XanoScript execution.
+
+**Important:** The Run API uses a fixed base URL: `https://app.dev.xano.com/api:run/<endpoint>` (NOT your Xano instance URL)
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | string | Yes | Documentation topic to retrieve |
+| `detail_level` | string | No | `overview`, `detailed` (default), or `examples` |
+| `include_schemas` | boolean | No | Include JSON schemas for requests/responses (default: true) |
+
+**Available Topics:**
+
+| Topic | Description |
+|-------|-------------|
+| `start` | Getting started with the Run API |
+| `run` | Execute XanoScript code and API endpoints |
+| `session` | Session management for stateful execution |
+| `history` | Execution history and debugging |
+| `data` | Data operations and variable management |
+| `workflows` | Step-by-step workflow guides |
+
+**Examples:**
+```
+// Get overview of Run API
+run_api_docs({ topic: "start" })
+
+// Get detailed run endpoint documentation
+run_api_docs({ topic: "run", detail_level: "detailed" })
+
+// Get examples without schemas (smaller context)
+run_api_docs({ topic: "session", detail_level: "examples", include_schemas: false })
+
+// Step-by-step workflow guides
+run_api_docs({ topic: "workflows" })
+```
+
 ### 4. `mcp_version`
 
 Get the current version of the Xano Developer MCP server.
@@ -263,7 +303,7 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `xanoscript://docs/testing` | Unit tests and mocks |
 | `xanoscript://docs/integrations` | External service integrations |
 | `xanoscript://docs/frontend` | Static frontend development |
-| `xanoscript://docs/ephemeral` | Temporary test environments |
+| `xanoscript://docs/run` | Run job and service configurations |
 | `xanoscript://docs/addons` | Reusable subqueries for related data |
 | `xanoscript://docs/debugging` | Logging and debugging tools |
 | `xanoscript://docs/performance` | Performance optimization |
@@ -287,11 +327,15 @@ xano-developer-mcp/
 ├── src/
 │   ├── index.ts              # Main MCP server implementation
 │   ├── xanoscript.d.ts       # TypeScript declarations
-│   ├── meta_api_docs/             # Meta API documentation
+│   ├── meta_api_docs/        # Meta API documentation
 │   │   ├── index.ts          # API docs tool handler
 │   │   ├── types.ts          # Type definitions
 │   │   ├── format.ts         # Documentation formatter
 │   │   └── topics/           # Individual topic modules
+│   ├── run_api_docs/         # Run API documentation
+│   │   ├── index.ts          # Run API tool handler
+│   │   ├── format.ts         # Documentation formatter
+│   │   └── topics/           # Individual topic modules
 │   ├── xanoscript_docs/      # XanoScript language documentation
 │   │   ├── version.json
 │   │   ├── README.md
@@ -329,6 +373,8 @@ Xano Developer MCP Server
     │
     ├─► meta_api_docs → Meta API documentation with detail levels
     │
+    ├─► run_api_docs → Run API documentation for runtime execution
+    │
     ├─► mcp_version → Returns server version from package.json
     │
     └─► MCP Resources → Direct access to XanoScript documentation

package/dist/index.js

@@ -94,10 +94,10 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["static/**/*"],
         description: "Static frontend development and deployment",
     },
-    ephemeral: {
-        file: "ephemeral.md",
-        applyTo: ["ephemeral/**/*.xs"],
-        description: "Temporary test environments",
+    run: {
+        file: "run.md",
+        applyTo: ["run/**/*.xs"],
+        description: "Run job and service configurations for the Xano Job Runner",
     },
     addons: {
         file: "addons.md",

package/dist/templates/xanoscript-index.js

@@ -64,6 +64,6 @@ ${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")}
+${formatRow("run", "Run job and service configurations")}
 `;
 }

package/dist/xanoscript_docs/README.md

@@ -33,7 +33,7 @@ project/
 ├── mcp_servers/         // MCP server definitions
 ├── addons/              // Query addons
 ├── static/              // Frontend files (HTML, CSS, JS)
-└── ephemeral/           // Temporary test environments
+└── run/                 // Job and service configurations
 ```
 
 ## Environment Variables
@@ -147,7 +147,7 @@ Use `xanoscript_docs({ keyword: "<keyword>" })` to retrieve documentation.
 | Testing | `testing` | Unit tests and mocking |
 | Debugging | `debugging` | Logging and inspection tools |
 | Frontend | `frontend` | Static frontend development |
-| Ephemeral | `ephemeral` | Temporary environments |
+| Run | `run` | Job and service configurations |
 
 ### Best Practices
 | Topic | Keyword | Description |

package/dist/xanoscript_docs/run.md

@@ -0,0 +1,357 @@
+---
+applyTo: "run/**/*.xs"
+---
+
+# Run Configurations
+
+Define job and service configurations for the Xano Job Runner.
+
+## Quick Reference
+
+| Type | Purpose | Lifecycle |
+|------|---------|-----------|
+| **run.job** | Execute a function once | Runs main function, then shuts down |
+| **run.service** | Long-running background process | Runs pre initialization, then maintains service |
+
+### Directory Structure
+```
+run/
+├── my-job/
+│   ├── run.xs
+│   ├── tables/
+│   └── functions/
+└── my-service/
+    ├── run.xs
+    ├── tables/
+    ├── functions/
+    └── apis/
+```
+
+---
+
+## run.job
+
+Execute a function as a standalone job in the Xano Job Runner.
+
+### Syntax
+```xs
+run.job "Job Name" {
+  main = {
+    name: "function_name"
+    input: { key: value }
+  }
+  env = ["ENV_VAR1", "ENV_VAR2"]
+}
+```
+
+### Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `main` | Object | Yes | Function to execute |
+| `main.name` | String | Yes | Name of the function to call |
+| `main.input` | Object | No | Input parameters for the function |
+| `env` | String[] | No | Environment variables required |
+
+### Basic Example
+```xs
+run.job "Random Dad Joke" {
+  main = {
+    name: "fetch_dad_joke"
+    input: {}
+  }
+}
+```
+
+### With Input Parameters
+```xs
+run.job "Average of values" {
+  main = {
+    name: "avg_value"
+    input: {
+      left: 1
+      right: 2
+    }
+  }
+}
+```
+
+### With Environment Variables
+```xs
+run.job "Gemini Image Understanding" {
+  main = {
+    name: "analyze_image"
+    input: {
+      model: "gemini-1.5-flash"
+      prompt: "Describe what is happening in this image."
+      image: "(attach image file)"
+    }
+  }
+  env = ["gemini_api_key"]
+}
+```
+
+---
+
+## run.service
+
+Define a long-running background service with optional initialization.
+
+### Syntax
+```xs
+run.service "Service Name" {
+  pre = {
+    name: "init_function"
+    input: { key: value }
+  }
+  env = ["ENV_VAR1", "ENV_VAR2"]
+}
+```
+
+### Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `pre` | Object | No | Initialization function |
+| `pre.name` | String | Yes (if pre) | Name of the init function |
+| `pre.input` | Object | No | Input parameters for init |
+| `env` | String[] | No | Environment variables required |
+
+### Minimal Form
+```xs
+run.service "email proxy"
+```
+
+### Basic Example
+```xs
+run.service "Random Dad Joke" {
+  pre = {
+    name: "fetch_dad_joke"
+    input: {}
+  }
+}
+```
+
+### With Initialization
+```xs
+run.service "email proxy" {
+  pre = {
+    name: "email_proxy_init"
+    input: {
+      config: "default"
+    }
+  }
+}
+```
+
+### With Environment Variables
+```xs
+run.service "webhook listener" {
+  pre = {
+    name: "init_webhook_listener"
+    input: {
+      port: 8080
+    }
+  }
+  env = ["webhook_secret", "database_url"]
+}
+```
+
+---
+
+## Supporting Files
+
+Jobs and services can include supporting tables and functions.
+
+### Table with Seed Data
+```xs
+table users {
+  auth = false
+  schema {
+    int id
+    text name
+    text email
+    timestamp created_at?=now
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Alice", "email": "alice@example.com"}
+    {"id": 2, "name": "Bob", "email": "bob@example.com"}
+  ]
+}
+```
+
+### Function Definition
+```xs
+function "process_data" {
+  input {
+    json data
+  }
+  stack {
+    db.query users {
+      return = { type: "list" }
+    } as $users
+  }
+  response = $users
+}
+```
+
+---
+
+## Complete Job Example
+
+```
+run/data-migration/
+├── run.xs
+├── tables/
+│   └── users.xs
+└── functions/
+    └── migrate_users.xs
+```
+
+### run.xs
+```xs
+run.job "Data Migration" {
+  main = {
+    name: "migrate_users"
+    input: {
+      batch_size: 100
+    }
+  }
+  env = ["source_db_url", "webhook_url"]
+}
+```
+
+### tables/users.xs
+```xs
+table users {
+  auth = false
+  schema {
+    int id
+    text name
+    text email
+    timestamp migrated_at?
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Alice", "email": "alice@example.com"}
+    {"id": 2, "name": "Bob", "email": "bob@example.com"}
+  ]
+}
+```
+
+### functions/migrate_users.xs
+```xs
+function "migrate_users" {
+  input {
+    int batch_size
+  }
+  stack {
+    db.query users {
+      where = $db.users.migrated_at == null
+      paging = { page: 1, per_page: $input.batch_size }
+    } as $pending
+
+    foreach ($pending) {
+      each as $user {
+        db.edit users {
+          field_name = "id"
+          field_value = $user.id
+          data = { migrated_at: now }
+        }
+      }
+    }
+  }
+  response = { migrated: $pending|count }
+}
+```
+
+---
+
+## Complete Service Example
+
+```
+run/event-tracker/
+├── run.xs
+├── tables/
+│   └── event.xs
+└── apis/
+    ├── api_group.xs
+    ├── list.xs
+    └── add.xs
+```
+
+### run.xs
+```xs
+run.service "Event Tracker" {
+  pre = {
+    name: "init_tracker"
+    input: {}
+  }
+  env = ["api_key"]
+}
+```
+
+### tables/event.xs
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = []
+}
+```
+
+### apis/list.xs
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      sort = { created_at: "desc" }
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+```
+
+---
+
+## Differences: run.job vs run.service
+
+| Feature | run.job | run.service |
+|---------|---------|-------------|
+| Required attribute | `main` | None |
+| Init function | N/A | `pre` (optional) |
+| Lifecycle | Executes once | Long-running |
+| Use case | One-time operations | Proxies, listeners, daemons |
+
+---
+
+## Validation Rules
+
+1. **run.job requires `main`** - Missing `main` causes an error
+2. **run.service cannot use `main`** - Use `pre` for initialization
+3. **`env` must be string array** - Cannot contain numbers or booleans
+4. **Input values must be constants** - No variables like `$input` allowed
+
+---
+
+## Best Practices
+
+1. **Name clearly** - Indicate purpose: `data-migration`, `email-proxy`
+2. **Use env for secrets** - Never hardcode API keys or credentials
+3. **Keep self-contained** - Include all required tables and functions
+4. **Seed test data** - Use `items` in table definitions for testing
+5. **Validate inputs** - Use preconditions in functions for input validation

package/package.json

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