@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/README.md

@@ -1 +1,107 @@
-# xanoscript-ai-documentation
+# XanoScript Documentation
+
+XanoScript is the declarative scripting language for [Xano](https://xano.com), a no-code/low-code backend platform. Use it to define database schemas, API endpoints, functions, scheduled tasks, and AI agents.
+
+## Quick Reference
+
+| Construct | File Location | Purpose |
+|-----------|---------------|---------|
+| `table` | `tables/*.xs` | Database schema definition |
+| `function` | `functions/**/*.xs` | Reusable logic blocks |
+| `query` | `apis/<group>/*.xs` | HTTP API endpoints |
+| `task` | `tasks/*.xs` | Scheduled/cron jobs |
+| `agent` | `agents/**/*.xs` | AI-powered agents |
+| `tool` | `tools/**/*.xs` | Tools for AI agents |
+| `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
+| `addon` | `addons/*.xs` | Subqueries for related data |
+
+## Workspace Structure
+
+```
+project/
+├── tables/              # Database table schemas
+├── functions/           # Reusable functions (supports subfolders)
+├── apis/
+│   └── <api-group>/     # API endpoints grouped by domain
+├── tasks/               # Scheduled jobs
+├── agents/              # AI agents
+├── tools/               # AI tools
+├── mcp_servers/         # MCP server definitions
+├── addons/              # Query addons
+├── static/              # Frontend files (HTML, CSS, JS)
+└── ephemeral/           # Temporary test environments
+```
+
+## Environment Variables
+
+Access with `$env.<name>`. Built-in variables:
+
+| Variable | Description |
+|----------|-------------|
+| `$env.$remote_ip` | Client IP address |
+| `$env.$http_headers` | Request headers array |
+| `$env.$request_uri` | Request URI |
+| `$env.$request_method` | HTTP method (GET, POST, etc.) |
+| `$env.$request_querystring` | Query string |
+| `$env.$datasource` | Current datasource |
+| `$env.$branch` | Current branch |
+
+Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
+
+## Core Syntax Patterns
+
+### Block Structure
+```xs
+<construct> "<name>" {
+  input { ... }      # Parameters (optional)
+  stack { ... }      # Logic
+  response = $var    # Output
+}
+```
+
+### Variable Access
+```xs
+$input.field        # Input parameters
+$var.field          # Stack variables
+$auth.id            # Authenticated user ID
+$env.MY_VAR         # Environment variable
+$db.table.field     # Database field reference (in queries)
+$this               # Current item in loops/maps
+```
+
+### Filters (Pipe Syntax)
+```xs
+$value|trim|lower                    # Chain filters
+$input.name|strlen                   # Get length
+$array|first                         # First element
+($a + $b)|round:2                    # Math with precision
+```
+
+## File Frontmatter
+
+Documentation files use frontmatter to specify which file patterns they apply to:
+
+```markdown
+---
+applyTo: "functions/**/*.xs"
+---
+```
+
+This helps AI tools apply the correct documentation based on the file being edited.
+
+## Documentation Index
+
+1. [Syntax Reference](syntax.md) - Expressions, operators, filters
+2. [Types & Inputs](types.md) - Data types, validation, input blocks
+3. [Tables](tables.md) - Database schema definitions
+4. [Functions](functions.md) - Reusable function stacks
+5. [APIs](apis.md) - HTTP endpoint definitions
+6. [Tasks](tasks.md) - Scheduled jobs
+7. [Database Operations](database.md) - Query, add, edit, delete
+8. [Agents](agents.md) - AI agent configuration
+9. [Tools](tools.md) - AI tools for agents
+10. [MCP Servers](mcp-servers.md) - Model Context Protocol servers
+11. [Testing](testing.md) - Unit tests and mocking
+12. [Integrations](integrations.md) - Cloud services, Redis, security
+13. [Frontend](frontend.md) - Static frontend development
+14. [Ephemeral](ephemeral.md) - Temporary environments

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