@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/xanoscript_docs_auto/mcp-servers.md

@@ -0,0 +1,408 @@
+---
+applyTo: "mcp_servers/**/*.xs"
+---
+
+# MCP Servers
+
+Model Context Protocol (MCP) server definitions for exposing tools to AI systems.
+
+## Quick Reference
+
+```xs
+mcp_server "<name>" {
+  description = "Server description"
+  tools = [tool1, tool2]
+}
+```
+
+---
+
+## MCP Server Definition
+
+### Basic MCP Server
+
+```xs
+mcp_server "data_tools" {
+  description = "Tools for data access and manipulation"
+  tools = [
+    query_database,
+    search_products,
+    get_user_profile
+  ]
+}
+```
+
+### With Configuration
+
+```xs
+mcp_server "analytics_tools" {
+  description = "Analytics and reporting tools"
+  tools = [
+    get_dashboard_stats,
+    generate_report,
+    export_data
+  ]
+  auth = {
+    type = "api_key"
+    header = "X-API-Key"
+  }
+}
+```
+
+---
+
+## Server Properties
+
+| Property | Description |
+|----------|-------------|
+| `description` | Human-readable description |
+| `tools` | List of tool names to expose |
+| `auth` | Authentication configuration |
+| `resources` | Resource definitions |
+| `prompts` | Prompt templates |
+
+---
+
+## Defining Tools for MCP
+
+Tools exposed via MCP follow the standard tool format:
+
+```xs
+tool "query_database" {
+  description = "Execute a database query and return results"
+  input {
+    text table description="Table name to query"
+    json? filters description="Filter conditions"
+    int? limit description="Maximum results" default=100
+  }
+  stack {
+    db.query $input.table {
+      where = $input.filters
+      return = {type: "list", paging: {per_page: $input.limit}}
+    } as $results
+  }
+  response = $results
+}
+
+tool "search_products" {
+  description = "Search products by name or category"
+  input {
+    text? query description="Search query"
+    text? category description="Category filter"
+  }
+  stack {
+    db.query product {
+      where = $db.product.name ilike? ("%" ~ $input.query ~ "%")
+            && $db.product.category ==? $input.category
+    } as $products
+  }
+  response = $products
+}
+```
+
+---
+
+## Authentication
+
+### API Key Authentication
+
+```xs
+mcp_server "secure_tools" {
+  auth = {
+    type = "api_key"
+    header = "X-API-Key"
+    env_var = "MCP_API_KEY"
+  }
+  tools = [...]
+}
+```
+
+### Bearer Token
+
+```xs
+mcp_server "authenticated_tools" {
+  auth = {
+    type = "bearer"
+    env_var = "MCP_AUTH_TOKEN"
+  }
+  tools = [...]
+}
+```
+
+---
+
+## External MCP Servers
+
+### Call External MCP Tools
+
+```xs
+ai.external.mcp.tool.list {
+  server = "external_server_name"
+} as $available_tools
+
+ai.external.mcp.tool.run {
+  server = "external_server_name"
+  tool = "tool_name"
+  input = {
+    param1: "value1",
+    param2: "value2"
+  }
+} as $result
+```
+
+### Get Server Details
+
+```xs
+ai.external.mcp.server_details {
+  server = "external_server_name"
+} as $server_info
+```
+
+---
+
+## MCP Server Triggers
+
+Handle events from MCP server interactions:
+
+```xs
+mcp_server_trigger "log_tool_calls" {
+  server = "data_tools"
+  event = tool_call
+
+  stack {
+    db.add mcp_log {
+      data = {
+        server: $trigger.server,
+        tool: $trigger.tool,
+        input: $trigger.input|json_encode,
+        output: $trigger.output|json_encode,
+        client_id: $trigger.client_id,
+        created_at: now
+      }
+    }
+  }
+}
+```
+
+### Trigger Events
+
+| Event | Description |
+|-------|-------------|
+| `tool_call` | Tool was invoked |
+| `connection` | Client connected |
+| `disconnection` | Client disconnected |
+| `error` | Error occurred |
+
+---
+
+## Complete Example
+
+```xs
+// MCP Server Definition
+mcp_server "ecommerce_tools" {
+  description = "E-commerce data access tools for AI assistants"
+  tools = [
+    search_products,
+    get_product_details,
+    check_inventory,
+    get_order_status,
+    list_categories
+  ]
+}
+
+// Tool: Search Products
+tool "search_products" {
+  description = "Search for products by keyword, category, or price range"
+  input {
+    text? query description="Search keyword"
+    text? category description="Product category"
+    decimal? min_price description="Minimum price"
+    decimal? max_price description="Maximum price"
+    int? limit description="Max results" default=20
+  }
+  stack {
+    db.query product {
+      where = $db.product.active == true
+            && $db.product.name ilike? ("%" ~ $input.query ~ "%")
+            && $db.product.category ==? $input.category
+            && $db.product.price >=? $input.min_price
+            && $db.product.price <=? $input.max_price
+      order_by = {field: "name", direction: "asc"}
+      return = {type: "list", paging: {per_page: $input.limit}}
+    } as $products
+  }
+  response = $products|map:{
+    id: $$.id,
+    name: $$.name,
+    category: $$.category,
+    price: $$.price,
+    in_stock: $$.stock > 0
+  }
+}
+
+// Tool: Get Product Details
+tool "get_product_details" {
+  description = "Get detailed information about a specific product"
+  input {
+    int product_id description="The product ID"
+  }
+  stack {
+    db.get product {
+      field_name = "id"
+      field_value = $input.product_id
+    } as $product
+
+    conditional {
+      if ($product == null) {
+        return {
+          value = {error: "Product not found"}
+        }
+      }
+    }
+  }
+  response = {
+    id: $product.id,
+    name: $product.name,
+    description: $product.description,
+    category: $product.category,
+    price: $product.price,
+    sale_price: $product.sale_price,
+    stock: $product.stock,
+    attributes: $product.attributes,
+    images: $product.images
+  }
+}
+
+// Tool: Check Inventory
+tool "check_inventory" {
+  description = "Check stock availability for one or more products"
+  input {
+    array<int> product_ids description="List of product IDs to check"
+  }
+  stack {
+    db.query product {
+      where = $db.product.id in $input.product_ids
+    } as $products
+  }
+  response = $products|map:{
+    product_id: $$.id,
+    name: $$.name,
+    stock: $$.stock,
+    available: $$.stock > 0
+  }
+}
+
+// Tool: Get Order Status
+tool "get_order_status" {
+  description = "Get the current status of an order"
+  input {
+    text order_number description="Order number"
+  }
+  stack {
+    db.get order {
+      field_name = "order_number"
+      field_value = $input.order_number
+    } as $order
+
+    conditional {
+      if ($order == null) {
+        return {
+          value = {error: "Order not found"}
+        }
+      }
+    }
+  }
+  response = {
+    order_number: $order.order_number,
+    status: $order.status,
+    created_at: $order.created_at,
+    shipped_at: $order.shipped_at,
+    tracking_number: $order.tracking_number
+  }
+}
+
+// Tool: List Categories
+tool "list_categories" {
+  description = "Get all product categories"
+  stack {
+    db.query category {
+      where = $db.category.active == true
+      order_by = {field: "name", direction: "asc"}
+    } as $categories
+  }
+  response = $categories|map:{
+    id: $$.id,
+    name: $$.name,
+    product_count: $$.product_count
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### Clear Descriptions
+
+Write descriptions that help AI understand when to use each tool:
+
+```xs
+// Good
+description = "Search for products by name, category, or price range. Returns product ID, name, price, and availability."
+
+// Bad
+description = "Product search"
+```
+
+### Structured Responses
+
+Return well-structured data:
+
+```xs
+// Good: Clear structure with relevant fields
+response = {
+  success: true,
+  data: $results,
+  count: $results|count,
+  has_more: $total > $limit
+}
+
+// Bad: Raw database response
+response = $results
+```
+
+### Handle Errors Gracefully
+
+```xs
+tool "safe_operation" {
+  stack {
+    try_catch {
+      try {
+        // Operation
+      }
+      catch {
+        return {
+          value = {
+            success: false,
+            error: $error.message
+          }
+        }
+      }
+    }
+  }
+  response = {success: true, data: $result}
+}
+```
+
+### Limit Data Exposure
+
+Only expose necessary data:
+
+```xs
+// Don't expose sensitive fields
+response = $users|map:{
+  id: $$.id,
+  name: $$.name,
+  // Omit: email, password_hash, internal_notes
+}
+```