@xano/developer-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Xano, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# Xano Developer MCP
+
+A Model Context Protocol (MCP) server that provides AI assistants with comprehensive documentation and tools for developing applications on the Xano Headless API platform.
+
+## Overview
+
+This MCP server acts as a bridge between AI models and Xano's developer ecosystem, offering:
+
+- Complete Xano Headless API documentation
+- XanoScript code validation and syntax checking
+- XanoScript programming language documentation with examples
+- Development workflows and best practices
+
+## Quick Start
+
+### Claude Code (Recommended)
+
+```bash
+claude mcp add xano-developer -- npx -y @xano/developer-mcp
+```
+
+That's it! The MCP server will be automatically installed and configured.
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "xano-developer": {
+      "command": "npx",
+      "args": ["-y", "@xano/developer-mcp"]
+    }
+  }
+}
+```
+
+## Installation from Source
+
+### Prerequisites
+
+- Node.js (ES2022+ compatible)
+- npm
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/xano-inc/xano-developer-mcp.git
+cd xano-developer-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+# Production
+npm start
+
+# Development (build + run)
+npm run dev
+```
+
+The server communicates via stdio (standard input/output) using the JSON-RPC protocol, which is the standard transport for MCP servers.
+
+### Source Install Configuration
+
+If you installed from source, configure your MCP client to use the local build:
+
+**Claude Code:**
+```bash
+claude mcp add xano-developer node /path/to/xano-developer-mcp/dist/index.js
+```
+
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "xano-developer": {
+      "command": "node",
+      "args": ["/path/to/xano-developer-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### 1. `api_docs`
+
+Retrieves Xano Headless API documentation for specific resources.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `object` | string | No | Specific API resource to document |
+
+**Available Objects:**
+- `workspace` - Workspace management, branches, datasources, OpenAPI specs
+- `table` - Database table schema management
+- `api_group` - API groups and endpoints management
+- `function` - Reusable function library
+- `task` - Scheduled tasks (cron jobs)
+- `middleware` - Request/response middleware
+- `addon` - Response transformation queries
+- `agent` - AI agent configuration
+- `tool` - AI tool definitions for agents
+- `mcp_server` - Model Context Protocol server management
+- `realtime` - Realtime WebSocket channels
+- `triggers` - Event-driven triggers
+- `file` - File uploads and static hosting
+- `history` - Request history and audit logs
+- `authentication` - User authentication and session info
+
+**Example:**
+```
+api_docs({ object: "workspace" })
+```
+
+### 2. `validate_xanoscript`
+
+Validates XanoScript code for syntax errors. The language server auto-detects the object type from the code syntax.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `code` | string | Yes | The XanoScript code to validate |
+
+**Example:**
+```
+validate_xanoscript({
+  code: "var:result = 1 + 2"
+})
+```
+
+**Returns:** List of errors with line/column positions, or confirmation of validity.
+
+### 3. `xanoscript_docs`
+
+Retrieves XanoScript programming language documentation.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `keyword` | string | No | Documentation topic to retrieve |
+
+**Supported Keywords:**
+
+| Category | Keywords |
+|----------|----------|
+| Core Concepts | `function`, `api_query`, `table`, `task`, `tool`, `agent`, `mcp_server` |
+| Language Reference | `syntax`, `expressions`, `input`, `db_query`, `query_filter` |
+| Workflows | `workflow`, `function_workflow`, `api_workflow`, `table_workflow`, `task_workflow` |
+| Special Topics | `frontend`, `lovable`, `testing`, `tips`, `ephemeral` |
+
+**Aliases:** The tool supports keyword aliases for convenience:
+- `api`, `apis`, `query`, `endpoint` → `api_query`
+- `func` → `function`
+- `db` → `db_query`
+
+**Example:**
+```
+xanoscript_docs({ keyword: "function" })
+```
+
+## npm Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `build` | `tsc` | Compile TypeScript to JavaScript |
+| `start` | `node dist/index.js` | Run the MCP server |
+| `dev` | `tsc && node dist/index.js` | Build and run in development |
+| `sync-docs` | `npx ts-node scripts/sync-xanoscript-docs.ts` | Regenerate XanoScript documentation mapping |
+
+## Project Structure
+
+```
+xano-developer-mcp/
+├── src/
+│   ├── index.ts              # Main MCP server implementation
+│   └── xanoscript.d.ts       # TypeScript declarations
+├── dist/                      # Compiled JavaScript output
+├── scripts/
+│   └── sync-xanoscript-docs.ts  # Documentation sync script
+├── api_docs/                  # Xano API documentation (16 markdown files)
+│   ├── index.md
+│   ├── workspace.md
+│   ├── table.md
+│   └── ...
+├── xanoscript_docs/           # XanoScript language documentation
+│   ├── version.json
+│   ├── function_guideline.md
+│   ├── function_examples.md
+│   └── ...
+├── package.json
+└── tsconfig.json
+```
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@modelcontextprotocol/sdk` | 1.26.0 | Official MCP SDK |
+| `@xano/xanoscript-language-server` | 11.6.3 | XanoScript parser and validation |
+
+## How It Works
+
+```
+AI Client
+    │
+    ▼
+MCP Protocol (JSON-RPC over stdio)
+    │
+    ▼
+Xano Developer MCP Server
+    │
+    ├─► api_docs → Reads /api_docs/*.md files
+    │
+    ├─► validate_xanoscript → Parses code with XanoScript language server
+    │
+    └─► xanoscript_docs → Reads external XanoScript documentation
+```
+
+## Authentication
+
+The MCP server itself does not require authentication. However, when using the documented APIs to interact with actual Xano services, you will need appropriate Xano Headless API credentials.
+
+## Development
+
+### Syncing Documentation
+
+If the XanoScript documentation source changes, regenerate the mapping:
+
+```bash
+npm run sync-docs
+```
+
+This scans the xanoscript-ai-documentation directory and updates the documentation mapping in the server.
+
+### Building
+
+```bash
+npm run build
+```
+
+Compiles TypeScript to JavaScript in the `dist/` directory.
+
+## License
+
+See [LICENSE](LICENSE) for details.

package/api_docs/addon.md

@@ -0,0 +1,193 @@
+# Addon API
+
+Addons are reusable query components that can be attached to API responses to transform or enrich data. They're commonly used for joining related data or formatting output.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/addon` | List addons |
+| GET | `/workspace/{workspace_id}/addon/{addon_id}` | Get addon |
+| POST | `/workspace/{workspace_id}/addon` | Create addon |
+| PUT | `/workspace/{workspace_id}/addon/{addon_id}` | Update addon |
+| DELETE | `/workspace/{workspace_id}/addon/{addon_id}` | Delete addon |
+| PUT | `/workspace/{workspace_id}/addon/{addon_id}/security` | Update security |
+
+---
+
+## List Addons
+
+```
+GET /workspace/{workspace_id}/addon
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+
+---
+
+## Get Addon
+
+```
+GET /workspace/{workspace_id}/addon/{addon_id}
+```
+
+Returns addon definition including XanoScript.
+
+---
+
+## Create Addon
+
+```
+POST /workspace/{workspace_id}/addon
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+
+### XanoScript Addon Syntax
+
+```xanoscript
+addon foo {
+  input {
+    int foo_id {
+      dbtable = "foo"
+    }
+  }
+
+  stack {
+    db.query foo {
+      where = $db.foo.id == $input.foo_id
+      return = {type: "single"}
+    }
+  }
+}
+```
+
+### Input Section
+
+Define input parameters that link to database fields:
+
+```xanoscript
+input {
+  int user_id {
+    dbtable = "user"  // Links to user table
+  }
+}
+```
+
+The `dbtable` property specifies which table field to join on.
+
+### Stack Section
+
+Query logic to fetch related data:
+
+```xanoscript
+stack {
+  db.query user {
+    where = $db.user.id == $input.user_id
+    return = {type: "single"}
+  }
+}
+```
+
+### Use Cases
+
+- Join related data (e.g., fetch author for a post)
+- Computed fields
+- Data aggregation
+- Response transformation
+
+### Example: Author Addon
+
+```xanoscript
+addon author_info {
+  input {
+    int author_id {
+      dbtable = "user"
+    }
+  }
+
+  stack {
+    db.query user {
+      select = ["id", "name", "avatar"]
+      where = $db.user.id == $input.author_id
+      return = {type: "single"}
+    }
+  }
+}
+```
+
+### Example: Order Summary Addon
+
+```xanoscript
+addon order_summary {
+  input {
+    int order_id {
+      dbtable = "order"
+    }
+  }
+
+  stack {
+    // Get order items
+    db.query order_item {
+      where = $db.order_item.order_id == $input.order_id
+      return = {type: "list"}
+    }
+
+    // Calculate totals
+    var $item_count {
+      value = count($order_item)
+    }
+
+    var $total {
+      value = sum($order_item, "price")
+    }
+  }
+}
+```
+
+---
+
+## Update Addon
+
+```
+PUT /workspace/{workspace_id}/addon/{addon_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete Addon
+
+```
+DELETE /workspace/{workspace_id}/addon/{addon_id}
+```
+
+**Warning:** This action cannot be undone.
+
+---
+
+## Update Addon Security
+
+```
+PUT /workspace/{workspace_id}/addon/{addon_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |

package/api_docs/agent.md

@@ -0,0 +1,154 @@
+# Agent API
+
+Agents are AI-powered assistants that can use tools to accomplish tasks. They are configured with an LLM provider, system prompt, and available tools.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/agent` | List agents |
+| GET | `/workspace/{workspace_id}/agent/{agent_id}` | Get agent |
+| POST | `/workspace/{workspace_id}/agent` | Create agent |
+| PUT | `/workspace/{workspace_id}/agent/{agent_id}` | Update agent |
+| DELETE | `/workspace/{workspace_id}/agent/{agent_id}` | Delete agent |
+
+---
+
+## List Agents
+
+```
+GET /workspace/{workspace_id}/agent
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+| `tools` | bool | true | Include tool information |
+
+---
+
+## Get Agent
+
+```
+GET /workspace/{workspace_id}/agent/{agent_id}
+```
+
+**Query Parameters:**
+- `tools` (bool, default: true): Include tool information
+
+Returns agent definition including LLM configuration and XanoScript.
+
+---
+
+## Create Agent
+
+```
+POST /workspace/{workspace_id}/agent
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+- `tools` (bool): Include tool information in response
+
+### XanoScript Agent Syntax
+
+```xanoscript
+agent foo {
+  canonical = "custom"
+  llm = {
+    type         : "anthropic"
+    system_prompt: "You are a helpful AI Agent."
+    max_steps    : 5
+    prompt       : ""
+    model        : "claude-4-sonnet-20250514"
+    temperature  : 1
+    reasoning    : true
+    baseURL      : ""
+    headers      : ""
+  }
+}
+```
+
+### LLM Configuration
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | text | LLM provider: "anthropic", "openai", etc. |
+| `system_prompt` | text | Instructions for agent behavior |
+| `max_steps` | int | Maximum tool calls per request |
+| `model` | text | Model identifier |
+| `temperature` | float | Response randomness (0-2) |
+| `reasoning` | bool | Enable extended thinking |
+| `baseURL` | text | Custom API endpoint (optional) |
+| `headers` | text | Custom headers (optional) |
+
+### Available LLM Providers
+
+| Provider | Type Value |
+|----------|------------|
+| Anthropic | `"anthropic"` |
+| OpenAI | `"openai"` |
+
+### Example: Customer Support Agent
+
+```xanoscript
+agent support_bot {
+  canonical = "support"
+  llm = {
+    type         : "anthropic"
+    system_prompt: "You are a customer support agent. Help users with their questions about our products. Be friendly and professional."
+    max_steps    : 10
+    model        : "claude-4-sonnet-20250514"
+    temperature  : 0.7
+    reasoning    : true
+  }
+}
+```
+
+### Example: Data Analysis Agent
+
+```xanoscript
+agent data_analyst {
+  canonical = "analyst"
+  llm = {
+    type         : "anthropic"
+    system_prompt: "You are a data analyst. Help users understand their data by running queries and providing insights. Always explain your findings clearly."
+    max_steps    : 15
+    model        : "claude-4-sonnet-20250514"
+    temperature  : 0.3
+    reasoning    : true
+  }
+}
+```
+
+---
+
+## Update Agent
+
+```
+PUT /workspace/{workspace_id}/agent/{agent_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+- `tools` (bool, default: true): Include tool information in response
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete Agent
+
+```
+DELETE /workspace/{workspace_id}/agent/{agent_id}
+```
+
+**Warning:** This action cannot be undone.