@xano/developer-mcp 1.0.31 → 1.0.32

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: [],
+    },
+};