@xano/developer-mcp 1.0.33 → 1.0.34

package/dist/xanoscript.js

@@ -21,6 +21,11 @@ export const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["**/*.xs"],
         description: "Expressions, operators, and filters for all XanoScript code",
     },
+    quickstart: {
+        file: "quickstart.md",
+        applyTo: ["**/*.xs"],
+        description: "Common patterns, quick reference, and common mistakes to avoid",
+    },
     types: {
         file: "types.md",
         applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tools/**/*.xs", "agents/**/*.xs"],

package/dist/xanoscript.test.js

@@ -11,6 +11,7 @@ describe("xanoscript module", () => {
             const expectedTopics = [
                 "readme",
                 "syntax",
+                "quickstart",
                 "types",
                 "tables",
                 "functions",
@@ -135,9 +136,10 @@ describe("xanoscript module", () => {
             const result = getDocsForFilePath("apis/test.xs");
             expect(result).not.toContain("readme");
         });
-        it("should put syntax first if not already matched", () => {
+        it("should include syntax and quickstart for .xs files", () => {
             const result = getDocsForFilePath("some/random/file.xs");
-            expect(result[0]).toBe("syntax");
+            expect(result).toContain("syntax");
+            expect(result).toContain("quickstart");
         });
     });
     describe("extractQuickReference", () => {

package/dist/xanoscript_docs/README.md

@@ -142,18 +142,35 @@ applyTo: "function/**/*.xs"
 
 This helps AI tools apply the correct documentation based on the file being edited.
 
+## Getting Started
+
+For common patterns and quick examples, use:
+```
+xanoscript_docs({ topic: "quickstart" })
+```
+
+This includes:
+- Variable declaration patterns
+- Conditional logic (if/elseif/else)
+- API requests with error handling
+- Database CRUD operations
+- Common mistakes to avoid
+
+---
+
 ## Documentation Index
 
 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             |
+| Topic        | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| `quickstart` | Common patterns, quick examples, mistakes to avoid   |
+| `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
 
@@ -210,3 +227,47 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 | ------------- | ------------------------------------------------------------ |
 | `performance` | Performance optimization best practices                      |
 | `security`    | Security best practices for authentication and authorization |
+
+---
+
+## Example Implementations
+
+Common integration patterns you can reference:
+
+### External API Integrations
+- **OpenAI/ChatGPT**: Use `api.request` with POST to `/v1/chat/completions`
+- **Stripe**: Use `api.request` with form-encoded params for payments
+- **SendGrid/Resend**: Use `api.request` or `util.send_email` for emails
+- **Slack/Discord**: Use `api.request` with webhook URLs
+- **Twilio**: Use `api.request` with Basic auth for SMS
+
+### Common Pattern: API Integration Function
+
+```xs
+function "call_external_api" {
+  input {
+    text endpoint
+    object payload
+  }
+  stack {
+    api.request {
+      url = $env.API_BASE_URL ~ $input.endpoint
+      method = "POST"
+      params = $input.payload
+      headers = [
+        "Content-Type: application/json",
+        "Authorization: Bearer " ~ $env.API_KEY
+      ]
+      timeout = 30
+    } as $api_result
+
+    precondition ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+      error_type = "standard"
+      error = "API error: " ~ ($api_result.response.status|to_text)
+    }
+  }
+  response = $api_result.response.result
+}
+```
+
+For more patterns, see `xanoscript_docs({ topic: "quickstart" })` or `xanoscript_docs({ topic: "integrations" })`.

package/dist/xanoscript_docs/integrations.md

@@ -575,22 +575,92 @@ util.send_email {
 
 ---
 
-## External APIs
+## External APIs (api.request)
 
 Make HTTP requests to external APIs.
 
+### Quick Reference
+
 ```xs
 api.request {
-  url = "https://api.example.com/data"
-  method = "POST"
-  params = { key: "value" }
+  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 = 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:

package/dist/xanoscript_docs/quickstart.md

@@ -0,0 +1,340 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Quickstart & Common Patterns
+
+Essential patterns for XanoScript development. Use this as a quick reference for frequently-used code patterns.
+
+## Quick Reference
+
+### Variable Declaration
+```xs
+var $name { value = "initial value" }
+var $count { value = 0 }
+var $data { value = { key: "value" } }
+```
+
+### Conditional Logic
+```xs
+conditional {
+  if (`$status == "active"`) {
+    var $result { value = "Active user" }
+  }
+  elseif (`$status == "pending"`) {
+    var $result { value = "Pending approval" }
+  }
+  else {
+    var $result { value = "Unknown status" }
+  }
+}
+```
+
+### API Request with Error Handling
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "POST"
+  params = $payload
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+precondition ($api_result.response.status == 200) {
+  error_type = "standard"
+  error = "API request failed"
+}
+
+var $data { value = $api_result.response.result }
+```
+
+### String Concatenation
+```xs
+var $greeting { value = "Hello, " ~ $input.name ~ "!" }
+
+// With filters (use parentheses)
+var $message { value = "Status: " ~ ($status|to_text) ~ " - " ~ ($data|json_encode) }
+```
+
+---
+
+## Common Patterns
+
+### 1. Input Validation
+
+```xs
+// Required field check
+precondition ($input.email != null && $input.email != "") {
+  error_type = "inputerror"
+  error = "Email is required"
+}
+
+// Format validation
+precondition ($input.email|contains:"@") {
+  error_type = "inputerror"
+  error = "Invalid email format"
+}
+```
+
+### 2. Database CRUD
+
+```xs
+// Create
+db.add "user" {
+  data = { name: $input.name, email: $input.email }
+} as $new_user
+
+// Read one
+db.get "user" {
+  where = $db.user.id == $input.id
+} as $user
+
+// Read many
+db.query "user" {
+  where = $db.user.is_active == true
+  order = [{ field: created_at, direction: desc }]
+  paging = { limit: 10, offset: 0 }
+} as $users
+
+// Update
+db.edit "user" {
+  where = $db.user.id == $input.id
+  data = { name: $input.name }
+}
+
+// Delete
+db.delete "user" {
+  where = $db.user.id == $input.id
+}
+```
+
+### 3. Optional Field Handling
+
+```xs
+// Build object with optional fields
+var $data { value = { required_field: $input.required } }
+
+conditional {
+  if ($input.optional_field != null) {
+    var.update $data { value = $data|set:"optional_field":$input.optional_field }
+  }
+}
+
+// Or use set_ifnotnull
+var $data {
+  value = { required: $input.required }|set_ifnotnull:"optional":$input.optional
+}
+```
+
+### 4. Loop Through Array
+
+```xs
+// Using each
+each ($items as $item) {
+  debug.log { value = $item.name }
+}
+
+// Using map filter
+var $names { value = $items|map:$$.name }
+
+// Using filter
+var $active_items { value = $items|filter:$$.is_active == true }
+```
+
+### 5. Error Handling with Try-Catch
+
+```xs
+try_catch {
+  try {
+    api.request {
+      url = "https://api.example.com/risky"
+      method = "GET"
+    } as $result
+  }
+  catch {
+    debug.log { value = "Request failed, using fallback" }
+    var $result { value = { response: { result: null } } }
+  }
+}
+```
+
+### 6. Authentication Check
+
+```xs
+// Require authenticated user
+precondition ($auth.id != null) {
+  error_type = "accessdenied"
+  error = "Authentication required"
+}
+
+// Check user owns resource
+db.get "post" {
+  where = $db.post.id == $input.post_id
+} as $post
+
+precondition ($post.user_id == $auth.id) {
+  error_type = "accessdenied"
+  error = "You can only edit your own posts"
+}
+```
+
+### 7. Pagination
+
+```xs
+var $page { value = $input.page ?? 1 }
+var $limit { value = $input.limit ?? 20 }
+var $offset { value = ($page - 1) * $limit }
+
+db.query "item" {
+  where = $db.item.is_active == true
+  order = [{ field: created_at, direction: desc }]
+  paging = { limit: $limit, offset: $offset }
+  count = true
+} as $result
+
+response = {
+  items: $result.items,
+  total: $result.count,
+  page: $page,
+  pages: ($result.count / $limit)|ceil
+}
+```
+
+### 8. Building Complex Objects
+
+```xs
+// Step by step
+var $response { value = {} }
+var.update $response { value = $response|set:"user":$user }
+var.update $response { value = $response|set:"posts":$posts }
+var.update $response { value = $response|set:"stats":{ count: $posts|count } }
+
+// Or all at once
+var $response {
+  value = {
+    user: $user,
+    posts: $posts,
+    stats: { count: $posts|count }
+  }
+}
+```
+
+### 9. Date/Time Operations
+
+```xs
+// Current timestamp
+var $now { value = now }
+
+// Format for display
+var $formatted { value = now|format_timestamp:"Y-m-d H:i:s":"UTC" }
+
+// Relative time
+var $yesterday { value = now|transform_timestamp:"-1 day" }
+var $next_week { value = now|transform_timestamp:"+7 days" }
+
+// Compare dates
+db.query "event" {
+  where = $db.event.start_date >= now
+} as $upcoming_events
+```
+
+### 10. JSON API Response
+
+```xs
+api.request {
+  url = "https://api.openai.com/v1/chat/completions"
+  method = "POST"
+  params = {
+    model: "gpt-4",
+    messages: [{ role: "user", content: $input.prompt }]
+  }
+  headers = [
+    "Content-Type: application/json",
+    "Authorization: Bearer " ~ $env.OPENAI_API_KEY
+  ]
+} as $api_result
+
+conditional {
+  if ($api_result.response.status == 200) {
+    var $answer { value = $api_result.response.result.choices|first|get:"message"|get:"content" }
+  }
+  else {
+    throw {
+      name = "APIError",
+      value = "OpenAI API error: " ~ ($api_result.response.status|to_text)
+    }
+  }
+}
+```
+
+---
+
+## Common Mistakes
+
+### 1. Using `else if` instead of `elseif`
+```xs
+// ❌ Wrong
+conditional {
+  if (...) { }
+  else if (...) { }  // Parse error!
+}
+
+// ✅ Correct
+conditional {
+  if (...) { }
+  elseif (...) { }
+}
+```
+
+### 2. Missing parentheses in filter concatenation
+```xs
+// ❌ Wrong
+var $msg { value = $status|to_text ~ " - " ~ $data|json_encode }
+
+// ✅ Correct
+var $msg { value = ($status|to_text) ~ " - " ~ ($data|json_encode) }
+```
+
+### 3. Using `body` instead of `params` for api.request
+```xs
+// ❌ Wrong
+api.request {
+  url = "..."
+  method = "POST"
+  body = $payload  // "body" is not valid!
+}
+
+// ✅ Correct
+api.request {
+  url = "..."
+  method = "POST"
+  params = $payload  // Use "params" for request body
+}
+```
+
+### 4. Using `default` filter (doesn't exist)
+```xs
+// ❌ Wrong
+var $value { value = $input.optional|default:"fallback" }
+
+// ✅ Correct
+var $value { value = $input.optional|first_notnull:"fallback" }
+// or
+var $value { value = $input.optional ?? "fallback" }
+```
+
+### 5. Using $env in run.job input blocks
+```xs
+// ❌ Wrong - $env not allowed in input blocks
+run.job "my_job" {
+  input {
+    text api_key = $env.API_KEY
+  }
+}
+
+// ✅ Correct - use $env in the stack
+run.job "my_job" {
+  stack {
+    var $api_key { value = $env.API_KEY }
+  }
+}
+```

package/dist/xanoscript_docs/syntax.md

@@ -21,12 +21,67 @@ Complete reference for XanoScript expressions, operators, and filters.
 | Filter | Purpose | Example |
 |--------|---------|---------|
 | `trim` | Remove whitespace | `$s\|trim` |
-| `lower` / `upper` | Case conversion | `$s\|to_lower` |
+| `to_lower` / `to_upper` | Case conversion | `$s\|to_lower` |
 | `first` / `last` | Array endpoints | `$arr\|first` |
 | `count` | Array/object length | `$arr\|count` |
 | `get` | Object property | `$obj\|get:"key"` |
 | `set` | Set property | `$obj\|set:"key":"val"` |
 | `json_encode` / `json_decode` | JSON conversion | `$obj\|json_encode` |
+| `to_text` / `to_int` | Type conversion | `$num\|to_text` |
+
+> **Note:** There is no `default` filter. Use conditional blocks or `first_notnull`/`first_notempty` instead.
+
+### String Concatenation with Filters
+
+When concatenating strings that use filters, wrap each filtered expression in parentheses:
+
+```xs
+// ✅ Correct - parentheses around filtered expressions
+var $message {
+  value = ($status|to_text) ~ ": " ~ ($data|json_encode)
+}
+
+// ❌ Incorrect - missing parentheses causes parse error
+var $message {
+  value = $status|to_text ~ ": " ~ $data|json_encode
+}
+```
+
+---
+
+## Conditional Blocks
+
+Use `conditional` blocks for if/elseif/else logic:
+
+```xs
+conditional {
+  if (`$status == "success"`) {
+    var $message { value = "All good!" }
+  }
+  elseif (`$status == "pending"`) {
+    var $message { value = "Please wait..." }
+  }
+  else {
+    var $message { value = "Unknown status" }
+  }
+}
+```
+
+> **Important:** Use `elseif` (one word), not `else if` or `else { if (...) }`. Nested `if` inside `else` blocks is not supported.
+
+### Conditional as Expression
+
+Use conditional blocks inline to return values:
+
+```xs
+var $tier_limit {
+  value = conditional {
+    if ($auth.tier == "premium") { 1000 }
+    elseif ($auth.tier == "pro") { 500 }
+    else { 100 }
+  }
+}
+```
 
 ---
 
@@ -431,6 +486,32 @@ var $client_ip { value = $env.$remote_ip }
 var $method { value = $env.$request_method }
 var $headers { value = $env.$http_headers }
 var $current_branch { value = $env.$branch }
+
+// Custom environment variables (set in Xano dashboard)
+var $api_key { value = $env.MY_API_KEY }
+```
+
+### $env Limitations
+
+> **Important:** `$env` variables cannot be used in `run.job` or `run.service` input blocks. Input values must be constants.
+
+```xs
+// ❌ Invalid - $env not allowed in run.job input
+run.job "my_job" {
+  input {
+    text api_key = $env.API_KEY    // Error!
+  }
+}
+
+// ✅ Valid - access $env inside the stack instead
+run.job "my_job" {
+  input {
+    text api_key                   // No default value
+  }
+  stack {
+    var $key { value = $env.API_KEY }
+  }
+}
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.33",
+  "version": "1.0.34",
   "description": "MCP server and library for Xano development - XanoScript validation, Meta API, Run API, and CLI documentation",
   "type": "module",
   "main": "dist/lib.js",