@xano/developer-mcp 1.0.26 → 1.0.27

package/dist/templates/init-workspace.js

@@ -1,278 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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/ephemeral.md

@@ -1,330 +0,0 @@
----
-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`