@xano/developer-mcp 1.0.31 → 1.0.33

package/dist/tools/run_api_docs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Run API Documentation Tool
+ *
+ * Retrieves documentation for Xano's Run API.
+ * Re-exports from the run_api_docs module with ToolResult support.
+ */
+import { runApiDocsToolDefinition, topics, getTopicNames, getTopicDescriptions } from "../run_api_docs/index.js";
+import type { TopicDoc, DetailLevel } from "../meta_api_docs/types.js";
+import type { ToolResult } from "./types.js";
+export { runApiDocsToolDefinition, topics as runApiTopics, getTopicNames as getRunApiTopicNames, getTopicDescriptions as getRunApiTopicDescriptions, };
+export type { TopicDoc, DetailLevel };
+export interface RunApiDocsArgs {
+    topic: string;
+    detail_level?: DetailLevel;
+    include_schemas?: boolean;
+}
+export interface RunApiDocsResult {
+    documentation: string;
+}
+/**
+ * Get Xano Run API documentation.
+ *
+ * @param args - Documentation arguments
+ * @returns Documentation content
+ *
+ * @example
+ * ```ts
+ * import { runApiDocs } from '@xano/developer-mcp';
+ *
+ * // Get overview
+ * const overview = runApiDocs({ topic: 'start' });
+ *
+ * // Get session documentation with examples
+ * const sessionDocs = runApiDocs({
+ *   topic: 'session',
+ *   detail_level: 'examples',
+ *   include_schemas: true
+ * });
+ * ```
+ */
+export declare function runApiDocs(args: RunApiDocsArgs): RunApiDocsResult;
+/**
+ * Get Run API documentation and return a ToolResult.
+ */
+export declare function runApiDocsTool(args: RunApiDocsArgs): ToolResult;
+export { runApiDocsToolDefinition as toolDefinition };

package/dist/tools/run_api_docs.js

@@ -0,0 +1,69 @@
+/**
+ * Run API Documentation Tool
+ *
+ * Retrieves documentation for Xano's Run API.
+ * Re-exports from the run_api_docs module with ToolResult support.
+ */
+import { handleRunApiDocs as _handleRunApiDocs, runApiDocsToolDefinition, topics, getTopicNames, getTopicDescriptions, } from "../run_api_docs/index.js";
+// =============================================================================
+// Re-exports
+// =============================================================================
+export { runApiDocsToolDefinition, topics as runApiTopics, getTopicNames as getRunApiTopicNames, getTopicDescriptions as getRunApiTopicDescriptions, };
+// =============================================================================
+// Standalone Tool Function
+// =============================================================================
+/**
+ * Get Xano Run API documentation.
+ *
+ * @param args - Documentation arguments
+ * @returns Documentation content
+ *
+ * @example
+ * ```ts
+ * import { runApiDocs } from '@xano/developer-mcp';
+ *
+ * // Get overview
+ * const overview = runApiDocs({ topic: 'start' });
+ *
+ * // Get session documentation with examples
+ * const sessionDocs = runApiDocs({
+ *   topic: 'session',
+ *   detail_level: 'examples',
+ *   include_schemas: true
+ * });
+ * ```
+ */
+export function runApiDocs(args) {
+    if (!args?.topic) {
+        throw new Error("'topic' parameter is required. Use topic='start' for overview.");
+    }
+    const documentation = _handleRunApiDocs(args.topic, args.detail_level, args.include_schemas);
+    return { documentation };
+}
+/**
+ * Get Run API documentation and return a ToolResult.
+ */
+export function runApiDocsTool(args) {
+    if (!args?.topic) {
+        return {
+            success: false,
+            error: "Error: 'topic' parameter is required. Use run_api_docs with topic='start' for overview.",
+        };
+    }
+    try {
+        const result = runApiDocs(args);
+        return {
+            success: true,
+            data: result.documentation,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `Error retrieving Run API documentation: ${errorMessage}`,
+        };
+    }
+}
+// Re-export tool definition for MCP
+export { runApiDocsToolDefinition as toolDefinition };

package/dist/tools/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Common types for tool results
+ */
+export interface ToolResult {
+    success: boolean;
+    data?: string;
+    error?: string;
+}
+/**
+ * Convert a ToolResult to MCP tool response format
+ */
+export declare function toMcpResponse(result: ToolResult): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};

package/dist/tools/types.js

@@ -0,0 +1,17 @@
+/**
+ * Common types for tool results
+ */
+/**
+ * Convert a ToolResult to MCP tool response format
+ */
+export function toMcpResponse(result) {
+    if (result.success) {
+        return {
+            content: [{ type: "text", text: result.data }],
+        };
+    }
+    return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+    };
+}

package/dist/tools/validate_xanoscript.d.ts

@@ -0,0 +1,68 @@
+/**
+ * XanoScript Validation Tool
+ *
+ * Validates XanoScript code for syntax errors using the XanoScript language server.
+ * Can be used standalone or within the MCP server.
+ */
+import type { ToolResult } from "./types.js";
+export interface ValidateXanoscriptArgs {
+    /** The XanoScript code to validate */
+    code: string;
+}
+export interface ParserDiagnostic {
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    message: string;
+    source: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ParserDiagnostic[];
+    message: string;
+}
+/**
+ * Validate XanoScript code for syntax errors.
+ *
+ * @param args - The validation arguments
+ * @returns Validation result with errors if any
+ *
+ * @example
+ * ```ts
+ * import { validateXanoscript } from '@xano/developer-mcp';
+ *
+ * const result = validateXanoscript({ code: 'return 1 + 1' });
+ * if (result.valid) {
+ *   console.log('Code is valid!');
+ * } else {
+ *   console.log('Errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateXanoscript(args: ValidateXanoscriptArgs): ValidationResult;
+/**
+ * Validate XanoScript and return a simplified result.
+ * Returns ToolResult format for consistent error handling.
+ */
+export declare function validateXanoscriptTool(args: ValidateXanoscriptArgs): ToolResult;
+export declare const validateXanoscriptToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            code: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/validate_xanoscript.js

@@ -0,0 +1,114 @@
+/**
+ * XanoScript Validation Tool
+ *
+ * Validates XanoScript code for syntax errors using the XanoScript language server.
+ * Can be used standalone or within the MCP server.
+ */
+import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser.js";
+import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
+// =============================================================================
+// Standalone Tool Function
+// =============================================================================
+/**
+ * Validate XanoScript code for syntax errors.
+ *
+ * @param args - The validation arguments
+ * @returns Validation result with errors if any
+ *
+ * @example
+ * ```ts
+ * import { validateXanoscript } from '@xano/developer-mcp';
+ *
+ * const result = validateXanoscript({ code: 'return 1 + 1' });
+ * if (result.valid) {
+ *   console.log('Code is valid!');
+ * } else {
+ *   console.log('Errors:', result.errors);
+ * }
+ * ```
+ */
+export function validateXanoscript(args) {
+    if (!args?.code) {
+        return {
+            valid: false,
+            errors: [],
+            message: "Error: 'code' parameter is required",
+        };
+    }
+    try {
+        const text = args.code;
+        const scheme = getSchemeFromContent(text);
+        const parser = xanoscriptParser(text, scheme);
+        if (parser.errors.length === 0) {
+            return {
+                valid: true,
+                errors: [],
+                message: "XanoScript is valid. No syntax errors found.",
+            };
+        }
+        const diagnostics = parser.errors.map((error) => {
+            const startOffset = error.token?.startOffset ?? 0;
+            const endOffset = error.token?.endOffset ?? 5;
+            const lines = text.substring(0, startOffset).split("\n");
+            const line = lines.length - 1;
+            const character = lines[lines.length - 1].length;
+            const endLines = text.substring(0, endOffset + 1).split("\n");
+            const endLine = endLines.length - 1;
+            const endCharacter = endLines[endLines.length - 1].length;
+            return {
+                range: {
+                    start: { line, character },
+                    end: { line: endLine, character: endCharacter },
+                },
+                message: error.message,
+                source: error.name || "XanoScript Parser",
+            };
+        });
+        const errorMessages = diagnostics.map((d, i) => {
+            const location = `Line ${d.range.start.line + 1}, Column ${d.range.start.character + 1}`;
+            return `${i + 1}. [${location}] ${d.message}`;
+        });
+        return {
+            valid: false,
+            errors: diagnostics,
+            message: `Found ${diagnostics.length} error(s):\n\n${errorMessages.join("\n")}`,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            valid: false,
+            errors: [],
+            message: `Validation error: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Validate XanoScript and return a simplified result.
+ * Returns ToolResult format for consistent error handling.
+ */
+export function validateXanoscriptTool(args) {
+    const result = validateXanoscript(args);
+    return {
+        success: result.valid,
+        data: result.valid ? result.message : undefined,
+        error: result.valid ? undefined : result.message,
+    };
+}
+// =============================================================================
+// MCP Tool Definition
+// =============================================================================
+export const validateXanoscriptToolDefinition = {
+    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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            code: {
+                type: "string",
+                description: "The XanoScript code to validate",
+            },
+        },
+        required: ["code"],
+    },
+};

package/dist/tools/xanoscript_docs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * XanoScript Documentation Tool
+ *
+ * Retrieves XanoScript programming language documentation.
+ * Can be used standalone or within the MCP server.
+ */
+import { type XanoscriptDocsArgs } from "../xanoscript.js";
+import type { ToolResult } from "./types.js";
+export type { XanoscriptDocsArgs };
+export interface XanoscriptDocsResult {
+    documentation: string;
+}
+/**
+ * Get the path to XanoScript documentation files.
+ * Searches common locations for production and development.
+ */
+export declare function getXanoscriptDocsPath(): string;
+/**
+ * Set a custom docs path (useful for testing or custom installations)
+ */
+export declare function setXanoscriptDocsPath(path: string): void;
+/**
+ * Get XanoScript documentation.
+ *
+ * @param args - Optional documentation arguments
+ * @returns Documentation content
+ *
+ * @example
+ * ```ts
+ * import { xanoscriptDocs } from '@xano/developer-mcp';
+ *
+ * // Get overview
+ * const overview = xanoscriptDocs();
+ *
+ * // Get specific topic
+ * const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });
+ *
+ * // Get context-aware docs for a file
+ * const fileDocs = xanoscriptDocs({ file_path: 'apis/users/create.xs' });
+ *
+ * // Get quick reference only
+ * const quickRef = xanoscriptDocs({ topic: 'syntax', mode: 'quick_reference' });
+ * ```
+ */
+export declare function xanoscriptDocs(args?: XanoscriptDocsArgs): XanoscriptDocsResult;
+/**
+ * Get XanoScript documentation and return a ToolResult.
+ */
+export declare function xanoscriptDocsTool(args?: XanoscriptDocsArgs): ToolResult;
+export declare const xanoscriptDocsToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            topic: {
+                type: string;
+                description: string;
+            };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};

package/dist/tools/xanoscript_docs.js

@@ -0,0 +1,129 @@
+/**
+ * XanoScript Documentation Tool
+ *
+ * Retrieves XanoScript programming language documentation.
+ * Can be used standalone or within the MCP server.
+ */
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { readXanoscriptDocsV2, getTopicDescriptions, } from "../xanoscript.js";
+// =============================================================================
+// Path Resolution
+// =============================================================================
+let _docsPath = null;
+/**
+ * Get the path to XanoScript documentation files.
+ * Searches common locations for production and development.
+ */
+export function getXanoscriptDocsPath() {
+    if (_docsPath)
+        return _docsPath;
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const possiblePaths = [
+        join(__dirname, "..", "xanoscript_docs"), // dist/xanoscript_docs (production)
+        join(__dirname, "..", "..", "src", "xanoscript_docs"), // src/xanoscript_docs (dev)
+        join(__dirname, "..", "..", "xanoscript_docs"), // fallback
+    ];
+    for (const p of possiblePaths) {
+        try {
+            readFileSync(join(p, "version.json"));
+            _docsPath = p;
+            return p;
+        }
+        catch {
+            continue;
+        }
+    }
+    // Default fallback
+    _docsPath = join(__dirname, "..", "xanoscript_docs");
+    return _docsPath;
+}
+/**
+ * Set a custom docs path (useful for testing or custom installations)
+ */
+export function setXanoscriptDocsPath(path) {
+    _docsPath = path;
+}
+// =============================================================================
+// Standalone Tool Function
+// =============================================================================
+/**
+ * Get XanoScript documentation.
+ *
+ * @param args - Optional documentation arguments
+ * @returns Documentation content
+ *
+ * @example
+ * ```ts
+ * import { xanoscriptDocs } from '@xano/developer-mcp';
+ *
+ * // Get overview
+ * const overview = xanoscriptDocs();
+ *
+ * // Get specific topic
+ * const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });
+ *
+ * // Get context-aware docs for a file
+ * const fileDocs = xanoscriptDocs({ file_path: 'apis/users/create.xs' });
+ *
+ * // Get quick reference only
+ * const quickRef = xanoscriptDocs({ topic: 'syntax', mode: 'quick_reference' });
+ * ```
+ */
+export function xanoscriptDocs(args) {
+    const docsPath = getXanoscriptDocsPath();
+    const documentation = readXanoscriptDocsV2(docsPath, args);
+    return { documentation };
+}
+/**
+ * Get XanoScript documentation and return a ToolResult.
+ */
+export function xanoscriptDocsTool(args) {
+    try {
+        const result = xanoscriptDocs(args);
+        return {
+            success: true,
+            data: result.documentation,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `Error retrieving XanoScript documentation: ${errorMessage}`,
+        };
+    }
+}
+// =============================================================================
+// MCP Tool Definition
+// =============================================================================
+export const xanoscriptDocsToolDefinition = {
+    name: "xanoscript_docs",
+    description: "Get XanoScript programming language documentation for AI code generation. " +
+        "Call without parameters for overview (README). " +
+        "Use 'topic' for specific documentation, or 'file_path' for context-aware docs based on the file you're editing. " +
+        "Use mode='quick_reference' for compact syntax cheatsheet (recommended for context efficiency).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                description: "Documentation topic. Available: " + getTopicDescriptions(),
+            },
+            file_path: {
+                type: "string",
+                description: "File path being edited (e.g., 'apis/users/create.xs', 'functions/utils/format.xs'). " +
+                    "Returns all relevant docs based on file type using applyTo pattern matching.",
+            },
+            mode: {
+                type: "string",
+                enum: ["full", "quick_reference"],
+                description: "full = complete documentation, quick_reference = compact Quick Reference sections only. " +
+                    "Use quick_reference for smaller context window usage.",
+            },
+        },
+        required: [],
+    },
+};

package/dist/xanoscript_docs/README.md

@@ -4,45 +4,81 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 
 ## Quick Reference
 
-| Construct          | File Location         | Purpose                       |
-| ------------------ | --------------------- | ----------------------------- |
-| `table`            | `tables/*.xs`         | Database schema definition    |
-| `function`         | `functions/**/*.xs`   | Reusable logic blocks         |
-| `query`            | `apis/<group>/*.xs`   | HTTP API endpoints            |
-| `task`             | `tasks/*.xs`          | Scheduled/cron jobs           |
-| `*_trigger`        | `triggers/**/*.xs`    | Event-driven handlers         |
-| `agent`            | `agents/**/*.xs`      | AI-powered agents             |
-| `tool`             | `tools/**/*.xs`       | Tools for AI agents           |
-| `mcp_server`       | `mcp_servers/**/*.xs` | MCP server definitions        |
-| `addon`            | `addons/*.xs`         | Subqueries for related data   |
-| `middleware`       | `middleware/**/*.xs`  | Request/response interceptors |
-| `branch`           | `branch.xs`           | Branch-level configuration    |
-| `workspace`        | `workspace.xs`        | Workspace-level configuration |
-| `realtime_channel` | Configuration         | Realtime channel settings     |
+| Construct           | File Location                        | Purpose                       |
+| ------------------- | ------------------------------------ | ----------------------------- |
+| `workspace`         | `workspace/{name}.xs`                | Workspace-level configuration |
+| `workspace_trigger` | `workspace/trigger/{name}.xs`        | Workspace event handlers      |
+| `table`             | `table/{name}.xs`                    | Database schema definition    |
+| `table_trigger`     | `table/trigger/{name}.xs`            | Table event handlers          |
+| `api_group`         | `api/{group}/api_group.xs`           | API group definition          |
+| `query`             | `api/{group}/{endpoint}_{verb}.xs`   | HTTP API endpoints            |
+| `function`          | `function/{name}.xs`                 | Reusable logic blocks         |
+| `task`              | `task/{name}.xs`                     | Scheduled/cron jobs           |
+| `agent`             | `agent/{name}.xs`                    | AI-powered agents             |
+| `agent_trigger`     | `agent/trigger/{name}.xs`            | Agent event handlers          |
+| `tool`              | `tool/{name}.xs`                     | Tools for AI agents           |
+| `mcp_server`        | `mcp_server/{name}.xs`               | MCP server definitions        |
+| `mcp_server_trigger`| `mcp_server/trigger/{name}.xs`       | MCP server event handlers     |
+| `addon`             | `addon/{name}.xs`                    | Subqueries for related data   |
+| `middleware`        | `middleware/{name}.xs`               | Request/response interceptors |
+| `branch`            | `branch.xs`                          | Branch-level configuration    |
+| `realtime_channel`  | Configuration                        | Realtime channel settings     |
+
+**Naming convention:** All folder and file names use `snake_case` (e.g., `user_profile.xs`, `get_all_users_get.xs`).
 
 **Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
 
 ## Workspace Structure
 
+After pulling from Xano, files are organized using `snake_case` naming:
+
 ```
 project/
-├── workspace.xs         // Workspace configuration (env vars, preferences)
-├── branch.xs            // Branch configuration (middleware, history)
-├── tables/              // Database table schemas
-├── functions/           // Reusable functions (supports subfolders)
-├── apis/
-│   └── <api-group>/     // API endpoints grouped by domain
-├── tasks/               // Scheduled jobs
-├── triggers/            // Event-driven handlers
-├── agents/              // AI agents
-├── tools/               // AI tools
-├── mcp_servers/         // MCP server definitions
-├── middleware/          // Request/response interceptors
-├── addons/              // Query addons
-├── static/              // Frontend files (HTML, CSS, JS)
-└── run/                 // Job and service configurations
+├── branch.xs                        # Branch configuration
+├── workspace/
+│   ├── my_workspace.xs              # Workspace configuration
+│   └── trigger/
+│       └── on_deploy.xs             # Workspace triggers
+├── api/
+│   └── users/                       # API group folder
+│       ├── api_group.xs             # API group definition
+│       ├── get_all_get.xs           # GET /users
+│       ├── get_one_get.xs           # GET /users/:id
+│       ├── create_post.xs           # POST /users
+│       └── nested/
+│           └── profile_get.xs       # Nested endpoint: GET /users/nested/profile
+├── function/
+│   └── validate_token.xs            # Reusable functions
+├── task/
+│   └── daily_cleanup.xs             # Scheduled jobs
+├── table/
+│   ├── users.xs                     # Table schema
+│   └── trigger/
+│       └── on_user_create.xs        # Table triggers
+├── agent/
+│   ├── support_bot.xs               # AI agents
+│   └── trigger/
+│       └── on_message.xs            # Agent triggers
+├── tool/
+│   └── search_docs.xs               # AI tools
+├── mcp_server/
+│   ├── my_server.xs                 # MCP server definitions
+│   └── trigger/
+│       └── on_connect.xs            # MCP server triggers
+├── middleware/
+│   └── auth_check.xs                # Request/response interceptors
+├── addon/
+│   └── user_posts.xs                # Query addons
+├── static/                          # Frontend files (HTML, CSS, JS)
+└── run/                             # Job and service configurations
 ```
 
+**Key conventions:**
+- All folders and files use `snake_case` naming
+- API endpoints include the HTTP verb suffix (e.g., `create_post.xs`, `get_one_get.xs`)
+- Triggers are nested under `{type}/trigger/` folders
+- Nested API paths become nested folders (e.g., `/users/nested/profile` → `api/users/nested/profile_get.xs`)
+
 ## Environment Variables
 
 Access with `$env.<name>`. Common built-in variables include `$env.$remote_ip`, `$env.$http_headers`, `$env.$request_method`, `$env.$datasource`, and `$env.$branch`. Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
@@ -100,7 +136,7 @@ Documentation files use frontmatter to specify which file patterns they apply to
 
 ```markdown
 ---
-applyTo: "functions/**/*.xs"
+applyTo: "function/**/*.xs"
 ---
 ```
 

package/dist/xanoscript_docs/addons.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "addons/*.xs, functions/**/*.xs, apis/**/*.xs"
+applyTo: "addon/**/*.xs, function/**/*.xs, api/**/*.xs"
 ---
 
 # Addons
@@ -231,7 +231,7 @@ db.query product {
 ### File Structure
 
 ```
-addons/
+addon/
 ├── comment_count.xs
 ├── like_count.xs
 ├── author_details.xs