@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/testing.md

@@ -0,0 +1,335 @@
+---
+applyTo: "functions/**/*.xs, apis/**/*.xs"
+---
+
+# Testing
+
+Unit tests and mocking in XanoScript.
+
+## Quick Reference
+
+```xs
+function "<name>" {
+  input { ... }
+  stack { ... }
+  response = $result
+
+  test "<test name>" {
+    input = { key: value }
+    expect.<assertion> ($response) { value = expected }
+  }
+}
+```
+
+### Assertions
+| Assertion | Purpose |
+|-----------|---------|
+| `expect.to_equal` | Exact match |
+| `expect.to_not_equal` | Not equal |
+| `expect.to_be_true` | Is true |
+| `expect.to_be_false` | Is false |
+| `expect.to_be_null` | Is null |
+| `expect.to_contain` | Array contains |
+| `expect.to_match` | Regex match |
+| `expect.to_throw` | Throws error |
+
+---
+
+## Basic Test
+
+```xs
+function "add" {
+  input {
+    int a
+    int b
+  }
+  stack {
+    var $sum { value = $input.a + $input.b }
+  }
+  response = $sum
+
+  test "adds two numbers" {
+    input = { a: 5, b: 3 }
+    expect.to_equal ($response) { value = 8 }
+  }
+
+  test "handles negative numbers" {
+    input = { a: -5, b: 3 }
+    expect.to_equal ($response) { value = -2 }
+  }
+}
+```
+
+---
+
+## Assertions
+
+### Value Assertions
+
+```xs
+# Equality
+expect.to_equal ($response.status) { value = "active" }
+expect.to_not_equal ($response.status) { value = "deleted" }
+
+# Boolean
+expect.to_be_true ($response.is_active)
+expect.to_be_false ($response.is_deleted)
+
+# Null
+expect.to_be_null ($response.deleted_at)
+expect.to_not_be_null ($response.created_at)
+
+# Defined
+expect.to_be_defined ($response.id)
+expect.to_not_be_defined ($response.optional_field)
+
+# Empty
+expect.to_be_empty ($response.errors)
+```
+
+### Comparison Assertions
+
+```xs
+# Numeric comparisons
+expect.to_be_greater_than ($response.total) { value = 100 }
+expect.to_be_less_than ($response.stock) { value = 10 }
+
+# Range
+expect.to_be_within ($response.temperature) {
+  min = 20
+  max = 30
+}
+```
+
+### String Assertions
+
+```xs
+# Starts/ends with
+expect.to_start_with ($response.name) { value = "John" }
+expect.to_end_with ($response.file) { value = ".pdf" }
+
+# Contains
+expect.to_contain ($response.tags) { value = "featured" }
+
+# Regex match
+expect.to_match ($response.phone) { value = "^\\+1\\d{10}$" }
+```
+
+### Time Assertions
+
+```xs
+expect.to_be_in_the_past ($response.created_at)
+expect.to_be_in_the_future ($response.expires_at)
+```
+
+### Error Assertions
+
+```xs
+# Expects any error
+test "throws on invalid input" {
+  input = { amount: -1 }
+  expect.to_throw
+}
+
+# Expects specific error
+test "throws validation error" {
+  input = { amount: -1 }
+  expect.to_throw { value = "InvalidInputError" }
+}
+```
+
+---
+
+## Mocking
+
+Mock external calls to isolate tests:
+
+```xs
+function "get_weather" {
+  input { text city }
+  stack {
+    api.request {
+      url = "https://api.weather.com/current"
+      params = { city: $input.city }
+      mock = {
+        "returns sunny for Paris": { response: { weather: "sunny", temp: 22 } },
+        "returns rainy for London": { response: { weather: "rainy", temp: 15 } }
+      }
+    } as $weather
+  }
+  response = $weather.response
+
+  test "returns sunny for Paris" {
+    input = { city: "Paris" }
+    expect.to_equal ($response.weather) { value = "sunny" }
+  }
+
+  test "returns rainy for London" {
+    input = { city: "London" }
+    expect.to_equal ($response.weather) { value = "rainy" }
+  }
+}
+```
+
+### Mock Matching
+
+Mocks activate when their key matches the test name:
+
+```xs
+stack {
+  api.request {
+    url = "https://api.example.com/data"
+    mock = {
+      "test name here": { response: { ... } },
+      "another test": { response: { ... } }
+    }
+  } as $result
+}
+```
+
+### Mocking Variables
+
+```xs
+stack {
+  var $message {
+    value = "Hello " ~ $input.name
+    mock = {
+      "custom greeting": "Custom greeting!"
+    }
+  }
+}
+```
+
+---
+
+## Testing API Endpoints
+
+```xs
+query "products/{id}" verb=GET {
+  input {
+    int id { table = "product" }
+  }
+  stack {
+    db.get "product" {
+      field_name = "id"
+      field_value = $input.id
+      mock = {
+        "returns product": { id: 1, name: "Widget", price: 29.99 },
+        "handles not found": null
+      }
+    } as $product
+  }
+  response = $product
+
+  test "returns product" {
+    input = { id: 1 }
+    expect.to_equal ($response.name) { value = "Widget" }
+  }
+
+  test "handles not found" {
+    input = { id: 999 }
+    expect.to_be_null ($response)
+  }
+}
+```
+
+---
+
+## Testing Error Cases
+
+```xs
+function "validate_age" {
+  input { int age }
+  stack {
+    precondition ($input.age >= 0) {
+      error_type = "inputerror"
+      error = "Age cannot be negative"
+    }
+    precondition ($input.age <= 150) {
+      error_type = "inputerror"
+      error = "Age is unrealistic"
+    }
+  }
+  response = { valid: true }
+
+  test "accepts valid age" {
+    input = { age: 25 }
+    expect.to_equal ($response.valid) { value = true }
+  }
+
+  test "rejects negative age" {
+    input = { age: -5 }
+    expect.to_throw { value = "Age cannot be negative" }
+  }
+
+  test "rejects unrealistic age" {
+    input = { age: 200 }
+    expect.to_throw { value = "Age is unrealistic" }
+  }
+}
+```
+
+---
+
+## Complete Example
+
+```xs
+function "calculate_discount" {
+  input {
+    decimal subtotal filters=min:0
+    enum customer_type { values = ["regular", "premium", "vip"] }
+    text coupon?
+  }
+  stack {
+    var $discount_rate { value = 0 }
+
+    switch ($input.customer_type) {
+      case ("premium") { var.update $discount_rate { value = 0.1 } } break
+      case ("vip") { var.update $discount_rate { value = 0.2 } } break
+      default { var.update $discount_rate { value = 0 } }
+    }
+
+    conditional {
+      if ($input.coupon == "SAVE10") {
+        math.add $discount_rate { value = 0.1 }
+      }
+    }
+
+    var $discount { value = $input.subtotal * $discount_rate }
+  }
+  response = { discount: $discount, rate: $discount_rate }
+
+  test "no discount for regular customer" {
+    input = { subtotal: 100, customer_type: "regular" }
+    expect.to_equal ($response.discount) { value = 0 }
+  }
+
+  test "10% discount for premium" {
+    input = { subtotal: 100, customer_type: "premium" }
+    expect.to_equal ($response.discount) { value = 10 }
+  }
+
+  test "20% discount for VIP" {
+    input = { subtotal: 100, customer_type: "vip" }
+    expect.to_equal ($response.discount) { value = 20 }
+  }
+
+  test "coupon stacks with VIP discount" {
+    input = { subtotal: 100, customer_type: "vip", coupon: "SAVE10" }
+    expect.to_equal ($response.rate) { value = 0.3 }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Test happy paths** - Verify expected behavior works
+2. **Test edge cases** - Empty arrays, null values, boundaries
+3. **Test error cases** - Invalid inputs, missing data
+4. **Use mocks** - Isolate from external dependencies
+5. **Descriptive test names** - Explain what's being tested
+6. **One assertion focus** - Each test verifies one behavior
+7. **Keep tests independent** - No shared state between tests
+8. **Test at boundaries** - Min/max values, length limits

package/xanoscript_docs/tools.md

@@ -0,0 +1,305 @@
+---
+applyTo: "tools/**/*.xs"
+---
+
+# Tools
+
+Functions that AI agents and MCP servers can execute.
+
+## Quick Reference
+
+```xs
+tool "<name>" {
+  description = "Internal documentation"
+  instructions = "How the AI should use this tool"
+  input { ... }
+  stack { ... }
+  response = $result
+}
+```
+
+---
+
+## Basic Structure
+
+```xs
+tool "get_user_by_email" {
+  description = "Look up user by email address"
+  instructions = "Use this to find user details when you have their email."
+
+  input {
+    email email filters=lower {
+      description = "The user's email address"
+    }
+  }
+
+  stack {
+    db.get "user" {
+      field_name = "email"
+      field_value = $input.email
+    } as $user
+  }
+
+  response = $user
+}
+```
+
+---
+
+## Key Fields
+
+| Field | Purpose | Visibility |
+|-------|---------|------------|
+| `description` | Internal documentation | Not sent to AI |
+| `instructions` | How AI should use tool | Sent to AI |
+| `input` | Parameters with descriptions | Sent to AI |
+| `stack` | Execution logic | Not sent to AI |
+| `response` | Return value | Sent to AI |
+
+**Important:** `instructions` and input `description` fields are sent to the AI. Write them clearly.
+
+---
+
+## Input Block
+
+Same as functions, but descriptions are especially important:
+
+```xs
+input {
+  int order_id {
+    description = "The unique order ID to look up"
+  }
+  enum status {
+    description = "New status to set"
+    values = ["pending", "processing", "shipped", "delivered"]
+  }
+  text reason? {
+    description = "Optional reason for the status change"
+  }
+}
+```
+
+---
+
+## Tool-Specific Statements
+
+### api.call
+Call an API endpoint:
+
+```xs
+stack {
+  api.call "orders/get" verb=GET {
+    api_group = "orders"
+    input = { order_id: $input.order_id }
+  } as $order
+}
+```
+
+### task.call
+Trigger a background task:
+
+```xs
+stack {
+  task.call "send_notification" as $result
+}
+```
+
+### tool.call
+Call another tool:
+
+```xs
+stack {
+  tool.call "get_user_by_id" {
+    input = { user_id: $input.user_id }
+  } as $user
+}
+```
+
+---
+
+## Common Patterns
+
+### Database Lookup
+```xs
+tool "get_order_status" {
+  instructions = "Check the current status of an order by its ID."
+  input {
+    int order_id { description = "Order ID to check" }
+  }
+  stack {
+    db.get "order" {
+      field_name = "id"
+      field_value = $input.order_id
+    } as $order
+  }
+  response = {
+    order_id: $order.id,
+    status: $order.status,
+    updated_at: $order.updated_at
+  }
+}
+```
+
+### Database Update
+```xs
+tool "update_order_status" {
+  instructions = "Update an order's status. Use when customer requests changes."
+  input {
+    int order_id { description = "Order ID to update" }
+    enum status {
+      description = "New status"
+      values = ["pending", "processing", "shipped", "cancelled"]
+    }
+  }
+  stack {
+    db.edit "order" {
+      field_name = "id"
+      field_value = $input.order_id
+      data = { status: $input.status, updated_at: now }
+    } as $order
+  }
+  response = $order
+}
+```
+
+### External API Call
+```xs
+tool "get_weather" {
+  instructions = "Get current weather for a city."
+  input {
+    text city filters=trim { description = "City name" }
+  }
+  stack {
+    api.request {
+      url = "https://api.weather.com/current"
+      method = "GET"
+      params = { q: $input.city, key: $env.WEATHER_API_KEY }
+    } as $weather
+  }
+  response = {
+    city: $input.city,
+    temperature: $weather.temp,
+    conditions: $weather.conditions
+  }
+}
+```
+
+### Search Tool
+```xs
+tool "search_products" {
+  instructions = "Search products by name or category."
+  input {
+    text query? { description = "Search term" }
+    text category? { description = "Category filter" }
+    int limit?=10 { description = "Max results (default 10)" }
+  }
+  stack {
+    db.query "product" {
+      where = $db.product.name includes? $input.query
+        && $db.product.category ==? $input.category
+        && $db.product.is_active == true
+      return = { type: "list", paging: { page: 1, per_page: $input.limit } }
+    } as $products
+  }
+  response = $products.items
+}
+```
+
+### Create Record
+```xs
+tool "create_ticket" {
+  instructions = "Create a support ticket for the customer."
+  input {
+    text subject filters=trim { description = "Ticket subject" }
+    text description filters=trim { description = "Issue description" }
+    enum priority?="medium" {
+      description = "Ticket priority"
+      values = ["low", "medium", "high", "urgent"]
+    }
+  }
+  stack {
+    db.add "ticket" {
+      data = {
+        subject: $input.subject,
+        description: $input.description,
+        priority: $input.priority,
+        status: "open",
+        created_at: now
+      }
+    } as $ticket
+  }
+  response = { ticket_id: $ticket.id, message: "Ticket created" }
+}
+```
+
+### Composed Tool
+```xs
+tool "get_order_with_items" {
+  instructions = "Get complete order details including all items."
+  input {
+    int order_id { description = "Order ID" }
+  }
+  stack {
+    tool.call "get_order_status" {
+      input = { order_id: $input.order_id }
+    } as $order
+
+    db.query "order_item" {
+      where = $db.order_item.order_id == $input.order_id
+    } as $items
+  }
+  response = {
+    order: $order,
+    items: $items
+  }
+}
+```
+
+---
+
+## Error Handling
+
+```xs
+tool "cancel_order" {
+  instructions = "Cancel an order. Only works for pending orders."
+  input {
+    int order_id { description = "Order to cancel" }
+  }
+  stack {
+    db.get "order" {
+      field_name = "id"
+      field_value = $input.order_id
+    } as $order
+
+    precondition ($order != null) {
+      error_type = "notfound"
+      error = "Order not found"
+    }
+
+    precondition ($order.status == "pending") {
+      error_type = "standard"
+      error = "Only pending orders can be cancelled"
+    }
+
+    db.edit "order" {
+      field_name = "id"
+      field_value = $input.order_id
+      data = { status: "cancelled" }
+    } as $updated
+  }
+  response = { success: true, order_id: $input.order_id }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Write clear instructions** - This is what the AI reads to understand the tool
+2. **Describe all inputs** - Help AI construct valid requests
+3. **Use enums for fixed options** - Reduces AI errors
+4. **Keep tools focused** - One task per tool
+5. **Handle errors gracefully** - Return clear error messages
+6. **Validate inputs** - Use filters and preconditions
+7. **Limit response size** - Don't return huge datasets
+8. **Use composition** - Call other tools for complex operations