@xano/developer-mcp 1.0.35 → 1.0.37

package/dist/xanoscript_docs/database.md

@@ -6,6 +6,29 @@ applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs, tool/**/*.xs"
 
 Complete reference for XanoScript database operations.
 
+> **TL;DR:** Use `db.get` for single record by ID, `db.query` for filtered lists, `db.has` to check existence, `db.add` to insert, `db.edit` for inline updates, `db.patch` for dynamic fields, `db.del` to delete.
+
+## Choosing an Operation
+
+```
+Need to...
+├── Read data?
+│   ├── Single record by ID? → db.get
+│   ├── Check if exists? → db.has
+│   └── Filtered list? → db.query
+├── Write data?
+│   ├── New record? → db.add
+│   ├── Update known fields? → db.edit
+│   └── Update dynamic fields? → db.patch
+├── Delete data?
+│   ├── Single record? → db.del
+│   └── All records? → db.truncate
+└── Complex query?
+    ├── Join tables? → db.query with join
+    ├── Aggregate? → db.query with evals
+    └── Transaction? → db.transaction
+```
+
 ## Quick Reference
 
 | Operation        | Purpose                       | Returns                  |

package/dist/xanoscript_docs/docs_index.json

@@ -0,0 +1,241 @@
+{
+  "version": "1.0.0",
+  "description": "Machine-readable index for XanoScript documentation",
+
+  "topics": {
+    "cheatsheet": {
+      "file": "cheatsheet.md",
+      "purpose": "Quick reference for 20 most common operations",
+      "priority": 1,
+      "aliases": ["quick", "common", "basics", "start"]
+    },
+    "quickstart": {
+      "file": "quickstart.md",
+      "purpose": "Common patterns and mistakes to avoid",
+      "priority": 2,
+      "aliases": ["start", "getting-started", "patterns", "mistakes"]
+    },
+    "syntax": {
+      "file": "syntax.md",
+      "purpose": "Operators, filters, expressions, error handling",
+      "priority": 3,
+      "aliases": ["filters", "operators", "expressions"]
+    },
+    "types": {
+      "file": "types.md",
+      "purpose": "Data types, validation, input blocks",
+      "priority": 4,
+      "aliases": ["validation", "input", "data-types"]
+    },
+    "database": {
+      "file": "database.md",
+      "purpose": "All db.* operations",
+      "priority": 5,
+      "aliases": ["db", "crud", "query", "sql"]
+    },
+    "tables": {
+      "file": "tables.md",
+      "purpose": "Table schema definitions",
+      "aliases": ["schema", "fields", "indexes"]
+    },
+    "apis": {
+      "file": "apis.md",
+      "purpose": "HTTP endpoint definitions",
+      "aliases": ["endpoints", "http", "rest", "query"]
+    },
+    "functions": {
+      "file": "functions.md",
+      "purpose": "Reusable function stacks",
+      "aliases": ["fn", "reusable", "stack"]
+    },
+    "triggers": {
+      "file": "triggers.md",
+      "purpose": "Event-driven handlers",
+      "aliases": ["events", "hooks", "handlers"]
+    },
+    "agents": {
+      "file": "agents.md",
+      "purpose": "AI agent configuration",
+      "aliases": ["ai", "llm", "chatbot"]
+    },
+    "tools": {
+      "file": "tools.md",
+      "purpose": "AI tools for agents",
+      "aliases": ["ai-tools", "agent-tools"]
+    },
+    "integrations": {
+      "file": "integrations.md",
+      "purpose": "External service integrations (index)",
+      "aliases": ["external", "services", "cloud"]
+    },
+    "integrations/cloud-storage": {
+      "file": "integrations/cloud-storage.md",
+      "purpose": "AWS S3, Azure Blob, GCP Storage",
+      "aliases": ["s3", "azure", "gcp", "files", "upload"]
+    },
+    "integrations/search": {
+      "file": "integrations/search.md",
+      "purpose": "Elasticsearch, Algolia",
+      "aliases": ["elasticsearch", "algolia", "full-text"]
+    },
+    "integrations/redis": {
+      "file": "integrations/redis.md",
+      "purpose": "Caching, rate limiting, queues",
+      "aliases": ["cache", "rate-limit", "queue"]
+    },
+    "integrations/external-apis": {
+      "file": "integrations/external-apis.md",
+      "purpose": "api.request patterns",
+      "aliases": ["http", "api", "request", "fetch"]
+    },
+    "integrations/utilities": {
+      "file": "integrations/utilities.md",
+      "purpose": "Email, Zip, Lambda",
+      "aliases": ["email", "zip", "lambda", "archive"]
+    },
+    "security": {
+      "file": "security.md",
+      "purpose": "Authentication, authorization, security patterns",
+      "aliases": ["auth", "authorization", "permissions"]
+    },
+    "performance": {
+      "file": "performance.md",
+      "purpose": "Optimization best practices",
+      "aliases": ["optimization", "speed", "caching"]
+    },
+    "mcp-servers": {
+      "file": "mcp-servers.md",
+      "purpose": "MCP server configuration",
+      "aliases": ["mcp", "model-context-protocol"]
+    },
+    "tasks": {
+      "file": "tasks.md",
+      "purpose": "Scheduled job definitions",
+      "aliases": ["scheduled", "jobs", "cron"]
+    },
+    "streaming": {
+      "file": "streaming.md",
+      "purpose": "Streaming data handling",
+      "aliases": ["stream", "large-files"]
+    },
+    "realtime": {
+      "file": "realtime.md",
+      "purpose": "Real-time channel configuration",
+      "aliases": ["websocket", "channels", "pubsub"]
+    },
+    "middleware": {
+      "file": "middleware.md",
+      "purpose": "Request interceptors",
+      "aliases": ["interceptors", "hooks"]
+    },
+    "unit-testing": {
+      "file": "unit-testing.md",
+      "purpose": "Unit tests, mocks, and assertions",
+      "aliases": ["tests", "unit-tests", "mocks", "assertions"]
+    },
+    "workflow-tests": {
+      "file": "workflow-tests.md",
+      "purpose": "End-to-end workflow tests",
+      "aliases": ["e2e", "workflow", "integration-tests"]
+    },
+    "debugging": {
+      "file": "debugging.md",
+      "purpose": "Logging and debugging",
+      "aliases": ["logs", "debug", "trace"]
+    }
+  },
+
+  "filters": {
+    "trim": { "file": "syntax.md", "category": "string" },
+    "ltrim": { "file": "syntax.md", "category": "string" },
+    "rtrim": { "file": "syntax.md", "category": "string" },
+    "to_lower": { "file": "syntax.md", "category": "string" },
+    "to_upper": { "file": "syntax.md", "category": "string" },
+    "capitalize": { "file": "syntax.md", "category": "string" },
+    "substr": { "file": "syntax.md", "category": "string" },
+    "split": { "file": "syntax.md", "category": "string" },
+    "replace": { "file": "syntax.md", "category": "string" },
+    "contains": { "file": "syntax.md", "category": "string" },
+    "strlen": { "file": "syntax.md", "category": "string" },
+    "first": { "file": "syntax.md", "category": "array" },
+    "last": { "file": "syntax.md", "category": "array" },
+    "count": { "file": "syntax.md", "category": "array" },
+    "map": { "file": "syntax.md", "category": "array" },
+    "filter": { "file": "syntax.md", "category": "array" },
+    "find": { "file": "syntax.md", "category": "array" },
+    "reduce": { "file": "syntax.md", "category": "array" },
+    "push": { "file": "syntax.md", "category": "array" },
+    "pop": { "file": "syntax.md", "category": "array" },
+    "join": { "file": "syntax.md", "category": "array" },
+    "sort": { "file": "syntax.md", "category": "array" },
+    "unique": { "file": "syntax.md", "category": "array" },
+    "get": { "file": "syntax.md", "category": "object" },
+    "set": { "file": "syntax.md", "category": "object" },
+    "has": { "file": "syntax.md", "category": "object" },
+    "keys": { "file": "syntax.md", "category": "object" },
+    "values": { "file": "syntax.md", "category": "object" },
+    "to_int": { "file": "syntax.md", "category": "type" },
+    "to_text": { "file": "syntax.md", "category": "type" },
+    "to_bool": { "file": "syntax.md", "category": "type" },
+    "to_decimal": { "file": "syntax.md", "category": "type" },
+    "json_encode": { "file": "syntax.md", "category": "type" },
+    "json_decode": { "file": "syntax.md", "category": "type" },
+    "round": { "file": "syntax.md", "category": "math" },
+    "abs": { "file": "syntax.md", "category": "math" },
+    "ceil": { "file": "syntax.md", "category": "math" },
+    "floor": { "file": "syntax.md", "category": "math" },
+    "add": { "file": "syntax.md", "category": "math" },
+    "subtract": { "file": "syntax.md", "category": "math" }
+  },
+
+  "constructs": {
+    "table": { "file": "tables.md", "triggers": "triggers.md" },
+    "function": { "file": "functions.md", "testing": "unit-testing.md" },
+    "query": { "file": "apis.md", "auth": "security.md" },
+    "api_group": { "file": "apis.md" },
+    "task": { "file": "tasks.md" },
+    "agent": { "file": "agents.md", "tools": "tools.md" },
+    "tool": { "file": "tools.md", "mcp": "mcp-servers.md" },
+    "mcp_server": { "file": "mcp-servers.md", "triggers": "triggers.md" },
+    "table_trigger": { "file": "triggers.md", "section": "table-trigger" },
+    "realtime_trigger": { "file": "triggers.md", "section": "realtime-trigger" },
+    "workspace_trigger": { "file": "triggers.md", "section": "workspace-trigger" },
+    "agent_trigger": { "file": "triggers.md", "section": "agent-trigger" },
+    "mcp_server_trigger": { "file": "triggers.md", "section": "mcp-server-trigger" },
+    "addon": { "file": "addons.md" },
+    "middleware": { "file": "middleware.md" },
+    "realtime_channel": { "file": "realtime.md" }
+  },
+
+  "operations": {
+    "db.query": { "file": "database.md" },
+    "db.get": { "file": "database.md" },
+    "db.has": { "file": "database.md" },
+    "db.add": { "file": "database.md" },
+    "db.edit": { "file": "database.md" },
+    "db.patch": { "file": "database.md" },
+    "db.del": { "file": "database.md" },
+    "db.truncate": { "file": "database.md" },
+    "api.request": { "file": "integrations/external-apis.md" },
+    "function.run": { "file": "functions.md" },
+    "redis.get": { "file": "integrations/redis.md" },
+    "redis.set": { "file": "integrations/redis.md" },
+    "storage.s3_put": { "file": "integrations/cloud-storage.md" },
+    "storage.s3_get": { "file": "integrations/cloud-storage.md" }
+  },
+
+  "tasks": {
+    "authentication": ["security.md", "apis.md"],
+    "authorization": ["security.md"],
+    "rate_limiting": ["security.md", "integrations/redis.md"],
+    "error_handling": ["syntax.md", "quickstart.md"],
+    "pagination": ["database.md", "apis.md"],
+    "file_upload": ["integrations/cloud-storage.md", "streaming.md"],
+    "caching": ["performance.md", "integrations/redis.md"],
+    "search": ["integrations/search.md"],
+    "email": ["integrations/utilities.md"],
+    "scheduled_jobs": ["tasks.md"],
+    "realtime": ["realtime.md", "triggers.md"],
+    "ai_agents": ["agents.md", "tools.md", "mcp-servers.md"]
+  }
+}

package/dist/xanoscript_docs/frontend.md

@@ -286,3 +286,13 @@ The tool will:
 2. **Centralize API calls** - Single `api.js` file
 3. **Store tokens securely** - localStorage for web, secure storage for mobile
 4. **Test incrementally** - Migrate one feature at a time
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `apis` | Backend API endpoints |
+| `workspace` | Workspace configuration |
+| `security` | CORS and authentication |

package/dist/xanoscript_docs/functions.md

@@ -6,6 +6,10 @@ applyTo: "function/**/*.xs"
 
 Reusable logic blocks in XanoScript.
 
+> **TL;DR:** Define with `function "name" { input { } stack { } response = $result }`. Call with `function.run "name" { input = { } } as $result`. Empty input blocks need braces on separate lines.
+
+---
+
 ## Quick Reference
 
 ```xs

package/dist/xanoscript_docs/integrations/cloud-storage.md

@@ -0,0 +1,142 @@
+---
+applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs"
+---
+
+# Cloud Storage Integrations
+
+> **TL;DR:** `cloud.aws.s3.*` for AWS, `cloud.azure.storage.*` for Azure, `cloud.google.storage.*` for GCP. All support upload, read, delete, and signed URLs.
+
+## Quick Reference
+
+| Provider | Prefix | Operations |
+|----------|--------|------------|
+| AWS S3 | `cloud.aws.s3.*` | upload_file, read_file, sign_url, list_directory, delete_file |
+| Azure Blob | `cloud.azure.storage.*` | upload_file, read_file, sign_url |
+| Google Cloud | `cloud.google.storage.*` | upload_file, read_file, sign_url |
+
+---
+
+## AWS S3
+
+### Upload File
+```xs
+cloud.aws.s3.upload_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "uploads/" ~ $input.filename
+  file = $input.file
+} as $result
+```
+
+### Read File
+```xs
+cloud.aws.s3.read_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "data/config.json"
+} as $file
+```
+
+### Sign URL
+```xs
+cloud.aws.s3.sign_url {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "private/document.pdf"
+  ttl = 300
+} as $signed_url
+```
+
+### List Directory
+```xs
+cloud.aws.s3.list_directory {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  prefix = "uploads/"
+} as $files
+```
+
+### Delete File
+```xs
+cloud.aws.s3.delete_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "temp/old-file.txt"
+}
+```
+
+---
+
+## Azure Blob Storage
+
+```xs
+cloud.azure.storage.upload_file {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "files"
+  filePath = "uploads/doc.pdf"
+  file = $input.file
+}
+
+cloud.azure.storage.read_file {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "files"
+  filePath = "data/config.json"
+} as $file
+
+cloud.azure.storage.sign_url {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "private"
+  path = "document.pdf"
+  ttl = 300
+} as $url
+```
+
+---
+
+## Google Cloud Storage
+
+```xs
+cloud.google.storage.upload_file {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "uploads/file.pdf"
+  file = $input.file
+}
+
+cloud.google.storage.read_file {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "data/config.json"
+} as $file
+
+cloud.google.storage.sign_url {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "private/doc.pdf"
+  method = "GET"
+  ttl = 300
+} as $url
+```
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `streaming` | Streaming large files |
+| `integrations` | All integrations index |
+| `integrations/utilities` | Local storage operations |

package/dist/xanoscript_docs/integrations/external-apis.md

@@ -0,0 +1,201 @@
+---
+applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs"
+---
+
+# External APIs
+
+> **TL;DR:** Use `api.request` for HTTP requests to external APIs. The `params` parameter is for the **request body** (not query params). Response in `$result.response.result`.
+
+## Quick Reference
+
+```xs
+api.request {
+  url = "https://api.example.com/endpoint"
+  method = "POST"                    // GET, POST, PUT, PATCH, DELETE
+  params = $payload                  // Request body for POST/PUT/PATCH
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+  timeout = 30                       // Timeout in seconds
+} as $api_result
+
+// Access response
+$api_result.response.status          // HTTP status code (200, 404, etc.)
+$api_result.response.result          // Response body (auto-parsed JSON)
+$api_result.response.headers         // Response headers array
+```
+
+> **Important:** The `params` parameter is used for the **request body** (POST/PUT/PATCH), not query parameters. This naming is counterintuitive but consistent across XanoScript.
+
+> **Note:** The `headers` parameter expects an array of text strings, where each string contains the header name and value separated by a colon (e.g., `["Content-Type: application/json", "X-Custom-Header: value"]`).
+
+---
+
+## GET Request
+
+```xs
+api.request {
+  url = "https://api.example.com/users?page=1&limit=10"
+  method = "GET"
+  headers = ["Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+var $users { value = $api_result.response.result }
+```
+
+---
+
+## POST Request with JSON Body
+
+```xs
+var $payload {
+  value = {
+    name: $input.name,
+    email: $input.email
+  }
+}
+
+api.request {
+  url = "https://api.example.com/users"
+  method = "POST"
+  params = $payload
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+// Check for success
+precondition ($api_result.response.status == 201) {
+  error_type = "standard"
+  error = "Failed to create user: " ~ ($api_result.response.result|json_encode)
+}
+```
+
+---
+
+## Error Handling Pattern
+
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "GET"
+  timeout = 30
+} as $api_result
+
+conditional {
+  if ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+    var $data { value = $api_result.response.result }
+  }
+  elseif ($api_result.response.status == 404) {
+    throw { name = "NotFound", value = "Resource not found" }
+  }
+  else {
+    throw {
+      name = "APIError",
+      value = "API returned status " ~ ($api_result.response.status|to_text)
+    }
+  }
+}
+```
+
+---
+
+## Response Structure
+
+The `api.request` statement returns an object with both request and response details:
+
+```json
+{
+  "request": {
+    "url": "",       // The URL that was requested
+    "method": "",    // HTTP method used (GET, POST, etc.)
+    "headers": [],   // Array of request headers sent
+    "params": []     // Parameters sent with the request
+  },
+  "response": {
+    "headers": [],   // Array of response headers received
+    "result": "",    // Response body (can be any format: JSON, string, null, boolean, etc.)
+    "status": 200    // HTTP status code
+  }
+}
+```
+
+---
+
+## Accessing Response Data
+
+```xs
+api.request {
+  url = "https://api.example.com/users"
+  method = "GET"
+} as $api_result
+
+// Access the response body
+var $data { value = $api_result.response.result }
+
+// Check status code
+precondition ($api_result.response.status == 200) {
+  error_type = "standard"
+  error = "API request failed"
+}
+
+// Access a specific header
+var $content_type { value = $api_result.response.headers|first }
+```
+
+---
+
+## Common Patterns
+
+### Retry Logic
+
+```xs
+var $retries { value = 0 }
+var $success { value = false }
+
+while ($retries < 3 && $success == false) {
+  try_catch {
+    try {
+      api.request {
+        url = "https://api.example.com/data"
+        method = "GET"
+        timeout = 10
+      } as $api_result
+
+      conditional {
+        if ($api_result.response.status == 200) {
+          var.update $success { value = true }
+        }
+      }
+    }
+    catch {
+      var.update $retries { value = $retries + 1 }
+      util.sleep { value = 2 }
+    }
+  }
+}
+```
+
+### Webhook Callback
+
+```xs
+api.request {
+  url = $env.WEBHOOK_URL
+  method = "POST"
+  params = {
+    event: "order.created",
+    data: $order,
+    timestamp: now
+  }
+  headers = [
+    "Content-Type: application/json",
+    "X-Webhook-Signature: " ~ $signature
+  ]
+}
+```
+
+---
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| `syntax` | Error handling with try_catch |
+| `integrations/utilities` | Lambda invocation |
+| `integrations` | All integrations index |