@xano/developer-mcp 1.0.11 → 1.0.12

package/README.md

@@ -6,10 +6,10 @@ A Model Context Protocol (MCP) server that provides AI assistants with comprehen
 
 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
+- **Meta API Documentation** - Programmatically manage Xano workspaces, databases, APIs, functions, and more
+- **XanoScript Documentation** - Language reference with context-aware docs based on file type
+- **Code Validation** - Syntax checking with the official XanoScript language server
+- **Workflow Guides** - Step-by-step guides for common development tasks
 
 ## Quick Start
 
@@ -109,38 +109,7 @@ claude mcp add xano-developer node /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`
+### 1. `validate_xanoscript`
 
 Validates XanoScript code for syntax errors. The language server auto-detects the object type from the code syntax.
 
@@ -158,7 +127,7 @@ validate_xanoscript({
 
 **Returns:** List of errors with line/column positions, or confirmation of validity.
 
-### 3. `xanoscript_docs`
+### 2. `xanoscript_docs`
 
 Retrieves XanoScript programming language documentation with context-aware support.
 
@@ -225,6 +194,54 @@ Get the current version of the Xano Developer MCP server.
 mcp_version()
 ```
 
+### 5. `api_docs`
+
+Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | string | Yes | Documentation topic to retrieve |
+| `detail_level` | string | No | `overview`, `detailed` (default), or `examples` |
+| `include_schemas` | boolean | No | Include JSON schemas for requests/responses (default: true) |
+
+**Available Topics:**
+
+| Topic | Description |
+|-------|-------------|
+| `start` | Getting started with the Meta API |
+| `authentication` | API authentication and authorization |
+| `workspace` | Workspace management endpoints |
+| `apigroup` | API group operations |
+| `api` | API endpoint management |
+| `table` | Database table operations |
+| `function` | Function management |
+| `task` | Scheduled task operations |
+| `agent` | AI agent configuration |
+| `tool` | AI tool management |
+| `mcp_server` | MCP server endpoints |
+| `middleware` | Middleware configuration |
+| `branch` | Branch management |
+| `realtime` | Real-time channel operations |
+| `file` | File management |
+| `history` | Version history |
+| `workflows` | Step-by-step workflow guides |
+
+**Examples:**
+```
+// Get overview of Meta API
+api_docs({ topic: "start" })
+
+// Get detailed table documentation
+api_docs({ topic: "table", detail_level: "detailed" })
+
+// Get examples without schemas (smaller context)
+api_docs({ topic: "api", detail_level: "examples", include_schemas: false })
+
+// Step-by-step workflow guides
+api_docs({ topic: "workflows" })
+```
+
 ## MCP Resources
 
 The server also exposes XanoScript documentation as MCP resources for direct access:
@@ -262,7 +279,6 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `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
 
@@ -271,23 +287,19 @@ xano-developer-mcp/
 ├── src/
 │   ├── index.ts              # Main MCP server implementation
 │   ├── xanoscript.d.ts       # TypeScript declarations
+│   ├── api_docs/             # Meta API documentation
+│   │   ├── index.ts          # API docs tool handler
+│   │   ├── types.ts          # Type definitions
+│   │   ├── format.ts         # Documentation formatter
+│   │   └── topics/           # Individual topic modules
+│   ├── xanoscript_docs/      # XanoScript language documentation
+│   │   ├── version.json
+│   │   ├── README.md
+│   │   ├── syntax.md
+│   │   └── ...
 │   └── templates/
 │       └── xanoscript-index.ts
 ├── dist/                      # Compiled JavaScript output
-├── scripts/
-│   └── sync-xanoscript-docs.ts  # Documentation sync script
-├── api_docs/                  # Xano Headless API documentation (16 markdown files)
-│   ├── index.md
-│   ├── workspace.md
-│   ├── table.md
-│   └── ...
-├── xanoscript_docs/           # XanoScript language documentation
-│   ├── version.json
-│   ├── README.md
-│   ├── syntax.md
-│   ├── functions.md
-│   ├── apis.md
-│   └── ...
 ├── package.json
 └── tsconfig.json
 ```
@@ -310,16 +322,16 @@ 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 → Context-aware docs from /xanoscript_docs/*.md
     │
+    ├─► api_docs → Meta API documentation with detail levels
+    │
     ├─► mcp_version → Returns server version from package.json
     │
-    └─► MCP Resources → Direct access to documentation files
+    └─► MCP Resources → Direct access to XanoScript documentation
 ```
 
 ## Authentication
@@ -338,11 +350,17 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
 
 ### Documentation Structure
 
-The XanoScript documentation uses a file-based structure in `xanoscript_docs/`. The documentation mapping is configured in `src/index.ts` via the `XANOSCRIPT_DOCS_V2` constant, which defines:
-
-- **file**: The markdown file containing the documentation
-- **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
-- **description**: Human-readable description of the topic
+**XanoScript Documentation** (`src/xanoscript_docs/`):
+- Markdown files for XanoScript language reference
+- Configured in `src/index.ts` via `XANOSCRIPT_DOCS_V2` with:
+  - **file**: The markdown file containing the documentation
+  - **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
+  - **description**: Human-readable description of the topic
+
+**Meta API Documentation** (`src/api_docs/`):
+- TypeScript modules with structured documentation
+- Supports parameterized output (detail levels, schema inclusion)
+- Better for AI consumption due to context efficiency
 
 ## License
 

package/dist/api_docs/format.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Formatting utilities for API documentation output
+ */
+import type { TopicDoc, DetailLevel } from "./types.js";
+export declare function formatDocumentation(doc: TopicDoc, detailLevel?: DetailLevel, includeSchemas?: boolean): string;

package/dist/api_docs/format.js

@@ -0,0 +1,158 @@
+/**
+ * Formatting utilities for API documentation output
+ */
+function formatParameter(param) {
+    const required = param.required ? " (required)" : "";
+    const defaultVal = param.default !== undefined ? ` [default: ${param.default}]` : "";
+    const enumVals = param.enum ? ` [options: ${param.enum.join(", ")}]` : "";
+    return `  - \`${param.name}\`: ${param.type}${required}${defaultVal}${enumVals} - ${param.description}`;
+}
+function formatEndpoint(ep, detailLevel) {
+    const lines = [];
+    // Method and path
+    lines.push(`### ${ep.method} ${ep.path}`);
+    if (ep.tool_name) {
+        lines.push(`**Tool:** \`${ep.tool_name}\``);
+    }
+    lines.push("");
+    lines.push(ep.description);
+    if (detailLevel === "overview") {
+        return lines.join("\n");
+    }
+    // Parameters
+    if (ep.parameters?.length) {
+        lines.push("");
+        lines.push("**Parameters:**");
+        for (const param of ep.parameters) {
+            lines.push(formatParameter(param));
+        }
+    }
+    // Request body
+    if (ep.request_body) {
+        lines.push("");
+        lines.push(`**Request Body:** \`${ep.request_body.type}\``);
+        if (ep.request_body.properties) {
+            for (const [key, val] of Object.entries(ep.request_body.properties)) {
+                const req = val.required ? " (required)" : "";
+                lines.push(`  - \`${key}\`: ${val.type}${req} - ${val.description || ""}`);
+            }
+        }
+    }
+    // Example (only in detailed/examples mode)
+    if (detailLevel === "examples" && ep.example) {
+        lines.push("");
+        lines.push("**Example:**");
+        lines.push("```");
+        lines.push(`${ep.example.method} ${ep.example.path}`);
+        if (ep.example.body) {
+            lines.push(JSON.stringify(ep.example.body, null, 2));
+        }
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function formatExample(ex) {
+    const lines = [];
+    lines.push(`### ${ex.title}`);
+    lines.push("");
+    lines.push(ex.description);
+    lines.push("");
+    lines.push("**Request:**");
+    lines.push("```");
+    lines.push(`${ex.request.method} ${ex.request.path}`);
+    if (ex.request.headers) {
+        for (const [key, val] of Object.entries(ex.request.headers)) {
+            lines.push(`${key}: ${val}`);
+        }
+    }
+    if (ex.request.body) {
+        lines.push("");
+        lines.push(JSON.stringify(ex.request.body, null, 2));
+    }
+    lines.push("```");
+    if (ex.response !== undefined) {
+        lines.push("");
+        lines.push("**Response:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(ex.response, null, 2));
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function formatPattern(pattern) {
+    const lines = [];
+    lines.push(`### ${pattern.name}`);
+    if (pattern.description) {
+        lines.push("");
+        lines.push(pattern.description);
+    }
+    lines.push("");
+    lines.push("**Steps:**");
+    for (const step of pattern.steps) {
+        lines.push(step);
+    }
+    if (pattern.example) {
+        lines.push("");
+        lines.push("**Example:**");
+        lines.push("```");
+        lines.push(pattern.example);
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+export function formatDocumentation(doc, detailLevel = "detailed", includeSchemas = true) {
+    const sections = [];
+    // Header
+    sections.push(`# ${doc.title}`);
+    sections.push("");
+    sections.push(doc.description);
+    // AI Hints (always include for AI optimization)
+    if (doc.ai_hints) {
+        sections.push("");
+        sections.push("## AI Usage Hints");
+        sections.push(doc.ai_hints);
+    }
+    // Endpoints
+    if (doc.endpoints?.length) {
+        sections.push("");
+        sections.push("## Endpoints");
+        for (const ep of doc.endpoints) {
+            sections.push("");
+            sections.push(formatEndpoint(ep, detailLevel));
+        }
+    }
+    // Patterns/Workflows
+    if (doc.patterns?.length) {
+        sections.push("");
+        sections.push("## Workflows");
+        for (const pattern of doc.patterns) {
+            sections.push("");
+            sections.push(formatPattern(pattern));
+        }
+    }
+    // Examples
+    if ((detailLevel === "detailed" || detailLevel === "examples") && doc.examples?.length) {
+        sections.push("");
+        sections.push("## Examples");
+        for (const ex of doc.examples) {
+            sections.push("");
+            sections.push(formatExample(ex));
+        }
+    }
+    // Schemas
+    if (includeSchemas && doc.schemas && Object.keys(doc.schemas).length > 0) {
+        sections.push("");
+        sections.push("## Schemas");
+        sections.push("");
+        sections.push("```json");
+        sections.push(JSON.stringify(doc.schemas, null, 2));
+        sections.push("```");
+    }
+    // Related topics
+    if (doc.related_topics?.length) {
+        sections.push("");
+        sections.push("## Related Topics");
+        sections.push(`Use \`api_docs\` with topic: ${doc.related_topics.join(", ")}`);
+    }
+    return sections.join("\n");
+}

package/dist/api_docs/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Xano Meta API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the api_docs tool handler for the MCP server.
+ */
+import type { TopicDoc, ApiDocsArgs } from "./types.js";
+/**
+ * All available documentation topics
+ */
+export declare const topics: Record<string, TopicDoc>;
+/**
+ * Get list of all available topic names
+ */
+export declare function getTopicNames(): string[];
+/**
+ * Get topic descriptions for tool documentation
+ */
+export declare function getTopicDescriptions(): string;
+/**
+ * Handler for the api_docs tool
+ */
+export declare function handleApiDocs(args: ApiDocsArgs): string;
+/**
+ * Tool definition for MCP server
+ */
+export declare const apiDocsToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            topic: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            detail_level: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            include_schemas: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/api_docs/index.js

@@ -0,0 +1,111 @@
+/**
+ * Xano Meta API Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the api_docs tool handler for the MCP server.
+ */
+import { formatDocumentation } from "./format.js";
+// Import all topic documentation
+import { startDoc } from "./topics/start.js";
+import { authenticationDoc } from "./topics/authentication.js";
+import { workspaceDoc } from "./topics/workspace.js";
+import { apigroupDoc } from "./topics/apigroup.js";
+import { apiDoc } from "./topics/api.js";
+import { tableDoc } from "./topics/table.js";
+import { functionDoc } from "./topics/function.js";
+import { taskDoc } from "./topics/task.js";
+import { agentDoc } from "./topics/agent.js";
+import { toolDoc } from "./topics/tool.js";
+import { mcpServerDoc } from "./topics/mcp_server.js";
+import { middlewareDoc } from "./topics/middleware.js";
+import { branchDoc } from "./topics/branch.js";
+import { realtimeDoc } from "./topics/realtime.js";
+import { fileDoc } from "./topics/file.js";
+import { historyDoc } from "./topics/history.js";
+import { workflowsDoc } from "./topics/workflows.js";
+/**
+ * All available documentation topics
+ */
+export const topics = {
+    start: startDoc,
+    authentication: authenticationDoc,
+    workspace: workspaceDoc,
+    apigroup: apigroupDoc,
+    api: apiDoc,
+    table: tableDoc,
+    function: functionDoc,
+    task: taskDoc,
+    agent: agentDoc,
+    tool: toolDoc,
+    mcp_server: mcpServerDoc,
+    middleware: middlewareDoc,
+    branch: branchDoc,
+    realtime: realtimeDoc,
+    file: fileDoc,
+    history: historyDoc,
+    workflows: workflowsDoc,
+};
+/**
+ * Get list of all available topic names
+ */
+export function getTopicNames() {
+    return Object.keys(topics);
+}
+/**
+ * Get topic descriptions for tool documentation
+ */
+export function getTopicDescriptions() {
+    return Object.entries(topics)
+        .map(([key, doc]) => `- ${key}: ${doc.title}`)
+        .join("\n");
+}
+/**
+ * Handler for the api_docs tool
+ */
+export function handleApiDocs(args) {
+    const { topic, detail_level = "detailed", include_schemas = true } = args;
+    // Validate topic
+    if (!topics[topic]) {
+        const available = getTopicNames().join(", ");
+        return `Error: Unknown topic "${topic}".\n\nAvailable topics: ${available}`;
+    }
+    const doc = topics[topic];
+    return formatDocumentation(doc, detail_level, include_schemas);
+}
+/**
+ * Tool definition for MCP server
+ */
+export const apiDocsToolDefinition = {
+    name: "api_docs",
+    description: `Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.
+
+## Topics
+${getTopicDescriptions()}
+
+## Usage
+- Start with "start" topic for overview and getting started
+- Use "workflows" for step-by-step guides
+- Use specific topics (workspace, table, api, etc.) for detailed endpoint docs`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                enum: getTopicNames(),
+                description: "Documentation topic to retrieve",
+            },
+            detail_level: {
+                type: "string",
+                enum: ["overview", "detailed", "examples"],
+                default: "detailed",
+                description: "Level of detail: overview (brief), detailed (full docs), examples (with code examples)",
+            },
+            include_schemas: {
+                type: "boolean",
+                default: true,
+                description: "Include JSON schemas for requests/responses",
+            },
+        },
+        required: ["topic"],
+    },
+};

package/dist/api_docs/topics/agent.d.ts

@@ -0,0 +1,2 @@
+import type { TopicDoc } from "../types.js";
+export declare const agentDoc: TopicDoc;

package/dist/api_docs/topics/agent.js

@@ -0,0 +1,142 @@
+export const agentDoc = {
+    topic: "agent",
+    title: "AI Agent Management",
+    description: `Agents are AI-powered automation units that use LLMs (like Claude) to make decisions and execute multi-step workflows.
+
+## Key Concepts
+- Agents use LLMs for reasoning and decision-making
+- Can call tools to perform actions
+- Support multiple LLM providers (Anthropic, OpenAI, etc.)
+- Configurable system prompts, temperature, max steps
+- Can have triggers that invoke them automatically
+
+## LLM Configuration
+- Type: Provider (e.g., "anthropic")
+- Model: Specific model (e.g., "claude-4-sonnet-20250514")
+- System prompt: Instructions for the agent
+- Temperature: Creativity level (0-1)
+- Max steps: Maximum reasoning iterations
+- Reasoning: Enable/disable chain-of-thought`,
+    ai_hints: `- Create tools first, then create agent and associate tools
+- System prompt is critical for agent behavior
+- Lower temperature = more deterministic responses
+- Max steps limits runaway agent loops
+- Use triggers to invoke agents on events (table changes, etc.)`,
+    endpoints: [
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/agent",
+            tool_name: "listAgents",
+            description: "List all AI agents in a workspace.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "page", type: "integer", default: 1, description: "Page number" },
+                { name: "per_page", type: "integer", default: 50, description: "Items per page" },
+                { name: "search", type: "string", description: "Search by agent name" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft versions" }
+            ]
+        },
+        {
+            method: "GET",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "getAgent",
+            description: "Get details of a specific AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" },
+                { name: "include_xanoscript", type: "boolean", default: false, description: "Include XanoScript definition" },
+                { name: "include_draft", type: "boolean", default: false, description: "Include draft version" }
+            ]
+        },
+        {
+            method: "POST",
+            path: "/workspace/{workspace_id}/agent",
+            tool_name: "createAgent",
+            description: "Create a new AI agent with LLM configuration.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Agent name", required: true },
+                    description: { type: "string", description: "Agent description" },
+                    xanoscript: { type: "string", description: "XanoScript agent definition", required: true }
+                }
+            },
+            example: {
+                method: "POST",
+                path: "/workspace/1/agent",
+                body: {
+                    name: "support_agent",
+                    description: "Customer support AI agent",
+                    xanoscript: `agent support_agent {
+  llm {
+    type = "anthropic"
+    model = "claude-4-sonnet-20250514"
+    system_prompt = "You are a helpful customer support agent."
+    max_steps = 10
+    temperature = 0.3
+  }
+  tools = [lookup_order, update_ticket]
+}`
+                }
+            }
+        },
+        {
+            method: "PUT",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "updateAgent",
+            description: "Update an existing AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" },
+                { name: "publish", type: "boolean", default: true, description: "Publish changes immediately" }
+            ],
+            request_body: {
+                type: "application/json",
+                properties: {
+                    name: { type: "string", description: "Agent name" },
+                    description: { type: "string", description: "Agent description" },
+                    xanoscript: { type: "string", description: "XanoScript agent definition" }
+                }
+            }
+        },
+        {
+            method: "DELETE",
+            path: "/workspace/{workspace_id}/agent/{agent_id}",
+            tool_name: "deleteAgent",
+            description: "Delete an AI agent.",
+            parameters: [
+                { name: "workspace_id", type: "integer", required: true, in: "path", description: "Workspace ID" },
+                { name: "agent_id", type: "integer", required: true, in: "path", description: "Agent ID" }
+            ]
+        }
+    ],
+    schemas: {
+        Agent: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                description: { type: "string" },
+                llm: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", description: "LLM provider (anthropic, openai, etc.)" },
+                        model: { type: "string", description: "Model identifier" },
+                        system_prompt: { type: "string" },
+                        max_steps: { type: "integer" },
+                        temperature: { type: "number" },
+                        reasoning: { type: "boolean" }
+                    }
+                },
+                tools: { type: "array", items: { type: "string" } },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" }
+            }
+        }
+    },
+    related_topics: ["tool", "mcp_server", "function"]
+};

package/dist/api_docs/topics/api.d.ts

@@ -0,0 +1,2 @@
+import type { TopicDoc } from "../types.js";
+export declare const apiDoc: TopicDoc;