@xano/developer-mcp 1.0.34 → 1.0.35

package/dist/tools/index.d.ts

@@ -29,33 +29,20 @@
  * const docs = xanoscriptDocs({ topic: 'syntax' });
  * ```
  */
-import { validateXanoscript, validateXanoscriptTool, validateXanoscriptToolDefinition, type ValidateXanoscriptArgs, type ValidationResult, type ParserDiagnostic } from "./validate_xanoscript.js";
+import { validateXanoscript, validateXanoscriptTool, validateXanoscriptToolDefinition, TYPE_ALIASES, RESERVED_VARIABLES, type ValidateXanoscriptArgs, type ValidationResult, type BatchValidationResult, type SingleFileValidationResult, type ParserDiagnostic } from "./validate_xanoscript.js";
 import { xanoscriptDocs, xanoscriptDocsTool, xanoscriptDocsToolDefinition, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult } from "./xanoscript_docs.js";
 import { mcpVersion, mcpVersionTool, mcpVersionToolDefinition, getServerVersion, setServerVersion, type McpVersionResult } from "./mcp_version.js";
 import { metaApiDocs, metaApiDocsTool, metaApiDocsToolDefinition, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult } from "./meta_api_docs.js";
 import { runApiDocs, runApiDocsTool, runApiDocsToolDefinition, runApiTopics, getRunApiTopicNames, getRunApiTopicDescriptions, type RunApiDocsArgs, type RunApiDocsResult } from "./run_api_docs.js";
 import { cliDocs, cliDocsTool, cliDocsToolDefinition, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult } from "./cli_docs.js";
 import { type ToolResult, toMcpResponse } from "./types.js";
-export { validateXanoscript, type ValidateXanoscriptArgs, type ValidationResult, type ParserDiagnostic, xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, mcpVersion, getServerVersion, setServerVersion, type McpVersionResult, metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult, runApiDocs, runApiTopics, getRunApiTopicNames, getRunApiTopicDescriptions, type RunApiDocsArgs, type RunApiDocsResult, cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult, type ToolResult, toMcpResponse, };
+export { validateXanoscript, TYPE_ALIASES, RESERVED_VARIABLES, type ValidateXanoscriptArgs, type ValidationResult, type BatchValidationResult, type SingleFileValidationResult, type ParserDiagnostic, xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, mcpVersion, getServerVersion, setServerVersion, type McpVersionResult, metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult, runApiDocs, runApiTopics, getRunApiTopicNames, getRunApiTopicDescriptions, type RunApiDocsArgs, type RunApiDocsResult, cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult, type ToolResult, toMcpResponse, };
 export { validateXanoscriptTool, xanoscriptDocsTool, mcpVersionTool, metaApiDocsTool, runApiDocsTool, cliDocsTool, };
 export { validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVersionToolDefinition, metaApiDocsToolDefinition, runApiDocsToolDefinition, cliDocsToolDefinition, };
 /**
  * All tool definitions for MCP server registration
  */
 export declare const toolDefinitions: ({
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            code: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-} | {
     name: string;
     description: string;
     inputSchema: {

package/dist/tools/index.js

@@ -32,7 +32,7 @@
 // =============================================================================
 // Tool Imports
 // =============================================================================
-import { validateXanoscript, validateXanoscriptTool, validateXanoscriptToolDefinition, } from "./validate_xanoscript.js";
+import { validateXanoscript, validateXanoscriptTool, validateXanoscriptToolDefinition, TYPE_ALIASES, RESERVED_VARIABLES, } from "./validate_xanoscript.js";
 import { xanoscriptDocs, xanoscriptDocsTool, xanoscriptDocsToolDefinition, getXanoscriptDocsPath, setXanoscriptDocsPath, } from "./xanoscript_docs.js";
 import { mcpVersion, mcpVersionTool, mcpVersionToolDefinition, getServerVersion, setServerVersion, } from "./mcp_version.js";
 import { metaApiDocs, metaApiDocsTool, metaApiDocsToolDefinition, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, } from "./meta_api_docs.js";
@@ -44,7 +44,7 @@ import { toMcpResponse } from "./types.js";
 // =============================================================================
 export { 
 // Validation
-validateXanoscript, 
+validateXanoscript, TYPE_ALIASES, RESERVED_VARIABLES, 
 // XanoScript Documentation
 xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, 
 // MCP Version

package/dist/tools/validate_xanoscript.d.ts

@@ -3,11 +3,25 @@
  *
  * Validates XanoScript code for syntax errors using the XanoScript language server.
  * Can be used standalone or within the MCP server.
+ *
+ * Supports multiple input methods:
+ * - code: Raw XanoScript code as a string
+ * - file_path: Path to a single .xs file
+ * - file_paths: Array of file paths for batch validation
+ * - directory: Directory path with optional glob pattern
  */
 import type { ToolResult } from "./types.js";
 export interface ValidateXanoscriptArgs {
-    /** The XanoScript code to validate */
-    code: string;
+    /** The XanoScript code to validate (mutually exclusive with file_path/file_paths/directory) */
+    code?: string;
+    /** Path to a single XanoScript file to validate */
+    file_path?: string;
+    /** Array of file paths for batch validation */
+    file_paths?: string[];
+    /** Directory to validate (validates all .xs files recursively) */
+    directory?: string;
+    /** Glob pattern to filter files when using directory (default: "**\/*.xs") */
+    pattern?: string;
 }
 export interface ParserDiagnostic {
     range: {
@@ -23,14 +37,42 @@ export interface ParserDiagnostic {
     message: string;
     source: string;
 }
+export interface SingleFileValidationResult {
+    valid: boolean;
+    errors: ParserDiagnostic[];
+    message: string;
+    file_path?: string;
+}
 export interface ValidationResult {
     valid: boolean;
     errors: ParserDiagnostic[];
     message: string;
 }
+export interface BatchValidationResult {
+    valid: boolean;
+    total_files: number;
+    valid_files: number;
+    invalid_files: number;
+    results: SingleFileValidationResult[];
+    message: string;
+}
+/**
+ * Common type aliases that users might try
+ */
+declare const TYPE_ALIASES: Record<string, string>;
+/**
+ * Reserved variable names that cannot be used
+ */
+declare const RESERVED_VARIABLES: string[];
 /**
  * Validate XanoScript code for syntax errors.
  *
+ * Supports multiple input methods:
+ * - code: Raw XanoScript code as a string
+ * - file_path: Path to a single .xs file
+ * - file_paths: Array of file paths for batch validation
+ * - directory: Directory path with optional glob pattern
+ *
  * @param args - The validation arguments
  * @returns Validation result with errors if any
  *
@@ -38,15 +80,28 @@ export interface ValidationResult {
  * ```ts
  * import { validateXanoscript } from '@xano/developer-mcp';
  *
+ * // Validate code directly
  * const result = validateXanoscript({ code: 'return 1 + 1' });
- * if (result.valid) {
- *   console.log('Code is valid!');
- * } else {
- *   console.log('Errors:', result.errors);
- * }
+ *
+ * // Validate a single file
+ * const fileResult = validateXanoscript({ file_path: './functions/utils.xs' });
+ *
+ * // Validate multiple files
+ * const batchResult = validateXanoscript({
+ *   file_paths: ['./apis/users/get.xs', './apis/users/create.xs']
+ * });
+ *
+ * // Validate all .xs files in a directory
+ * const dirResult = validateXanoscript({ directory: './src' });
+ *
+ * // Validate with a specific pattern
+ * const patternResult = validateXanoscript({
+ *   directory: './src',
+ *   pattern: 'apis/**\/*.xs'
+ * });
  * ```
  */
-export declare function validateXanoscript(args: ValidateXanoscriptArgs): ValidationResult;
+export declare function validateXanoscript(args: ValidateXanoscriptArgs): ValidationResult | BatchValidationResult;
 /**
  * Validate XanoScript and return a simplified result.
  * Returns ToolResult format for consistent error handling.
@@ -62,7 +117,27 @@ export declare const validateXanoscriptToolDefinition: {
                 type: string;
                 description: string;
             };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            file_paths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            directory: {
+                type: string;
+                description: string;
+            };
+            pattern: {
+                type: string;
+                description: string;
+            };
         };
-        required: string[];
+        required: never[];
     };
 };
+export { TYPE_ALIASES, RESERVED_VARIABLES };

package/dist/tools/validate_xanoscript.js

@@ -3,47 +3,183 @@
  *
  * Validates XanoScript code for syntax errors using the XanoScript language server.
  * Can be used standalone or within the MCP server.
+ *
+ * Supports multiple input methods:
+ * - code: Raw XanoScript code as a string
+ * - file_path: Path to a single .xs file
+ * - file_paths: Array of file paths for batch validation
+ * - directory: Directory path with optional glob pattern
  */
 import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser.js";
 import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join, resolve, basename } from "path";
+import { minimatch } from "minimatch";
 // =============================================================================
-// Standalone Tool Function
+// Error Message Improvements
 // =============================================================================
 /**
- * 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);
- * }
- * ```
+ * Common type aliases that users might try
  */
-export function validateXanoscript(args) {
-    if (!args?.code) {
-        return {
-            valid: false,
-            errors: [],
-            message: "Error: 'code' parameter is required",
-        };
+const TYPE_ALIASES = {
+    boolean: "bool",
+    integer: "int",
+    string: "text",
+    number: "decimal",
+    float: "decimal",
+    double: "decimal",
+    array: "type[]",
+    list: "type[]",
+    object: "json",
+    map: "json",
+    dict: "json",
+    dictionary: "json",
+};
+/**
+ * Reserved variable names that cannot be used
+ */
+const RESERVED_VARIABLES = [
+    "$response",
+    "$output",
+    "$input",
+    "$auth",
+    "$env",
+    "$db",
+    "$this",
+    "$result",
+];
+/**
+ * Common syntax mistakes and their fixes
+ */
+const SYNTAX_SUGGESTIONS = [
+    {
+        pattern: /else\s+if/,
+        suggestion: 'Use "elseif" (one word) instead of "else if"',
+    },
+    {
+        pattern: /body\s*=/,
+        suggestion: 'Use "params" instead of "body" for api.request request body',
+    },
+    {
+        pattern: /\|default:/,
+        suggestion: 'There is no "default" filter. Use "first_notnull" or "??" operator instead',
+    },
+    {
+        pattern: /boolean/,
+        suggestion: 'Use "bool" instead of "boolean" for type declaration',
+    },
+    {
+        pattern: /integer(?!\s*\()/,
+        suggestion: 'Use "int" instead of "integer" for type declaration',
+    },
+    {
+        pattern: /string(?!\s*\()/,
+        suggestion: 'Use "text" instead of "string" for type declaration',
+    },
+];
+/**
+ * Enhance error message with helpful suggestions
+ */
+function enhanceErrorMessage(message, code, lineNumber) {
+    let enhanced = message;
+    const lines = code.split("\n");
+    const errorLine = lines[lineNumber] || "";
+    // Check for type aliases
+    for (const [alias, correct] of Object.entries(TYPE_ALIASES)) {
+        const regex = new RegExp(`\\b${alias}\\b`, "i");
+        if (regex.test(errorLine)) {
+            enhanced += `\n\n💡 Suggestion: Use "${correct}" instead of "${alias}"`;
+            break;
+        }
+    }
+    // Check for reserved variables
+    for (const reserved of RESERVED_VARIABLES) {
+        if (errorLine.includes(`var ${reserved}`) ||
+            errorLine.includes(`var.update ${reserved}`)) {
+            enhanced += `\n\n💡 "${reserved}" is a reserved variable name. Try a different name like "${reserved.replace("$", "$my_")}"`;
+            break;
+        }
+    }
+    // Check for common syntax mistakes
+    for (const { pattern, suggestion } of SYNTAX_SUGGESTIONS) {
+        if (pattern.test(errorLine) || pattern.test(code)) {
+            enhanced += `\n\n💡 Suggestion: ${suggestion}`;
+            break;
+        }
+    }
+    // Add the actual line of code for context
+    if (errorLine.trim()) {
+        enhanced += `\n\nCode at line ${lineNumber + 1}:\n  ${errorLine.trim()}`;
+    }
+    return enhanced;
+}
+// =============================================================================
+// File Reading Utilities
+// =============================================================================
+/**
+ * Read a file and return its contents
+ */
+function readFile(filePath) {
+    try {
+        const absolutePath = resolve(filePath);
+        if (!existsSync(absolutePath)) {
+            return { content: "", error: `File not found: ${filePath}` };
+        }
+        const content = readFileSync(absolutePath, "utf-8");
+        return { content };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return { content: "", error: `Error reading file: ${errorMessage}` };
+    }
+}
+/**
+ * Find all .xs files in a directory matching the pattern
+ */
+function findXsFiles(directory, pattern = "**/*.xs") {
+    const absoluteDir = resolve(directory);
+    if (!existsSync(absoluteDir)) {
+        return [];
+    }
+    const files = [];
+    function walkDir(dir, basePath = "") {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            const relativePath = basePath ? join(basePath, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                walkDir(fullPath, relativePath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".xs")) {
+                if (minimatch(relativePath, pattern)) {
+                    files.push(fullPath);
+                }
+            }
+        }
     }
+    walkDir(absoluteDir);
+    return files;
+}
+// =============================================================================
+// Standalone Tool Function
+// =============================================================================
+/**
+ * Validate a single piece of XanoScript code.
+ * Internal function used by the public API.
+ */
+function validateCode(code, filePath) {
     try {
-        const text = args.code;
+        const text = 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.",
+                message: filePath
+                    ? `✓ ${basename(filePath)}: Valid`
+                    : "XanoScript is valid. No syntax errors found.",
+                file_path: filePath,
             };
         }
         const diagnostics = parser.errors.map((error) => {
@@ -55,12 +191,14 @@ export function validateXanoscript(args) {
             const endLines = text.substring(0, endOffset + 1).split("\n");
             const endLine = endLines.length - 1;
             const endCharacter = endLines[endLines.length - 1].length;
+            // Enhance error message with suggestions
+            const enhancedMessage = enhanceErrorMessage(error.message, text, line);
             return {
                 range: {
                     start: { line, character },
                     end: { line: endLine, character: endCharacter },
                 },
-                message: error.message,
+                message: enhancedMessage,
                 source: error.name || "XanoScript Parser",
             };
         });
@@ -68,10 +206,12 @@ export function validateXanoscript(args) {
             const location = `Line ${d.range.start.line + 1}, Column ${d.range.start.character + 1}`;
             return `${i + 1}. [${location}] ${d.message}`;
         });
+        const prefix = filePath ? `✗ ${basename(filePath)}: ` : "";
         return {
             valid: false,
             errors: diagnostics,
-            message: `Found ${diagnostics.length} error(s):\n\n${errorMessages.join("\n")}`,
+            message: `${prefix}Found ${diagnostics.length} error(s):\n\n${errorMessages.join("\n")}`,
+            file_path: filePath,
         };
     }
     catch (error) {
@@ -80,9 +220,156 @@ export function validateXanoscript(args) {
             valid: false,
             errors: [],
             message: `Validation error: ${errorMessage}`,
+            file_path: filePath,
         };
     }
 }
+/**
+ * Validate XanoScript code for syntax errors.
+ *
+ * Supports multiple input methods:
+ * - code: Raw XanoScript code as a string
+ * - file_path: Path to a single .xs file
+ * - file_paths: Array of file paths for batch validation
+ * - directory: Directory path with optional glob pattern
+ *
+ * @param args - The validation arguments
+ * @returns Validation result with errors if any
+ *
+ * @example
+ * ```ts
+ * import { validateXanoscript } from '@xano/developer-mcp';
+ *
+ * // Validate code directly
+ * const result = validateXanoscript({ code: 'return 1 + 1' });
+ *
+ * // Validate a single file
+ * const fileResult = validateXanoscript({ file_path: './functions/utils.xs' });
+ *
+ * // Validate multiple files
+ * const batchResult = validateXanoscript({
+ *   file_paths: ['./apis/users/get.xs', './apis/users/create.xs']
+ * });
+ *
+ * // Validate all .xs files in a directory
+ * const dirResult = validateXanoscript({ directory: './src' });
+ *
+ * // Validate with a specific pattern
+ * const patternResult = validateXanoscript({
+ *   directory: './src',
+ *   pattern: 'apis/**\/*.xs'
+ * });
+ * ```
+ */
+export function validateXanoscript(args) {
+    // Validate that at least one input method is provided
+    if (!args?.code && !args?.file_path && !args?.file_paths && !args?.directory) {
+        return {
+            valid: false,
+            errors: [],
+            message: "Error: One of 'code', 'file_path', 'file_paths', or 'directory' parameter is required",
+        };
+    }
+    // Handle direct code validation
+    if (args.code) {
+        const result = validateCode(args.code);
+        return {
+            valid: result.valid,
+            errors: result.errors,
+            message: result.message,
+        };
+    }
+    // Handle single file validation
+    if (args.file_path) {
+        const { content, error } = readFile(args.file_path);
+        if (error) {
+            return {
+                valid: false,
+                errors: [],
+                message: error,
+            };
+        }
+        const result = validateCode(content, args.file_path);
+        return {
+            valid: result.valid,
+            errors: result.errors,
+            message: result.message,
+        };
+    }
+    // Handle batch validation (file_paths or directory)
+    let filesToValidate = [];
+    if (args.file_paths) {
+        filesToValidate = args.file_paths;
+    }
+    else if (args.directory) {
+        filesToValidate = findXsFiles(args.directory, args.pattern || "**/*.xs");
+        if (filesToValidate.length === 0) {
+            return {
+                valid: true,
+                total_files: 0,
+                valid_files: 0,
+                invalid_files: 0,
+                results: [],
+                message: `No .xs files found in directory: ${args.directory}${args.pattern ? ` matching pattern: ${args.pattern}` : ""}`,
+            };
+        }
+    }
+    // Validate all files
+    const results = [];
+    let validCount = 0;
+    let invalidCount = 0;
+    for (const filePath of filesToValidate) {
+        const { content, error } = readFile(filePath);
+        if (error) {
+            results.push({
+                valid: false,
+                errors: [],
+                message: error,
+                file_path: filePath,
+            });
+            invalidCount++;
+            continue;
+        }
+        const result = validateCode(content, filePath);
+        results.push(result);
+        if (result.valid) {
+            validCount++;
+        }
+        else {
+            invalidCount++;
+        }
+    }
+    // Build summary message
+    const allValid = invalidCount === 0;
+    const summaryLines = [
+        `Validated ${filesToValidate.length} file(s): ${validCount} valid, ${invalidCount} invalid`,
+        "",
+    ];
+    // Show errors first, then valid files
+    const invalidResults = results.filter((r) => !r.valid);
+    const validResults = results.filter((r) => r.valid);
+    if (invalidResults.length > 0) {
+        summaryLines.push("❌ Files with errors:");
+        for (const result of invalidResults) {
+            summaryLines.push(`\n${result.message}`);
+        }
+        summaryLines.push("");
+    }
+    if (validResults.length > 0) {
+        summaryLines.push("✅ Valid files:");
+        for (const result of validResults) {
+            summaryLines.push(`  ${result.file_path}`);
+        }
+    }
+    return {
+        valid: allValid,
+        total_files: filesToValidate.length,
+        valid_files: validCount,
+        invalid_files: invalidCount,
+        results,
+        message: summaryLines.join("\n"),
+    };
+}
 /**
  * Validate XanoScript and return a simplified result.
  * Returns ToolResult format for consistent error handling.
@@ -100,15 +387,42 @@ export function validateXanoscriptTool(args) {
 // =============================================================================
 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.",
+    description: "Validate XanoScript code for syntax errors. Supports multiple input methods:\n" +
+        "- code: Raw XanoScript code as a string\n" +
+        "- file_path: Path to a single .xs file (easier than escaping code!)\n" +
+        "- file_paths: Array of file paths for batch validation\n" +
+        "- directory: Validate all .xs files in a directory\n\n" +
+        "Returns errors with line/column positions and helpful suggestions for common mistakes. " +
+        "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",
+                description: "The XanoScript code to validate as a string. Use file_path instead if the code contains special characters that are hard to escape.",
+            },
+            file_path: {
+                type: "string",
+                description: "Path to a single XanoScript file to validate. Easier than passing code directly - avoids escaping issues.",
+            },
+            file_paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of file paths for batch validation. Returns a summary with per-file results.",
+            },
+            directory: {
+                type: "string",
+                description: "Directory path to validate. Validates all .xs files recursively. Use with 'pattern' to filter.",
+            },
+            pattern: {
+                type: "string",
+                description: 'Glob pattern to filter files when using directory (default: "**/*.xs"). Example: "apis/**/*.xs"',
             },
         },
-        required: ["code"],
+        required: [],
     },
 };
+// =============================================================================
+// Utility Exports
+// =============================================================================
+export { TYPE_ALIASES, RESERVED_VARIABLES };

package/dist/xanoscript_docs/README.md

@@ -108,7 +108,20 @@ $db.table.field     // Database field reference (in queries)
 $this               // Current item in loops/maps
 ```
 
-**Note:** `$response` is a reserved word and cannot be used as a variable name.
+**Reserved Variables:** The following cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`.
+
+### Type Names
+
+XanoScript uses specific type names:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | String (not "string") | `text name` |
+| `int` | Integer (not "integer") | `int count` |
+| `bool` | Boolean (not "boolean") | `bool active` |
+| `decimal` | Float/number | `decimal price` |
+| `type[]` | Array (not "array" or "list") | `text[] tags` |
+| `json` | Arbitrary JSON data | `json metadata` |
 
 ### Comments
 

package/dist/xanoscript_docs/database.md

@@ -612,3 +612,17 @@ try_catch {
 5. **Use null-safe operators** - `==?` for optional filters
 6. **Use bulk operations for batch processing** - More efficient than loops
 7. **Handle deadlocks gracefully** - Implement retry logic for concurrent writes
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `tables` | Database schema definitions with indexes and relationships |
+| `syntax` | Query filters, operators, and expressions |
+| `quickstart` | Common CRUD patterns and examples |
+| `addons` | Reusable subqueries for fetching related data |
+| `performance` | Query optimization best practices |

package/dist/xanoscript_docs/functions.md

@@ -465,3 +465,17 @@ foreach ($items) {
 5. **Keep stacks shallow** - Avoid deeply nested conditionals
 6. **Use group for organization** - Visually group related statements for readability
 7. **Use remove sparingly** - Consider filtering arrays instead
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `types` | Input types, filters, and validation |
+| `syntax` | Expressions, operators, and control flow |
+| `quickstart` | Common patterns and examples |
+| `database` | Database operations in function stacks |
+| `testing` | Unit testing functions |

package/dist/xanoscript_docs/quickstart.md

@@ -8,6 +8,62 @@ Essential patterns for XanoScript development. Use this as a quick reference for
 
 ## Quick Reference
 
+### Reserved Variable Names
+
+These variable names are reserved and cannot be used:
+
+| Variable | Description |
+|----------|-------------|
+| `$response` | API/function response (auto-populated) |
+| `$output` | Output value |
+| `$input` | Input parameters from request/function call |
+| `$auth` | Authenticated user context |
+| `$env` | Environment variables and request context |
+| `$db` | Database table reference for queries |
+| `$this` | Current context reference |
+| `$result` | Used in reduce operations |
+
+```xs
+// ❌ Wrong - using reserved variable name
+var $response { value = "test" }    // Error: $response is reserved
+
+// ✅ Correct - use a different name
+var $api_response { value = "test" }
+var $my_result { value = "test" }
+```
+
+### Type Names (Common Aliases)
+
+XanoScript uses specific type names. Common aliases from other languages won't work.
+
+> **Full reference:** For complete type details and validation, see `xanoscript_docs({ topic: "types" })`.
+
+| ❌ Wrong | ✅ Correct | Description |
+|----------|------------|-------------|
+| `boolean` | `bool` | Boolean true/false |
+| `integer` | `int` | 32-bit integer |
+| `string` | `text` | UTF-8 string |
+| `number` | `decimal` | Floating-point number |
+| `float` | `decimal` | Floating-point number |
+| `array` | `type[]` | Array (e.g., `text[]`, `int[]`) |
+| `list` | `type[]` | Array (e.g., `text[]`, `int[]`) |
+
+```xs
+// ❌ Wrong - invalid type names
+input {
+  boolean is_active    // Error: use "bool"
+  integer count        // Error: use "int"
+  string name          // Error: use "text"
+}
+
+// ✅ Correct - proper XanoScript types
+input {
+  bool is_active
+  int count
+  text name
+}
+```
+
 ### Variable Declaration
 ```xs
 var $name { value = "initial value" }
@@ -35,7 +91,7 @@ conditional {
 api.request {
   url = "https://api.example.com/data"
   method = "POST"
-  params = $payload
+  params = $payload   // Note: "params" is used for request body, NOT "body"
   headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
 } as $api_result
 
@@ -47,6 +103,27 @@ precondition ($api_result.response.status == 200) {
 var $data { value = $api_result.response.result }
 ```
 
+### api.request Response Structure
+The response object contains:
+```xs
+$result.response.status    // HTTP status code (200, 404, 500, etc.)
+$result.response.result    // Parsed response body (JSON decoded)
+$result.response.headers   // Response headers object
+```
+
+### While Loop
+```xs
+stack {
+  var $counter { value = 0 }
+  while ($counter < 10) {
+    each {
+      var.update $counter { value = $counter + 1 }
+      debug.log { value = "Iteration: " ~ ($counter|to_text) }
+    }
+  }
+}
+```
+
 ### String Concatenation
 ```xs
 var $greeting { value = "Hello, " ~ $input.name ~ "!" }
@@ -55,6 +132,116 @@ var $greeting { value = "Hello, " ~ $input.name ~ "!" }
 var $message { value = "Status: " ~ ($status|to_text) ~ " - " ~ ($data|json_encode) }
 ```
 
+### Input Block Syntax
+
+> **Full reference:** For complete input types and validation options, see `xanoscript_docs({ topic: "types" })`.
+
+```xs
+input {
+  // Required input
+  text name
+
+  // Optional input (can be omitted)
+  text nickname?
+
+  // Optional with default value
+  text role?="user"
+
+  // With filters applied
+  email contact filters=trim|lower
+
+  // Optional with default AND filters
+  text search?="" filters=trim
+
+  // Array type
+  text[] tags filters=trim
+
+  // Nested object with schema
+  object address {
+    schema {
+      text street
+      text city
+      text country?="US"
+    }
+  }
+}
+```
+
+### Error Types Reference
+
+> **Full reference:** For try-catch, throw, and preconditions, see `xanoscript_docs({ topic: "syntax" })`.
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 Bad Request | Invalid input data |
+| `accessdenied` | 403 Forbidden | Authorization failure |
+| `notfound` | 404 Not Found | Resource doesn't exist |
+| `standard` | 500 Internal Server Error | General errors |
+
+### Quick Filter Reference
+
+> **Full reference:** For the complete list of filters with examples, see `xanoscript_docs({ topic: "syntax" })`.
+
+**String Filters:**
+```xs
+$s|trim                    // Remove whitespace
+$s|to_lower                // Lowercase
+$s|to_upper                // Uppercase
+$s|substr:1:3              // Substring from index 1, length 3
+$s|split:","               // Split by delimiter → array
+$s|replace:"old":"new"     // Replace text
+$s|contains:"text"         // Check if contains → bool
+$s|strlen                  // String length
+```
+
+**Array Filters:**
+```xs
+$arr|first                 // First element
+$arr|last                  // Last element
+$arr|count                 // Array length
+$arr|push:$item            // Add to end
+$arr|pop                   // Remove & return last
+$arr|join:","              // Join to string
+$arr|map:$$.name           // Transform elements
+$arr|filter:$$.active      // Filter elements
+$arr|find:$$.id == 5       // Find first match
+```
+
+**Object Filters:**
+```xs
+$obj|get:"key"             // Get property value
+$obj|get:"key":"default"   // With default if missing
+$obj|set:"key":"value"     // Set property
+$obj|has:"key"             // Check if key exists → bool
+$obj|keys                  // Get all keys → array
+$obj|values                // Get all values → array
+```
+
+**Type Conversion:**
+```xs
+$val|to_text               // Convert to string
+$val|to_int                // Convert to integer
+$val|to_decimal            // Convert to decimal
+$val|to_bool               // Convert to boolean
+$val|json_encode           // Object → JSON string
+$str|json_decode           // JSON string → object
+```
+
+**Null Handling:**
+```xs
+$val|first_notnull:"default"   // Default if null
+$val|first_notempty:"default"  // Default if empty
+$val ?? "default"               // Nullish coalescing (same as first_notnull)
+```
+
+**Encoding:**
+```xs
+$s|url_encode              // URL encode
+$s|url_decode              // URL decode
+$s|base64_encode           // Base64 encode
+$s|base64_decode           // Base64 decode
+```
+
 ---
 
 ## Common Patterns
@@ -77,6 +264,8 @@ precondition ($input.email|contains:"@") {
 
 ### 2. Database CRUD
 
+> **Full reference:** For all db.* operations including transactions, see `xanoscript_docs({ topic: "database" })`.
+
 ```xs
 // Create
 db.add "user" {
@@ -142,6 +331,8 @@ var $active_items { value = $items|filter:$$.is_active == true }
 
 ### 5. Error Handling with Try-Catch
 
+> **Full reference:** For all error handling patterns, see `xanoscript_docs({ topic: "syntax" })`.
+
 ```xs
 try_catch {
   try {
@@ -159,6 +350,8 @@ try_catch {
 
 ### 6. Authentication Check
 
+> **Full reference:** For security best practices, see `xanoscript_docs({ topic: "security" })`.
+
 ```xs
 // Require authenticated user
 precondition ($auth.id != null) {
@@ -220,6 +413,8 @@ var $response {
 
 ### 9. Date/Time Operations
 
+> **Full reference:** For all date/time filters, see `xanoscript_docs({ topic: "syntax" })`.
+
 ```xs
 // Current timestamp
 var $now { value = now }
@@ -239,6 +434,8 @@ db.query "event" {
 
 ### 10. JSON API Response
 
+> **Full reference:** For external API patterns, see `xanoscript_docs({ topic: "integrations" })`.
+
 ```xs
 api.request {
   url = "https://api.openai.com/v1/chat/completions"
@@ -287,42 +484,104 @@ conditional {
 
 ### 2. Missing parentheses in filter concatenation
 ```xs
-// ❌ Wrong
+// ❌ Wrong - parse error
 var $msg { value = $status|to_text ~ " - " ~ $data|json_encode }
 
-// ✅ Correct
+// ✅ Correct - wrap filtered expressions in parentheses
 var $msg { value = ($status|to_text) ~ " - " ~ ($data|json_encode) }
 ```
 
-### 3. Using `body` instead of `params` for api.request
+### 3. Missing parentheses in filter comparisons
 ```xs
-// ❌ Wrong
+// ❌ Wrong - parse error
+if ($array|count > 0) { }
+
+// ✅ Correct - wrap filter expression in parentheses
+if (($array|count) > 0) { }
+```
+
+### 4. Using `body` instead of `params` for api.request
+```xs
+// ❌ Wrong - "body" is not valid
 api.request {
   url = "..."
   method = "POST"
-  body = $payload  // "body" is not valid!
+  body = $payload
 }
 
-// ✅ Correct
+// ✅ Correct - use "params" for request body
 api.request {
   url = "..."
   method = "POST"
-  params = $payload  // Use "params" for request body
+  params = $payload
 }
 ```
 
-### 4. Using `default` filter (doesn't exist)
+### 5. Using `default` filter (doesn't exist)
 ```xs
-// ❌ Wrong
+// ❌ Wrong - no "default" filter exists
 var $value { value = $input.optional|default:"fallback" }
 
-// ✅ Correct
+// ✅ Correct - use first_notnull or ?? operator
 var $value { value = $input.optional|first_notnull:"fallback" }
 // or
 var $value { value = $input.optional ?? "fallback" }
+
+// For object key access with default, use get with 3rd parameter
+var $val { value = $obj|get:"key":"default_value" }
+```
+
+### 6. Using reserved variable names
+```xs
+// ❌ Wrong - $response is reserved
+var $response { value = "test" }
+
+// ✅ Correct - use a different name
+var $api_response { value = "test" }
+```
+
+### 7. Wrong type names
+```xs
+// ❌ Wrong - invalid type names
+input {
+  boolean active      // Use "bool"
+  integer count       // Use "int"
+  string name         // Use "text"
+}
+
+// ✅ Correct
+input {
+  bool active
+  int count
+  text name
+}
+```
+
+### 8. Object literal syntax (using = instead of :)
+```xs
+// ❌ Wrong - object literals use : not =
+var $data { value = { customer = $id } }
+
+// ✅ Correct - use : for object properties
+var $data { value = { customer: $id } }
+```
+
+### 9. Throw block with commas
+```xs
+// ❌ Wrong - throw blocks don't use commas
+throw {
+  name = "Error",
+  value = "message"
+}
+
+// ✅ Correct - no commas between properties
+throw {
+  name = "Error"
+  value = "message"
+}
 ```
 
-### 5. Using $env in run.job input blocks
+### 10. Using $env in run.job input blocks
 ```xs
 // ❌ Wrong - $env not allowed in input blocks
 run.job "my_job" {
@@ -331,10 +590,64 @@ run.job "my_job" {
   }
 }
 
-// ✅ Correct - use $env in the stack
+// ✅ Correct - access $env in the stack instead
 run.job "my_job" {
   stack {
     var $api_key { value = $env.API_KEY }
   }
 }
 ```
+
+### 11. Using `object` type without schema
+```xs
+// ❌ Wrong - object requires a schema
+input {
+  object data        // Error: needs schema
+}
+
+// ✅ Correct - use json for arbitrary data
+input {
+  json data          // Accepts any JSON
+}
+
+// ✅ Or define a schema for object
+input {
+  object data {
+    schema {
+      text name
+      int id
+    }
+  }
+}
+```
+
+### 12. While loop outside of stack block
+```xs
+// ❌ Wrong - while must be inside stack
+while (true) {
+  each { ... }
+}
+
+// ✅ Correct - wrap in stack block
+stack {
+  while (true) {
+    each { ... }
+  }
+}
+```
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `syntax` | Complete filter reference, operators, system variables |
+| `types` | Data types, input validation, schema definitions |
+| `database` | All db.* operations: query, get, add, edit, delete |
+| `functions` | Reusable function stacks, async patterns, loops |
+| `apis` | HTTP endpoints, authentication, CRUD patterns |
+| `security` | Security best practices and authentication |
+| `integrations` | External API patterns (OpenAI, Stripe, etc.) |

package/dist/xanoscript_docs/syntax.md

@@ -280,6 +280,8 @@ Generate numeric ranges with the `..` operator:
 
 ## Type Filters
 
+> **Full reference:** For input types and validation, see `xanoscript_docs({ topic: "types" })`.
+
 | Filter | Example | Result |
 |--------|---------|--------|
 | `to_int` | `"123"\|to_int` | `123` |
@@ -343,6 +345,8 @@ $ts|timestamp_day_of_week    // Day (0=Sunday)
 
 ## Security Filters
 
+> **Full reference:** For security best practices, see `xanoscript_docs({ topic: "security" })`.
+
 | Filter | Example |
 |--------|---------|
 | `md5` | `"text"\|md5` |
@@ -359,6 +363,8 @@ $ts|timestamp_day_of_week    // Day (0=Sunday)
 
 ## DB Query Filters
 
+> **Full reference:** For complete database operations, see `xanoscript_docs({ topic: "database" })`.
+
 Used in `db.query` where clauses:
 
 | Filter | Example | Description |
@@ -731,6 +737,8 @@ $db.created_at|timestamp_epoch_ms            // Milliseconds since epoch
 
 ### Vector Operations (AI/ML)
 
+> **Full reference:** For AI agents and embeddings, see `xanoscript_docs({ topic: "agents" })`.
+
 Additional vector similarity functions:
 
 ```xs
@@ -741,3 +749,17 @@ $db.embedding|inner_product:$input.vector            // Inner product
 // Geo covers (for polygon containment)
 $db.boundary|covers:$input.point                     // Polygon covers point
 ```
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `quickstart` | Common patterns, examples, mistakes to avoid |
+| `types` | Data types, input validation, schema definitions |
+| `database` | All db.* operations with query examples |
+| `functions` | Reusable function stacks, async patterns |
+| `security` | Security best practices and authentication |

package/dist/xanoscript_docs/types.md

@@ -362,3 +362,17 @@ precondition ($input.start_date < $input.end_date) {
 2. **Use filters first** - Prefer declarative filters over stack validation
 3. **Mark sensitive data** - Use `sensitive = true` for PII/credentials
 4. **Validate at boundaries** - Validate user input, trust internal calls
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `schema` | Runtime schema parsing and validation |
+| `syntax` | All filters, operators, and error handling |
+| `quickstart` | Common patterns and mistakes to avoid |
+| `functions` | Using input blocks in functions |
+| `apis` | Using input blocks in API endpoints |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.34",
+  "version": "1.0.35",
   "description": "MCP server and library for Xano development - XanoScript validation, Meta API, Run API, and CLI documentation",
   "type": "module",
   "main": "dist/lib.js",