@xano/developer-mcp 1.0.27 → 1.0.29

package/dist/templates/init-workspace.js

@@ -0,0 +1,278 @@
+/**
+ * Template for init_workspace tool documentation
+ * Edit this file to update the workspace initialization guide
+ */
+export function generateInitWorkspaceTemplate(objectTypes) {
+    const objectTypesTable = objectTypes
+        .map(({ type, path, endpoint }) => `| \`${type}\` | \`${path}/\` | \`${endpoint}\` |`)
+        .join("\n");
+    return `# Xano Workspace Initialization Guide
+
+This guide explains how to set up a local development workspace that syncs with the Xano Headless API.
+
+## Directory Structure
+
+Initialize your workspace with these directories:
+
+\`\`\`
+your-project/
+├── .xano/
+│   └── registry.json      # Tracks all objects and their sync state
+├── functions/             # Custom reusable functions
+│   ├── calculate_total.xs
+│   └── validate_email.xs
+├── tables/                # Database table schemas
+│   ├── user.xs
+│   └── order.xs
+├── tasks/                 # Scheduled background tasks
+│   └── cleanup_sessions.xs
+├── apis/                  # API groups and endpoints
+│   └── auth/              # API group directory
+│       ├── api_group.xs   # Group definition
+│       ├── POST_login.xs  # Endpoint: POST /auth/login
+│       └── GET_me.xs      # Endpoint: GET /auth/me
+├── tools/                 # AI-callable tools
+├── agents/                # AI agents
+├── middlewares/           # Request/response middleware
+├── addons/                # Query addons
+├── mcp_servers/           # MCP servers
+└── realtime/              # Realtime channels
+\`\`\`
+
+## Object Types
+
+| Type | Directory | API Endpoint |
+|------|-----------|--------------|
+${objectTypesTable}
+
+## File Naming Convention
+
+Files should follow snake_case naming with the \`.xs\` extension:
+- \`{name}.xs\` - Basic format (e.g., \`calculate_total.xs\`)
+- \`{id}_{name}.xs\` - With ID prefix for disambiguation (e.g., \`42_calculate_total.xs\`)
+- API endpoints: \`{VERB}_{path}.xs\` (e.g., \`POST_login.xs\`, \`GET_users_id.xs\`)
+
+## Registry Format
+
+The \`.xano/registry.json\` file tracks the sync state between local files and the Xano API:
+
+\`\`\`json
+{
+  "workspace_id": 12345,
+  "workspace_name": "My Project",
+  "branch": "",
+  "base_url": "https://your-instance.xano.io/api:headless",
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-15T10:30:00Z",
+  "objects": [
+    {
+      "id": 1,
+      "type": "function",
+      "name": "calculate_total",
+      "path": "functions/calculate_total.xs",
+      "sha256": "abc123...",
+      "status": "unchanged",
+      "original": "ZnVuY3Rpb24gY2FsY3VsYXRlX3RvdGFsIHsgLi4uIH0=",
+      "updated_at": "2025-01-15T10:30:00Z"
+    },
+    {
+      "id": 0,
+      "type": "function",
+      "name": "new_function",
+      "path": "functions/new_function.xs",
+      "status": "new"
+    }
+  ]
+}
+\`\`\`
+
+### Registry Record Fields
+
+| Field | Description |
+|-------|-------------|
+| \`id\` | Xano object ID (0 = new, not yet synced) |
+| \`type\` | Object type (function, table, task, etc.) |
+| \`name\` | Object name extracted from XanoScript |
+| \`path\` | Relative file path from workspace root |
+| \`sha256\` | SHA256 hash of file content for change detection |
+| \`status\` | Sync status: "new", "unchanged", "changed", "deleted" |
+| \`original\` | Base64-encoded original content (for conflict detection) |
+| \`updated_at\` | Last sync timestamp |
+
+### Status Values
+
+| Status | Description |
+|--------|-------------|
+| \`new\` | Created locally, not yet pushed to Xano |
+| \`unchanged\` | In sync with remote |
+| \`changed\` | Modified locally since last sync |
+| \`deleted\` | Marked for deletion (file removed locally) |
+
+## Fetching Objects from the API
+
+Use the Headless API to fetch objects.
+
+### List Objects
+
+\`\`\`
+GET /workspace/{workspace_id}/{type}
+Headers:
+  Authorization: Bearer {token}
+
+Query Parameters:
+  - branch: Branch label (empty = live branch)
+  - page: Page number (default: 1)
+  - per_page: Items per page (default: 50, max: 10000)
+  - search: Text search filter
+  - sort: Sort field (created_at, updated_at, name)
+  - order: asc or desc
+\`\`\`
+
+### Get Single Object with XanoScript
+
+\`\`\`
+GET /workspace/{workspace_id}/{type}/{id}
+Headers:
+  Authorization: Bearer {token}
+
+Query Parameters:
+  - branch: Branch label
+\`\`\`
+
+The response includes the \`xanoscript\` field with the code content:
+\`\`\`json
+{
+  "id": 1,
+  "name": "calculate_total",
+  "xanoscript": {
+    "status": "ok",
+    "value": "function calculate_total { ... }"
+  }
+}
+\`\`\`
+
+### API Endpoints (Nested Under API Groups)
+
+**Important:** API endpoints are nested resources under API groups. You must first fetch API groups to obtain their IDs, then use those IDs to fetch the endpoints within each group.
+
+\`\`\`
+# 1. First, list API groups
+GET /workspace/{workspace_id}/apigroup
+
+# 2. Then, list endpoints for each group using the apigroup_id
+GET /workspace/{workspace_id}/apigroup/{apigroup_id}/api
+
+# 3. Get a single endpoint
+GET /workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}
+\`\`\`
+
+This hierarchical structure is reflected in the local directory layout:
+\`\`\`
+apis/
+└── auth/                  # API group (apigroup_id required)
+    ├── api_group.xs       # Group definition
+    ├── POST_login.xs      # Endpoint within this group
+    └── GET_me.xs          # Another endpoint
+\`\`\`
+
+API groups contain endpoints that share common configuration.
+
+## Pull Workflow
+
+1. **Fetch object list** from API (paginated)
+2. **For each object**, get the full definition including XanoScript
+3. **Generate file path** based on type and name
+4. **Write file** to the appropriate directory
+5. **Update registry** with object metadata and SHA256 hash
+
+### Example Pull Request Sequence
+
+\`\`\`javascript
+// 1. List all functions
+const response = await fetch(
+  \`\${baseUrl}/workspace/\${workspaceId}/function?branch=\${branch}&per_page=100\`,
+  { headers: { Authorization: \`Bearer \${token}\` } }
+);
+const { items, nextPage } = await response.json();
+
+// 2. For each function, save to file
+for (const func of items) {
+  const xanoscript = func.xanoscript?.value || '';
+  const fileName = \`\${snakeCase(func.name)}.xs\`;
+  const filePath = \`functions/\${fileName}\`;
+
+  // Write file
+  await writeFile(filePath, xanoscript);
+
+  // Add to registry
+  registry.objects.push({
+    id: func.id,
+    type: 'function',
+    name: func.name,
+    path: filePath,
+    sha256: sha256(xanoscript),
+    status: 'unchanged',
+    original: btoa(xanoscript),
+    updated_at: func.updated_at
+  });
+}
+\`\`\`
+
+## Push Workflow
+
+1. **Read registry** to find changed/new objects
+2. **For each changed file**, read content and detect changes
+3. **Create or update** via API with XanoScript content
+4. **Update registry** with new IDs and hashes
+
+### Example Push Request
+
+\`\`\`javascript
+// Create new function
+const response = await fetch(
+  \`\${baseUrl}/workspace/\${workspaceId}/function?branch=\${branch}\`,
+  {
+    method: 'POST',
+    headers: {
+      'Authorization': \`Bearer \${token}\`,
+      'Content-Type': 'text/x-xanoscript'
+    },
+    body: xanoscriptContent
+  }
+);
+
+// Update existing function
+const response = await fetch(
+  \`\${baseUrl}/workspace/\${workspaceId}/function/\${functionId}?publish=true\`,
+  {
+    method: 'PUT',
+    headers: {
+      'Authorization': \`Bearer \${token}\`,
+      'Content-Type': 'text/x-xanoscript'
+    },
+    body: xanoscriptContent
+  }
+);
+\`\`\`
+
+## XanoScript Documentation References
+
+For writing XanoScript code, use:
+
+- \`xanoscript_docs()\` - Full documentation index
+- \`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
+
+Before pushing changes, validate the XanoScript syntax:
+
+\`\`\`
+validate_xanoscript({ code: "function foo { ... }" })
+\`\`\`
+
+This will check for syntax errors and return line/column positions for any issues.
+`;
+}

package/dist/templates/xanoscript-index.d.ts

@@ -0,0 +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;
+}
+export declare function generateXanoscriptIndexTemplate(params: XanoscriptIndexParams): string;

package/dist/templates/xanoscript-index.js

@@ -0,0 +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 } = params;
+    return `# XanoScript Documentation Index
+Version: ${version}
+
+Use \`xanoscript_docs({ topic: "<topic>" })\` to retrieve documentation.
+
+## 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 |
+
+## 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 |
+
+## 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 |
+
+## 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 |
+
+## Integrations
+| 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 | 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 | Description |
+|-------|-------------|
+| \`performance\` | Performance optimization best practices |
+| \`security\` | Security best practices for authentication and authorization |
+`;
+}

package/dist/xanoscript_docs/README.md

@@ -45,19 +45,9 @@ project/
 
 ## Environment Variables
 
-Access with `$env.<name>`. Built-in variables:
-
-| Variable                    | Description                   |
-| --------------------------- | ----------------------------- |
-| `$env.$remote_ip`           | Client IP address             |
-| `$env.$http_headers`        | Request headers array         |
-| `$env.$request_uri`         | Request URI                   |
-| `$env.$request_method`      | HTTP method (GET, POST, etc.) |
-| `$env.$request_querystring` | Query string                  |
-| `$env.$datasource`          | Current datasource            |
-| `$env.$branch`              | Current branch                |
-
-Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
+Access with `$env.<name>`. Common built-in variables include `$env.$remote_ip`, `$env.$http_headers`, `$env.$request_method`, `$env.$datasource`, and `$env.$branch`. Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
+
+For the complete list of system variables, see `xanoscript_docs({ topic: "syntax" })`.
 
 ## Core Syntax Patterns
 

package/dist/xanoscript_docs/ephemeral.md

@@ -0,0 +1,330 @@
+---
+applyTo: "ephemeral/**/*.xs"
+---
+
+# Ephemeral Environments
+
+Temporary Xano workspaces for testing and one-off operations.
+
+## Quick Reference
+
+| Type | Purpose | Lifecycle |
+|------|---------|-----------|
+| **Service** | Temporary workspace with DB/APIs | Runs until shut down |
+| **Job** | One-time operation | Executes once, then shuts down |
+
+### Directory Structure
+```
+ephemeral/
+├── my-service/
+│   ├── workspace.xs
+│   ├── tables/
+│   ├── functions/
+│   └── apis/
+└── my-job/
+    ├── workspace.xs
+    ├── tables/
+    └── functions/
+```
+
+---
+
+## Ephemeral Service
+
+A temporary workspace with database, functions, and API endpoints.
+
+### workspace.xs
+```xs
+workspace my_service {
+  env = {
+    api_key: "test-key"
+    debug: "true"
+  }
+}
+```
+
+### Table with Seed Data
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name filters=trim
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Event 1"}
+    {"id": 2, "name": "Event 2"}
+  ]
+}
+```
+
+### API Group
+```xs
+api_group events {
+  canonical = "events-api"
+}
+```
+
+### Endpoints
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+
+query add verb=POST {
+  api_group = "events"
+  input { text name filters=trim }
+  stack {
+    db.add event {
+      data = { name: $input.name }
+    } as $event
+  }
+  response = $event
+}
+```
+
+---
+
+## Ephemeral Job
+
+One-time operation with setup and cleanup hooks.
+
+### Reserved Functions
+| Function | Purpose | Required |
+|----------|---------|----------|
+| `$main` | Primary logic | Yes |
+| `$pre` | Setup/validation | No |
+| `$post` | Cleanup/notification | No |
+
+### Execution Order
+1. `$pre` (if defined)
+2. `$main`
+3. `$post` (if defined)
+4. Environment shuts down
+
+### $main Function
+```xs
+function "$main" {
+  input {
+    json args                   // Runtime arguments
+    json pre                    // Result from $pre
+  }
+  stack {
+    db.query authors {
+      return = { type: "count" }
+    } as $count
+
+    precondition ($count > 0) {
+      error = "No authors found"
+    }
+
+    db.add authors {
+      data = { name: "New Author" }
+    }
+  }
+  response = { processed: true }
+}
+```
+
+### $pre Function (optional)
+```xs
+function "$pre" {
+  input { json args }
+  stack {
+    // Validation or setup
+    precondition ($input.args.required_field != null) {
+      error = "Missing required field"
+    }
+  }
+  response = { validated: true }
+}
+```
+
+### $post Function (optional)
+```xs
+function "$post" {
+  input {
+    json args
+    json pre
+    json main
+  }
+  stack {
+    // Send notification or cleanup
+    api.request {
+      url = $env.WEBHOOK_URL
+      method = "POST"
+      params = {
+        status: "complete",
+        result: $input.main
+      }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Complete Service Example
+
+```
+ephemeral/event-tracker/
+├── workspace.xs
+├── tables/
+│   └── event.xs
+└── apis/
+    ├── api_group.xs
+    ├── list.xs
+    ├── add.xs
+    └── clear.xs
+```
+
+### workspace.xs
+```xs
+workspace event_tracker {
+  env = { api_key: "test" }
+}
+```
+
+### 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
+}
+```
+
+---
+
+## Complete Job Example
+
+```
+ephemeral/data-migration/
+├── workspace.xs
+├── tables/
+│   └── users.xs
+└── functions/
+    ├── $main.xs
+    └── $post.xs
+```
+
+### workspace.xs
+```xs
+workspace data_migration {
+  env = { webhook_url: "https://webhook.site/xxx" }
+}
+```
+
+### 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/$main.xs
+```xs
+function "$main" {
+  input { json args, json pre }
+  stack {
+    db.query users {
+      where = $db.users.migrated_at == null
+    } 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 }
+}
+```
+
+### functions/$post.xs
+```xs
+function "$post" {
+  input { json args, json pre, json main }
+  stack {
+    api.request {
+      url = $env.webhook_url
+      method = "POST"
+      params = { result: $input.main }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Deploying
+
+### Deploy Service
+```
+publish_ephemeral_service name="my-api" directory="ephemeral/my-service" mode="service"
+```
+
+### Run Job
+```
+publish_ephemeral_service name="migration" directory="ephemeral/my-job" mode="job"
+```
+
+---
+
+## Best Practices
+
+1. **Keep isolated** - Self-contained with own tables/functions
+2. **Seed test data** - Use `items` in table definitions
+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`