@xano/developer-mcp 1.0.11 → 1.0.13

package/dist/index.js

@@ -8,6 +8,7 @@ import { dirname, join } from "path";
 import { minimatch } from "minimatch";
 import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser.js";
 import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
+import { apiDocsToolDefinition, handleApiDocs } from "./api_docs/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -134,48 +135,12 @@ const XANOSCRIPT_DOCS_V2 = {
     },
 };
 // =============================================================================
-// API Documentation Configuration
-// =============================================================================
-const DOCS_MAP = {
-    workspace: "workspace.md",
-    table: "table.md",
-    api_group: "api_group.md",
-    function: "function.md",
-    task: "task.md",
-    middleware: "middleware.md",
-    addon: "addon.md",
-    agent: "agent.md",
-    tool: "tool.md",
-    mcp_server: "mcp_server.md",
-    realtime: "realtime.md",
-    triggers: "triggers.md",
-    file: "file.md",
-    history: "history.md",
-    authentication: "authentication.md",
-};
-// =============================================================================
 // Path Resolution
 // =============================================================================
-function getDocsPath() {
-    const possiblePaths = [
-        join(__dirname, "..", "api_docs"),
-        join(__dirname, "..", "..", "api_docs"),
-    ];
-    for (const p of possiblePaths) {
-        try {
-            readFileSync(join(p, "index.md"));
-            return p;
-        }
-        catch {
-            continue;
-        }
-    }
-    return join(__dirname, "..", "api_docs");
-}
 function getXanoscriptDocsPath() {
     const possiblePaths = [
-        join(__dirname, "..", "xanoscript_docs"),
-        join(__dirname, "..", "..", "xanoscript_docs"),
+        join(__dirname, "xanoscript_docs"), // dist/xanoscript_docs (production)
+        join(__dirname, "..", "src", "xanoscript_docs"), // src/xanoscript_docs (dev before build)
     ];
     for (const p of possiblePaths) {
         try {
@@ -186,9 +151,8 @@ function getXanoscriptDocsPath() {
             continue;
         }
     }
-    return join(__dirname, "..", "xanoscript_docs");
+    return join(__dirname, "xanoscript_docs");
 }
-const DOCS_PATH = getDocsPath();
 const XANOSCRIPT_DOCS_PATH = getXanoscriptDocsPath();
 // =============================================================================
 // Documentation Helpers
@@ -202,31 +166,6 @@ function getXanoscriptDocsVersion() {
         return "unknown";
     }
 }
-function readDocumentation(object) {
-    try {
-        if (!object) {
-            return readFileSync(join(DOCS_PATH, "index.md"), "utf-8");
-        }
-        const normalizedObject = object.toLowerCase().trim();
-        if (normalizedObject in DOCS_MAP) {
-            const filePath = join(DOCS_PATH, DOCS_MAP[normalizedObject]);
-            return readFileSync(filePath, "utf-8");
-        }
-        const matchingKey = Object.keys(DOCS_MAP).find((key) => key.includes(normalizedObject) || normalizedObject.includes(key));
-        if (matchingKey) {
-            const filePath = join(DOCS_PATH, DOCS_MAP[matchingKey]);
-            return readFileSync(filePath, "utf-8");
-        }
-        const availableObjects = Object.keys(DOCS_MAP).join(", ");
-        return `Error: Unknown object "${object}". Available objects: ${availableObjects}
-
-Use api_docs() without parameters to see the full documentation index.`;
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return `Error reading documentation: ${errorMessage}`;
-    }
-}
 // =============================================================================
 // XanoScript Documentation v2 Functions
 // =============================================================================
@@ -372,20 +311,6 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
         tools: [
-            {
-                name: "api_docs",
-                description: "Get Xano Headless API documentation. Returns documentation for interacting with the Xano Headless API using XanoScript. Use without parameters for an overview, or specify an object for detailed documentation.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        object: {
-                            type: "string",
-                            description: `Optional: The specific API object to get documentation for. Available values: ${Object.keys(DOCS_MAP).join(", ")}`,
-                        },
-                    },
-                    required: [],
-                },
-            },
             {
                 name: "validate_xanoscript",
                 description: "Validate XanoScript code for syntax errors. Returns a list of errors with line/column positions, or confirms the code is valid. The language server auto-detects the object type from the code syntax.",
@@ -441,23 +366,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: [],
                 },
             },
+            apiDocsToolDefinition,
         ],
     };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name === "api_docs") {
-        const args = request.params.arguments;
-        const object = args?.object;
-        const documentation = readDocumentation(object);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: documentation,
-                },
-            ],
-        };
-    }
     if (request.params.name === "validate_xanoscript") {
         const args = request.params.arguments;
         if (!args?.code) {
@@ -552,6 +465,47 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             ],
         };
     }
+    if (request.params.name === "api_docs") {
+        const args = request.params.arguments;
+        if (!args?.topic) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: 'topic' parameter is required. Use api_docs with topic='start' for overview.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const documentation = handleApiDocs({
+                topic: args.topic,
+                detail_level: args.detail_level,
+                include_schemas: args.include_schemas,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: documentation,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error retrieving API documentation: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
     return {
         content: [
             {

package/dist/templates/init-workspace.js

@@ -110,7 +110,7 @@ The \`.xano/registry.json\` file tracks the sync state between local files and t
 
 ## Fetching Objects from the API
 
-Use the Headless API to fetch objects. For detailed endpoint documentation, use \`api_docs({ object: "function" })\` etc.
+Use the Headless API to fetch objects.
 
 ### List Objects
 
@@ -175,7 +175,7 @@ apis/
     └── GET_me.xs          # Another endpoint
 \`\`\`
 
-See \`api_docs({ object: "api_group" })\` for complete API group and endpoint documentation.
+API groups contain endpoints that share common configuration.
 
 ## Pull Workflow
 
@@ -255,20 +255,6 @@ const response = await fetch(
 );
 \`\`\`
 
-## API Documentation References
-
-For detailed API documentation on each object type, use:
-
-- \`api_docs()\` - Overview of all endpoints
-- \`api_docs({ object: "workspace" })\` - Workspace management
-- \`api_docs({ object: "function" })\` - Functions API
-- \`api_docs({ object: "table" })\` - Tables API
-- \`api_docs({ object: "task" })\` - Tasks API
-- \`api_docs({ object: "api_group" })\` - API groups and endpoints
-- \`api_docs({ object: "agent" })\` - AI agents
-- \`api_docs({ object: "tool" })\` - AI tools
-- \`api_docs({ object: "authentication" })\` - Auth and user info
-
 ## XanoScript Documentation References
 
 For writing XanoScript code, use:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "MCP server for Xano Headless API documentation and XanoScript code validation",
   "type": "module",
   "main": "dist/index.js",
@@ -8,16 +8,13 @@
     "xano-developer-mcp": "./dist/index.js"
   },
   "files": [
-    "dist",
-    "api_docs",
-    "xanoscript_docs"
+    "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && cp -r src/xanoscript_docs dist/",
     "start": "node dist/index.js",
     "dev": "tsc && node dist/index.js",
-    "prepublishOnly": "npm run build",
-    "sync-docs": "npx ts-node scripts/sync-xanoscript-docs.ts"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "xano",

package/api_docs/addon.md

@@ -1,193 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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.