@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/integrations.md

@@ -0,0 +1,439 @@
+---
+applyTo: "functions/**/*.xs, apis/**/*.xs, tasks/*.xs"
+---
+
+# Integrations
+
+Cloud services, Redis, storage, and security operations.
+
+## Quick Reference
+
+### Cloud Storage
+| Provider | Prefix |
+|----------|--------|
+| AWS S3 | `cloud.aws.s3.*` |
+| Azure Blob | `cloud.azure.storage.*` |
+| Google Cloud | `cloud.google.storage.*` |
+
+### Search
+| Provider | Prefix |
+|----------|--------|
+| Elasticsearch | `cloud.elasticsearch.*` |
+| AWS OpenSearch | `cloud.aws.opensearch.*` |
+| Algolia | `cloud.algolia.*` |
+
+### Other
+| Service | Prefix |
+|---------|--------|
+| Redis | `redis.*` |
+| Storage | `storage.*` |
+| Security | `security.*` |
+
+---
+
+## AWS S3
+
+### Upload File
+```xs
+cloud.aws.s3.upload_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "uploads/" ~ $input.filename
+  file = $input.file
+} as $result
+```
+
+### Read File
+```xs
+cloud.aws.s3.read_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "data/config.json"
+} as $file
+```
+
+### Sign URL
+```xs
+cloud.aws.s3.sign_url {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "private/document.pdf"
+  ttl = 300
+} as $signed_url
+```
+
+### List Directory
+```xs
+cloud.aws.s3.list_directory {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  prefix = "uploads/"
+} as $files
+```
+
+### Delete File
+```xs
+cloud.aws.s3.delete_file {
+  bucket = "my-bucket"
+  region = "us-east-1"
+  key = $env.AWS_ACCESS_KEY
+  secret = $env.AWS_SECRET_KEY
+  file_key = "temp/old-file.txt"
+}
+```
+
+---
+
+## Azure Blob Storage
+
+```xs
+cloud.azure.storage.upload_file {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "files"
+  filePath = "uploads/doc.pdf"
+  file = $input.file
+}
+
+cloud.azure.storage.read_file {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "files"
+  filePath = "data/config.json"
+} as $file
+
+cloud.azure.storage.sign_url {
+  account_name = $env.AZURE_ACCOUNT
+  account_key = $env.AZURE_KEY
+  container_name = "private"
+  path = "document.pdf"
+  ttl = 300
+} as $url
+```
+
+---
+
+## Google Cloud Storage
+
+```xs
+cloud.google.storage.upload_file {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "uploads/file.pdf"
+  file = $input.file
+}
+
+cloud.google.storage.read_file {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "data/config.json"
+} as $file
+
+cloud.google.storage.sign_url {
+  service_account = $env.GCP_SERVICE_ACCOUNT
+  bucket = "my-bucket"
+  filePath = "private/doc.pdf"
+  method = "GET"
+  ttl = 300
+} as $url
+```
+
+---
+
+## Elasticsearch
+
+```xs
+# Search
+cloud.elasticsearch.query {
+  auth_type = "API Key"
+  key_id = $env.ES_KEY_ID
+  access_key = $env.ES_ACCESS_KEY
+  base_url = "https://my-cluster.es.io"
+  index = "products"
+  return_type = "search"
+  expression = [{ field: "category", value: "electronics", op: "eq" }]
+  size = 10
+  sort = [{ field: "price", order: "asc" }]
+} as $results
+
+# Document operations
+cloud.elasticsearch.document {
+  auth_type = "API Key"
+  key_id = $env.ES_KEY_ID
+  access_key = $env.ES_ACCESS_KEY
+  base_url = "https://my-cluster.es.io"
+  index = "products"
+  method = "GET"
+  doc_id = "product-123"
+} as $doc
+```
+
+---
+
+## Redis
+
+### Key-Value Operations
+```xs
+# Set value
+redis.set {
+  key = "user:123:session"
+  data = $session_data
+  ttl = 3600                            # Expires in 1 hour
+}
+
+# Get value
+redis.get { key = "user:123:session" } as $session
+
+# Check exists
+redis.has { key = "user:123:session" } as $exists
+
+# Delete
+redis.del { key = "user:123:session" }
+```
+
+### Counters
+```xs
+# Increment
+redis.incr {
+  key = "page_views"
+  by = 1
+} as $new_count
+
+# Decrement
+redis.decr {
+  key = "inventory:item-123"
+  by = 1
+} as $new_count
+```
+
+### Lists
+```xs
+# Push to end
+redis.push {
+  key = "queue:tasks"
+  value = $task
+} as $length
+
+# Push to front
+redis.unshift {
+  key = "queue:priority"
+  value = $urgent_task
+}
+
+# Pop from end
+redis.pop { key = "queue:tasks" } as $task
+
+# Pop from front
+redis.shift { key = "queue:tasks" } as $task
+
+# Get range
+redis.range {
+  key = "recent:logs"
+  start = 0
+  stop = 9
+} as $logs
+
+# Count
+redis.count { key = "queue:tasks" } as $count
+```
+
+### Rate Limiting
+```xs
+redis.ratelimit {
+  key = "api:" ~ $env.$remote_ip
+  max = 100
+  ttl = 60
+  error = "Rate limit exceeded"
+} as $status
+```
+
+---
+
+## Local Storage
+
+### File Operations
+```xs
+# Create file resource
+storage.create_file_resource {
+  filename = "report.csv"
+  filedata = $csv_content
+} as $file
+
+# Read file resource
+storage.read_file_resource {
+  value = $input.file
+} as $content
+
+# Delete file
+storage.delete_file { pathname = "temp/old-file.txt" }
+```
+
+### Image/Attachment Handling
+```xs
+# Create image metadata
+storage.create_image {
+  value = $input.image
+  access = "public"
+  filename = "profile.jpg"
+} as $image_meta
+
+# Create attachment metadata
+storage.create_attachment {
+  value = $input.file
+  access = "private"
+  filename = "document.pdf"
+} as $attachment_meta
+
+# Sign private URL
+storage.sign_private_url {
+  pathname = "private/document.pdf"
+  ttl = 300
+} as $signed_url
+```
+
+---
+
+## Security
+
+### Password Hashing
+```xs
+# Password is auto-hashed on insert
+db.add "user" {
+  data = { email: $input.email, password: $input.password }
+}
+
+# Verify password
+security.check_password {
+  text_password = $input.password
+  hash_password = $user.password
+} as $is_valid
+```
+
+### Auth Tokens
+```xs
+security.create_auth_token {
+  table = "user"
+  id = $user.id
+  extras = { role: $user.role }
+  expiration = 86400
+} as $token
+```
+
+### Encryption
+```xs
+# Encrypt
+security.encrypt {
+  data = $sensitive_data
+  algorithm = "aes-256-cbc"
+  key = $env.ENCRYPTION_KEY
+  iv = $env.ENCRYPTION_IV
+} as $encrypted
+
+# Decrypt
+security.decrypt {
+  data = $encrypted
+  algorithm = "aes-256-cbc"
+  key = $env.ENCRYPTION_KEY
+  iv = $env.ENCRYPTION_IV
+} as $decrypted
+```
+
+### JWT (JWS/JWE)
+```xs
+# Sign JWT
+security.jws_encode {
+  claims = { user_id: $user.id, role: $user.role }
+  key = $env.JWT_SECRET
+  signature_algorithm = "HS256"
+  ttl = 3600
+} as $token
+
+# Verify JWT
+security.jws_decode {
+  token = $input.token
+  key = $env.JWT_SECRET
+  signature_algorithm = "HS256"
+} as $claims
+```
+
+### Random Generation
+```xs
+security.create_uuid as $uuid
+security.random_number { min = 1, max = 100 } as $random
+security.random_bytes { length = 32 } as $bytes
+security.create_password {
+  character_count = 16
+  require_lowercase = true
+  require_uppercase = true
+  require_digit = true
+  require_symbol = true
+} as $password
+```
+
+---
+
+## Email
+
+```xs
+util.send_email {
+  service_provider = "resend"
+  api_key = $env.RESEND_API_KEY
+  to = $user.email
+  from = "noreply@example.com"
+  subject = "Welcome!"
+  message = "Thanks for signing up."
+  reply_to = "support@example.com"
+} as $result
+```
+
+---
+
+## External APIs
+
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "POST"
+  params = { key: "value" }
+  headers = []|push:("Authorization: Bearer " ~ $env.API_KEY)
+  timeout = 30
+} as $response
+```
+
+---
+
+## Utilities
+
+```xs
+# Template engine (Twig)
+util.template_engine {
+  value = """
+    Hello {{ $var.name }}!
+    {% for item in $var.items %}
+    - {{ item.name }}
+    {% endfor %}
+  """
+} as $rendered
+
+# IP lookup
+util.ip_lookup { value = $env.$remote_ip } as $location
+
+# Geo distance
+util.geo_distance {
+  latitude_1 = 40.71
+  longitude_1 = -74.00
+  latitude_2 = 34.05
+  longitude_2 = -118.24
+} as $distance_km
+
+# Sleep
+util.sleep { value = 5 }
+```

package/xanoscript_docs/mcp-servers.md

@@ -0,0 +1,190 @@
+---
+applyTo: "mcp_servers/**/*.xs"
+---
+
+# MCP Servers
+
+Model Context Protocol servers that expose tools to external AI clients.
+
+## Quick Reference
+
+```xs
+mcp_server "<name>" {
+  canonical = "<unique-id>"
+  description = "Internal documentation"
+  instructions = "How to use this server's tools"
+  tags = ["category"]
+  tools = [{ name: "<tool-name>" }]
+}
+```
+
+---
+
+## Basic Structure
+
+```xs
+mcp_server "Customer Support" {
+  canonical = "support-mcp-v1"
+  description = "Tools for customer support agents"
+  instructions = "Use these tools to help customers with orders and accounts."
+  tags = ["support", "customer"]
+  tools = [
+    { name: "get_order_status" },
+    { name: "update_order" },
+    { name: "create_ticket" }
+  ]
+}
+```
+
+---
+
+## Key Fields
+
+| Field | Purpose | Required |
+|-------|---------|----------|
+| `canonical` | Unique identifier | Yes |
+| `description` | Internal documentation | No |
+| `instructions` | Server-level AI guidance | No |
+| `tags` | Organization/categorization | No |
+| `tools` | List of exposed tools | Yes |
+
+---
+
+## Tools Block
+
+Reference tools from `tools/` directory by name:
+
+```xs
+tools = [
+  { name: "get_user_details" },
+  { name: "search_products" },
+  { name: "create_order" }
+]
+```
+
+Tool names must exactly match `.xs` file names in `tools/`.
+
+---
+
+## Examples
+
+### Task Management Server
+```xs
+mcp_server "Task Manager" {
+  canonical = "task-mgr-mcp"
+  description = "Task management tools for productivity agents"
+  instructions = "Manages user tasks. All tools relate to the authenticated user's records."
+  tags = ["productivity", "internal"]
+  tools = [
+    { name: "add_task" },
+    { name: "list_tasks" },
+    { name: "complete_task" },
+    { name: "delete_task" }
+  ]
+}
+```
+
+### E-commerce Server
+```xs
+mcp_server "Store Operations" {
+  canonical = "store-ops-v1"
+  instructions = "Tools for managing an e-commerce store. Handle products, orders, and inventory."
+  tags = ["ecommerce", "admin"]
+  tools = [
+    { name: "search_products" },
+    { name: "get_product" },
+    { name: "update_inventory" },
+    { name: "get_order" },
+    { name: "update_order_status" },
+    { name: "process_refund" }
+  ]
+}
+```
+
+### Analytics Server
+```xs
+mcp_server "Analytics" {
+  canonical = "analytics-mcp"
+  description = "Data analysis and reporting tools"
+  instructions = "Query and analyze business data. Use for generating reports and insights."
+  tags = ["analytics", "reporting"]
+  tools = [
+    { name: "get_sales_summary" },
+    { name: "get_user_metrics" },
+    { name: "generate_report" },
+    { name: "export_data" }
+  ]
+}
+```
+
+### CRM Server
+```xs
+mcp_server "CRM" {
+  canonical = "crm-mcp-v2"
+  instructions = """
+    Customer Relationship Management tools.
+    - Use contact tools for customer info
+    - Use deal tools for sales pipeline
+    - Use activity tools for interaction logging
+  """
+  tags = ["crm", "sales"]
+  tools = [
+    { name: "search_contacts" },
+    { name: "get_contact" },
+    { name: "create_contact" },
+    { name: "update_contact" },
+    { name: "list_deals" },
+    { name: "create_deal" },
+    { name: "log_activity" }
+  ]
+}
+```
+
+---
+
+## Server Organization
+
+### By Domain
+```
+mcp_servers/
+├── support.xs          # Customer support tools
+├── ecommerce.xs        # Store management
+├── analytics.xs        # Reporting and metrics
+└── admin.xs            # Administrative functions
+```
+
+### By Access Level
+```
+mcp_servers/
+├── public.xs           # Public-facing tools
+├── authenticated.xs    # Requires auth
+└── admin.xs            # Admin-only tools
+```
+
+---
+
+## Connecting to MCP Servers
+
+MCP servers expose a standardized endpoint that AI clients can connect to:
+
+1. Client connects to MCP endpoint
+2. Server returns available tools with schemas
+3. Client can call tools and receive responses
+
+The MCP protocol handles:
+- Tool discovery
+- Input validation
+- Response formatting
+- Error handling
+
+---
+
+## Best Practices
+
+1. **Clear naming** - Server name should indicate its purpose
+2. **Memorable canonical IDs** - Use descriptive, stable identifiers
+3. **Comprehensive instructions** - Guide AI on server's overall purpose
+4. **Logical tool grouping** - Group related tools in one server
+5. **Use tags** - Organize servers by category
+6. **Keep focused** - One domain per server (support, analytics, etc.)
+7. **Document internally** - Use description for team documentation