@xano/developer-mcp 1.0.0 → 1.0.2

package/xanoscript_docs/agents.md

@@ -0,0 +1,329 @@
+---
+applyTo: "agents/**/*.xs"
+---
+
+# Agents
+
+AI-powered agents that use LLMs to perform tasks autonomously.
+
+## Quick Reference
+
+```xs
+agent "<name>" {
+  canonical = "<unique-id>"
+  description = "What this agent does"
+  llm = {
+    type: "<provider>"
+    system_prompt: "Agent instructions"
+    prompt: "{{ $args.message }}"
+    max_steps: 5
+  }
+  tools = [{ name: "<tool-name>" }]
+}
+```
+
+### LLM Providers
+| Provider | Type Value |
+|----------|------------|
+| Xano Free (Gemini) | `xano-free` |
+| Google Gemini | `google-genai` |
+| OpenAI | `openai` |
+| Anthropic | `anthropic` |
+
+---
+
+## Basic Structure
+
+```xs
+agent "Customer Support" {
+  canonical = "support-agent-v1"
+  description = "Handles customer inquiries"
+  llm = {
+    type: "xano-free"
+    system_prompt: "You are a helpful customer support agent."
+    prompt: "{{ $args.user_message }}"
+    max_steps: 5
+    temperature: 0.7
+  }
+  tools = [
+    { name: "get_order_status" },
+    { name: "create_ticket" }
+  ]
+}
+```
+
+---
+
+## Calling Agents
+
+```xs
+ai.agent.run "Customer Support" {
+  args = {}|set:"user_message":$input.message
+  allow_tool_execution = true
+} as $response
+```
+
+---
+
+## LLM Configuration
+
+### Common Properties
+
+```xs
+llm = {
+  type: "<provider>"                    # Required
+  system_prompt: "..."                  # Agent persona and rules
+  prompt: "{{ $args.input }}"           # User input template
+  max_steps: 5                          # Max LLM calls per run
+}
+```
+
+### Dynamic Variables
+- `{{ $args.<name> }}` - Runtime arguments
+- `{{ $env.<name> }}` - Environment variables (for API keys)
+
+---
+
+## Provider Configurations
+
+### Xano Free (for testing)
+```xs
+llm = {
+  type: "xano-free"
+  system_prompt: "You are a helpful assistant."
+  prompt: "{{ $args.message }}"
+  max_steps: 3
+  temperature: 0
+  search_grounding: false               # Google Search grounding
+}
+```
+
+### Google Gemini
+```xs
+llm = {
+  type: "google-genai"
+  api_key: "{{ $env.GEMINI_API_KEY }}"
+  model: "gemini-2.5-flash"
+  system_prompt: "You are a helpful assistant."
+  prompt: "{{ $args.message }}"
+  max_steps: 5
+  temperature: 0.2
+  thinking_tokens: 10000                # Extended thinking
+  include_thoughts: true
+}
+```
+
+### OpenAI
+```xs
+llm = {
+  type: "openai"
+  api_key: "{{ $env.OPENAI_API_KEY }}"
+  model: "gpt-5-mini"
+  system_prompt: "You are a helpful assistant."
+  prompt: "{{ $args.message }}"
+  max_steps: 5
+  temperature: 0.8
+  reasoning_effort: "medium"            # low, medium, high
+}
+```
+
+**OpenAI-Compatible APIs:**
+```xs
+llm = {
+  type: "openai"
+  api_key: "{{ $env.GROQ_API_KEY }}"
+  baseURL: "https://api.groq.com/openai/v1"
+  model: "llama-3.3-70b-versatile"
+  compatibility: "compatible"           # Required for non-OpenAI
+  ...
+}
+```
+
+Supported: Groq, Mistral, OpenRouter, X.AI
+
+### Anthropic Claude
+```xs
+llm = {
+  type: "anthropic"
+  api_key: "{{ $env.ANTHROPIC_API_KEY }}"
+  model: "claude-sonnet-4-5-20250929"
+  system_prompt: "You are a helpful assistant."
+  prompt: "{{ $args.message }}"
+  max_steps: 8
+  temperature: 0.3
+  send_reasoning: true                  # Include thinking blocks
+}
+```
+
+---
+
+## Structured Outputs
+
+Force JSON response format (disables tools):
+
+```xs
+agent "Classifier" {
+  canonical = "classifier-v1"
+  llm = {
+    type: "openai"
+    api_key: "{{ $env.OPENAI_API_KEY }}"
+    model: "gpt-5-mini"
+    system_prompt: "Classify the sentiment of the text."
+    prompt: "{{ $args.text }}"
+    structured_outputs: true
+
+    output {
+      enum sentiment { values = ["positive", "negative", "neutral"] }
+      decimal confidence filters=min:0|max:1
+      text reasoning?
+    }
+  }
+  tools = []
+}
+```
+
+---
+
+## Tools
+
+Reference tools by name from `tools/` directory:
+
+```xs
+tools = [
+  { name: "get_user_by_email" },
+  { name: "update_order_status" },
+  { name: "send_notification" }
+]
+```
+
+**Important:** Do not describe tools in system_prompt or prompt. Tool descriptions are automatically provided to the LLM.
+
+---
+
+## Prompting
+
+### Using Twig Templates
+```xs
+llm = {
+  prompt: """
+    User ID: {{ $args.user_id }}
+    Request: {{ $args.message }}
+
+    {% if $args.is_priority %}
+    This is a priority customer. Respond within 5 minutes.
+    {% endif %}
+  """
+}
+```
+
+### Available Variables
+```xs
+{{ $args.any_arg }}                     # Runtime arguments
+{{ $env.MY_VAR }}                       # Environment variables
+{{ "now"|date("Y-m-d") }}               # Current date
+```
+
+---
+
+## Complete Examples
+
+### Task Manager Agent
+```xs
+agent "Task Manager" {
+  canonical = "task-mgr-v1"
+  description = "Manages user tasks"
+  llm = {
+    type: "google-genai"
+    api_key: "{{ $env.GEMINI_API_KEY }}"
+    model: "gemini-2.5-flash"
+    system_prompt: """
+      You help users manage their tasks. You can:
+      - Add new tasks
+      - Mark tasks complete
+      - List pending tasks
+      Always confirm actions with the user.
+    """
+    prompt: "User {{ $args.user_id }}: {{ $args.message }}"
+    max_steps: 5
+    temperature: 0.2
+  }
+  tools = [
+    { name: "add_task" },
+    { name: "complete_task" },
+    { name: "list_tasks" }
+  ]
+}
+```
+
+### Code Review Agent
+```xs
+agent "Code Reviewer" {
+  canonical = "code-review-v1"
+  llm = {
+    type: "anthropic"
+    api_key: "{{ $env.ANTHROPIC_API_KEY }}"
+    model: "claude-sonnet-4-5-20250929"
+    system_prompt: """
+      You are an expert code reviewer. Analyze code for:
+      - Bugs and potential issues
+      - Security vulnerabilities
+      - Performance problems
+      - Code style and best practices
+      Provide specific, actionable feedback.
+    """
+    prompt: """
+      Language: {{ $args.language }}
+      Code:
+      ```
+      {{ $args.code }}
+      ```
+    """
+    max_steps: 3
+    temperature: 0.1
+    send_reasoning: true
+  }
+  tools = []
+}
+```
+
+### Multi-Tool Research Agent
+```xs
+agent "Research Assistant" {
+  canonical = "research-v1"
+  llm = {
+    type: "openai"
+    api_key: "{{ $env.OPENAI_API_KEY }}"
+    model: "gpt-5"
+    system_prompt: """
+      You are a research assistant. Use your tools to:
+      1. Search for relevant information
+      2. Analyze data
+      3. Compile findings into clear summaries
+      Always cite your sources.
+    """
+    prompt: "Research topic: {{ $args.topic }}"
+    max_steps: 10
+    temperature: 0.5
+    reasoning_effort: "high"
+  }
+  tools = [
+    { name: "web_search" },
+    { name: "fetch_article" },
+    { name: "analyze_data" },
+    { name: "save_findings" }
+  ]
+}
+```
+
+---
+
+## Best Practices
+
+1. **Clear system prompts** - Define persona, capabilities, and constraints
+2. **Use appropriate temperature** - Low for factual, higher for creative
+3. **Limit max_steps** - Prevent infinite loops (3-10 typical)
+4. **Don't repeat tool descriptions** - They're auto-injected
+5. **Use environment variables** - Never hardcode API keys
+6. **Keep prompts focused** - One task per agent
+7. **Test with xano-free first** - Free for development
+8. **Use structured outputs** - When you need consistent JSON

package/xanoscript_docs/apis.md

@@ -0,0 +1,343 @@
+---
+applyTo: "apis/**/*.xs"
+---
+
+# APIs
+
+HTTP endpoint definitions in XanoScript.
+
+## Quick Reference
+
+```xs
+query "<path>" verb=<METHOD> {
+  description = "What this endpoint does"
+  auth = "<table>"              # Optional: require authentication
+  input { ... }
+  stack { ... }
+  response = $result
+}
+```
+
+### HTTP Methods
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+
+### File Structure
+```
+apis/
+├── users/                      # API group
+│   ├── list.xs                 # GET /users
+│   ├── create.xs               # POST /users
+│   └── {id}.xs                 # GET/PATCH/DELETE /users/{id}
+└── products/
+    └── search.xs
+```
+
+---
+
+## Basic Structure
+
+```xs
+query "products" verb=GET {
+  description = "List all products"
+  input {
+    int page?=1 filters=min:1
+    int per_page?=20 filters=min:1|max:100
+  }
+  stack {
+    db.query "product" {
+      return = { type: "list", paging: { page: $input.page, per_page: $input.per_page } }
+    } as $products
+  }
+  response = $products
+}
+```
+
+---
+
+## Authentication
+
+### Public Endpoint (default)
+```xs
+query "status" verb=GET {
+  stack { }
+  response = { status: "ok" }
+}
+```
+
+### Authenticated Endpoint
+```xs
+query "profile" verb=GET {
+  auth = "user"                 # Requires valid JWT
+  stack {
+    db.get "user" {
+      field_name = "id"
+      field_value = $auth.id    # User ID from token
+    } as $user
+  }
+  response = $user
+}
+```
+
+When `auth` is set:
+- Endpoint requires Bearer token in `Authorization` header
+- `$auth.id` contains authenticated user's ID
+- Invalid/missing token returns 401
+
+---
+
+## Path Parameters
+
+Use `{param}` in the path:
+
+```xs
+query "users/{user_id}" verb=GET {
+  auth = "user"
+  input {
+    int user_id { table = "user" }
+  }
+  stack {
+    db.get "user" {
+      field_name = "id"
+      field_value = $input.user_id
+    } as $user
+  }
+  response = $user
+}
+```
+
+---
+
+## CRUD Examples
+
+### List (GET)
+```xs
+query "products" verb=GET {
+  input {
+    text category? filters=trim|lower
+    int page?=1
+    int per_page?=20
+  }
+  stack {
+    db.query "product" {
+      where = $db.product.category ==? $input.category
+      sort = { created_at: "desc" }
+      return = { type: "list", paging: { page: $input.page, per_page: $input.per_page } }
+    } as $products
+  }
+  response = $products
+}
+```
+
+### Create (POST)
+```xs
+query "products" verb=POST {
+  auth = "user"
+  input {
+    text name filters=trim
+    text description? filters=trim
+    decimal price filters=min:0
+    int category_id { table = "category" }
+  }
+  stack {
+    db.add "product" {
+      data = {
+        name: $input.name,
+        description: $input.description,
+        price: $input.price,
+        category_id: $input.category_id,
+        created_by: $auth.id
+      }
+    } as $product
+  }
+  response = $product
+}
+```
+
+### Read (GET with ID)
+```xs
+query "products/{product_id}" verb=GET {
+  input {
+    int product_id { table = "product" }
+  }
+  stack {
+    db.get "product" {
+      field_name = "id"
+      field_value = $input.product_id
+    } as $product
+
+    precondition ($product != null) {
+      error_type = "notfound"
+      error = "Product not found"
+    }
+  }
+  response = $product
+}
+```
+
+### Update (PATCH)
+```xs
+query "products/{product_id}" verb=PATCH {
+  auth = "user"
+  input {
+    int product_id { table = "product" }
+    text name? filters=trim
+    text description? filters=trim
+    decimal price? filters=min:0
+  }
+  stack {
+    var $updates { value = {} }
+
+    conditional {
+      if ($input.name != null) {
+        var.update $updates { value = $updates|set:"name":$input.name }
+      }
+    }
+    conditional {
+      if ($input.price != null) {
+        var.update $updates { value = $updates|set:"price":$input.price }
+      }
+    }
+
+    db.patch "product" {
+      field_name = "id"
+      field_value = $input.product_id
+      data = $updates
+    } as $product
+  }
+  response = $product
+}
+```
+
+### Delete (DELETE)
+```xs
+query "products/{product_id}" verb=DELETE {
+  auth = "user"
+  input {
+    int product_id { table = "product" }
+  }
+  stack {
+    db.del "product" {
+      field_name = "id"
+      field_value = $input.product_id
+    }
+  }
+  response = { success: true }
+}
+```
+
+---
+
+## Response Types
+
+### JSON (default)
+```xs
+response = $data
+```
+
+### HTML
+```xs
+stack {
+  util.set_header {
+    value = "Content-Type: text/html; charset=utf-8"
+    duplicates = "replace"
+  }
+
+  util.template_engine {
+    value = """
+      <html>
+        <body><h1>{{ $var.title }}</h1></body>
+      </html>
+    """
+  } as $html
+}
+response = $html
+```
+
+### Streaming
+```xs
+stack {
+  api.stream { value = $processed_data }
+}
+response = null
+```
+
+---
+
+## Custom Headers
+
+```xs
+stack {
+  util.set_header {
+    value = "X-Custom-Header: value"
+    duplicates = "replace"
+  }
+
+  util.set_header {
+    value = "Set-Cookie: session=abc123; HttpOnly; Secure"
+    duplicates = "add"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Preconditions
+```xs
+stack {
+  precondition ($input.amount > 0) {
+    error_type = "inputerror"
+    error = "Amount must be positive"
+  }
+
+  precondition ($user != null) {
+    error_type = "notfound"
+    error = "User not found"
+  }
+
+  precondition ($user.id == $auth.id) {
+    error_type = "accessdenied"
+    error = "Not authorized"
+  }
+}
+```
+
+### Error Types
+| Type | HTTP Status |
+|------|-------------|
+| `inputerror` | 400 Bad Request |
+| `accessdenied` | 403 Forbidden |
+| `notfound` | 404 Not Found |
+| `standard` | 500 Internal Server Error |
+
+---
+
+## Pagination Response Format
+
+When using `return = { type: "list", paging: {...} }`:
+
+```json
+{
+  "itemsReceived": 20,
+  "curPage": 1,
+  "nextPage": 2,
+  "prevPage": null,
+  "offset": 0,
+  "perPage": 20,
+  "items": [...]
+}
+```
+
+---
+
+## Best Practices
+
+1. **RESTful design** - Use appropriate HTTP methods
+2. **Consistent naming** - Use lowercase, hyphens for multi-word paths
+3. **Authenticate sensitive operations** - Always auth for writes
+4. **Validate inputs** - Use filters and preconditions
+5. **Return appropriate errors** - Use correct error types
+6. **Paginate lists** - Never return unbounded lists
+7. **Document with description** - Explain what endpoint does
+8. **Group related endpoints** - Organize by resource in api groups