@xano/developer-mcp 1.0.54 → 1.0.57

package/README.md

@@ -208,6 +208,9 @@ const apiDocs = xanoscriptDocs({ file_path: 'api/users/create_post.xs' });
 
 // Get compact quick reference
 const quickRef = xanoscriptDocs({ topic: 'database', mode: 'quick_reference' });
+
+// Get topic index with sizes
+const index = xanoscriptDocs({ mode: 'index' });
 ```
 
 ### Get Meta API Documentation
@@ -335,16 +338,19 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 |-----------|------|----------|-------------|
 | `topic` | string | No | Specific documentation topic to retrieve |
 | `file_path` | string | No | File path being edited for context-aware docs (e.g., `api/users/create_post.xs`) |
-| `mode` | string | No | `full` (default) or `quick_reference` for compact syntax cheatsheet |
+| `mode` | string | No | `full` (default), `quick_reference` for compact syntax reference, or `index` for topic listing with sizes |
+| `exclude_topics` | string[] | No | Topic names to exclude from `file_path` results (e.g., topics already loaded) |
 
 **Available Topics:**
 
 | Topic | Description |
 |-------|-------------|
 | `readme` | XanoScript overview, workspace structure, and quick reference |
-| `cheatsheet` | Quick reference for 20 most common XanoScript patterns (recommended first stop) |
+| `essentials` | Common patterns, quick reference, and common mistakes to avoid |
 | `syntax` | Expressions, operators, and filters for all XanoScript code |
-| `quickstart` | Common patterns, quick reference, and common mistakes to avoid |
+| `syntax/string-filters` | String filters, regex, encoding, security filters, text functions |
+| `syntax/array-filters` | Array filters, functional operations, and array functions |
+| `syntax/functions` | Math filters/functions, object functions, bitwise operations |
 | `types` | Data types, input blocks, and validation |
 | `tables` | Database schema definitions with indexes and relationships |
 | `functions` | Reusable function stacks with inputs and responses |
@@ -381,15 +387,21 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 // Get overview
 xanoscript_docs()
 
-// Get quick reference cheatsheet (recommended first stop)
-xanoscript_docs({ topic: "cheatsheet" })
+// Get essentials (recommended first stop)
+xanoscript_docs({ topic: "essentials" })
 
 // Get specific topic
 xanoscript_docs({ topic: "functions" })
 
+// Discover available topics with sizes
+xanoscript_docs({ mode: "index" })
+
 // Context-aware: get all docs relevant to file being edited
 xanoscript_docs({ file_path: "api/users/create_post.xs" })
 
+// Context-aware with exclusions (skip already-loaded topics)
+xanoscript_docs({ file_path: "api/users/create_post.xs", exclude_topics: ["syntax", "essentials"] })
+
 // Compact quick reference (uses less context)
 xanoscript_docs({ topic: "database", mode: "quick_reference" })
 ```
@@ -505,9 +517,11 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | Resource URI | Description |
 |--------------|-------------|
 | `xanoscript://docs/readme` | Overview and quick reference |
-| `xanoscript://docs/cheatsheet` | Quick reference for 20 most common patterns |
+| `xanoscript://docs/essentials` | Common patterns, quick reference, and common mistakes to avoid |
 | `xanoscript://docs/syntax` | Expressions, operators, and filters |
-| `xanoscript://docs/quickstart` | Common patterns and common mistakes to avoid |
+| `xanoscript://docs/syntax/string-filters` | String filters, regex, encoding, security filters |
+| `xanoscript://docs/syntax/array-filters` | Array filters, functional operations |
+| `xanoscript://docs/syntax/functions` | Math filters/functions, object functions, bitwise |
 | `xanoscript://docs/types` | Data types and validation |
 | `xanoscript://docs/tables` | Database schema definitions |
 | `xanoscript://docs/functions` | Reusable function stacks |
@@ -561,10 +575,12 @@ xano-developer-mcp/
 │   ├── xanoscript.test.ts              # Tests for xanoscript module
 │   ├── xanoscript-language-server.d.ts # TypeScript declarations
 │   ├── tools/                          # Standalone tool modules
-│   │   ├── index.ts                    # Unified tool exports
+│   │   ├── index.ts                    # Unified tool exports & handler
+│   │   ├── index.test.ts               # Tests for tool handler
 │   │   ├── types.ts                    # Common types (ToolResult)
 │   │   ├── validate_xanoscript.ts      # XanoScript validation tool
 │   │   ├── xanoscript_docs.ts          # XanoScript docs tool
+│   │   ├── xanoscript_docs.test.ts     # Tests for xanoscript docs tool
 │   │   ├── mcp_version.ts              # Version tool
 │   │   ├── meta_api_docs.ts            # Meta API docs tool wrapper
 │   │   └── cli_docs.ts                 # CLI docs tool wrapper
@@ -582,9 +598,15 @@ xano-developer-mcp/
 │   │   ├── format.ts                   # Documentation formatter
 │   │   └── topics/                     # Individual topic modules
 │   └── xanoscript_docs/                # XanoScript language documentation
+│       ├── docs_index.json             # Machine-readable topic registry
 │       ├── version.json
 │       ├── README.md
+│       ├── essentials.md
 │       ├── syntax.md
+│       ├── syntax/                     # Syntax sub-topics
+│       │   ├── string-filters.md
+│       │   ├── array-filters.md
+│       │   └── functions.md
 │       └── ...
 ├── dist/                               # Compiled JavaScript output
 ├── vitest.config.ts                    # Test configuration
@@ -651,10 +673,12 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
 
 **XanoScript Documentation** (`src/xanoscript_docs/`):
 - Markdown files for XanoScript language reference
-- Configured in `src/index.ts` via `XANOSCRIPT_DOCS_V2` with:
+- Configured in `src/xanoscript_docs/docs_index.json` with:
   - **file**: The markdown file containing the documentation
-  - **applyTo**: Glob patterns for context-aware matching (e.g., `api/**/*.xs`)
+  - **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
   - **description**: Human-readable description of the topic
+  - **aliases**: Alternative names for topic lookup
+  - **priority**: Ordering weight for file_path matching
 
 **Meta API Documentation** (`src/meta_api_docs/`):
 - TypeScript modules with structured documentation
@@ -683,6 +707,8 @@ npm run test:coverage
 | Module | Test File | Description |
 |--------|-----------|-------------|
 | `xanoscript.ts` | `xanoscript.test.ts` | Core XanoScript documentation logic including file path matching and quick reference extraction |
+| `tools/index.ts` | `tools/index.test.ts` | Tool handler dispatch and argument validation |
+| `tools/xanoscript_docs.ts` | `tools/xanoscript_docs.test.ts` | XanoScript documentation tool and path resolution |
 | `meta_api_docs/index.ts` | `meta_api_docs/index.test.ts` | Meta API documentation handler and topic management |
 | `meta_api_docs/format.ts` | `meta_api_docs/format.test.ts` | Documentation formatting for endpoints, examples, and patterns |
 | `meta_api_docs/types.ts` | `meta_api_docs/types.test.ts` | Type structure validation |
@@ -695,6 +721,12 @@ Tests are co-located with source files using the `.test.ts` suffix:
 src/
 ├── xanoscript.ts
 ├── xanoscript.test.ts          # Tests for xanoscript.ts
+├── tools/
+│   ├── index.ts
+│   ├── index.test.ts           # Tests for tool handler
+│   ├── xanoscript_docs.ts
+│   ├── xanoscript_docs.test.ts # Tests for xanoscript docs tool
+│   └── ...
 ├── meta_api_docs/
 │   ├── index.ts
 │   ├── index.test.ts           # Tests for index.ts

package/dist/cli_docs/index.d.ts

@@ -50,4 +50,14 @@ export declare const cliDocsToolDefinition: {
         };
         required: string[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            documentation: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 };

package/dist/cli_docs/index.js

@@ -96,4 +96,14 @@ ${getTopicDescriptions()}
         },
         required: ["topic"],
     },
+    outputSchema: {
+        type: "object",
+        properties: {
+            documentation: {
+                type: "string",
+                description: "The CLI documentation content for the requested topic.",
+            },
+        },
+        required: ["documentation"],
+    },
 };

package/dist/index.js

@@ -14,7 +14,7 @@ import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 import { XANOSCRIPT_DOCS_V2, getXanoscriptDocsVersion } from "./xanoscript.js";
-import { toolDefinitions, handleTool, toMcpResponse, } from "./tools/index.js";
+import { toolDefinitions, handleTool, toMcpResponse, getXanoscriptDocsPath, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -24,24 +24,8 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.exit(0);
 }
 // =============================================================================
-// Path Resolution
+// Path Resolution (uses shared path from tools/xanoscript_docs.ts)
 // =============================================================================
-function getXanoscriptDocsPath() {
-    const possiblePaths = [
-        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 {
-            readFileSync(join(p, "version.json"));
-            return p;
-        }
-        catch {
-            continue;
-        }
-    }
-    return join(__dirname, "xanoscript_docs");
-}
 const XANOSCRIPT_DOCS_PATH = getXanoscriptDocsPath();
 // =============================================================================
 // MCP Server Setup

package/dist/lib.d.ts

@@ -42,10 +42,10 @@
  * @packageDocumentation
  */
 export { validateXanoscript, type ValidateXanoscriptArgs, type ValidationResult, type ParserDiagnostic, } from "./tools/validate_xanoscript.js";
-export { xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, } from "./tools/xanoscript_docs.js";
+export { xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, type TopicDoc, } from "./tools/xanoscript_docs.js";
 export { mcpVersion, getServerVersion, setServerVersion, type McpVersionResult, } from "./tools/mcp_version.js";
 export { metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult, } from "./tools/meta_api_docs.js";
 export { cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult, } from "./tools/cli_docs.js";
 export { type ToolResult, toMcpResponse } from "./tools/types.js";
-export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, type DocConfig, } from "./xanoscript.js";
+export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, readXanoscriptDocsStructured, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, clearDocsCache, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, type DocConfig, } from "./xanoscript.js";
 export { toolDefinitions, handleTool, validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVersionToolDefinition, metaApiDocsToolDefinition, cliDocsToolDefinition, } from "./tools/index.js";

package/dist/lib.js

@@ -61,7 +61,7 @@ export { toMcpResponse } from "./tools/types.js";
 // =============================================================================
 // XanoScript Core Exports (for advanced usage)
 // =============================================================================
-export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, } from "./xanoscript.js";
+export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, readXanoscriptDocsStructured, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, clearDocsCache, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, } from "./xanoscript.js";
 // =============================================================================
 // MCP Tool Definitions (for building custom MCP servers)
 // =============================================================================

package/dist/meta_api_docs/index.d.ts

@@ -55,4 +55,14 @@ export declare const metaApiDocsToolDefinition: {
         };
         required: string[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            documentation: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 };

package/dist/meta_api_docs/index.js

@@ -121,4 +121,14 @@ ${getTopicDescriptions()}
         },
         required: ["topic"],
     },
+    outputSchema: {
+        type: "object",
+        properties: {
+            documentation: {
+                type: "string",
+                description: "The Meta API documentation content for the requested topic.",
+            },
+        },
+        required: ["documentation"],
+    },
 };

package/dist/tools/cli_docs.js

@@ -54,6 +54,7 @@ export function cliDocsTool(args) {
         return {
             success: true,
             data: result.documentation,
+            structuredContent: { documentation: result.documentation },
         };
     }
     catch (error) {

package/dist/tools/index.d.ts

@@ -29,18 +29,134 @@
  * ```
  */
 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 { xanoscriptDocs, xanoscriptDocsTool, xanoscriptDocsToolDefinition, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, type TopicDoc } 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 { cliDocs, cliDocsTool, cliDocsToolDefinition, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult } from "./cli_docs.js";
 import { type ToolResult, toMcpResponse } from "./types.js";
-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, 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, type TopicDoc, mcpVersion, getServerVersion, setServerVersion, type McpVersionResult, metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult, cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult, type ToolResult, toMcpResponse, };
 export { validateXanoscriptTool, xanoscriptDocsTool, mcpVersionTool, metaApiDocsTool, cliDocsTool, };
 export { validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVersionToolDefinition, metaApiDocsToolDefinition, cliDocsToolDefinition, };
 /**
  * All tool definitions for MCP server registration
  */
 export declare const toolDefinitions: ({
+    name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            code: {
+                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: never[];
+    };
+    outputSchema: {
+        type: string;
+        properties: {
+            valid: {
+                type: string;
+                description: string;
+            };
+            message: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    inputSchema: {
+        type: string;
+        properties: {
+            topic: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            exclude_topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    outputSchema: {
+        type: string;
+        properties: {
+            documentation: {
+                type: string;
+                description: string;
+            };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                description: string;
+            };
+            version: {
+                type: string;
+                description: string;
+            };
+            topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+    };
+} | {
     name: string;
     annotations: {
         readOnlyHint: boolean;
@@ -54,6 +170,16 @@ export declare const toolDefinitions: ({
         properties: {};
         required: never[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            version: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 } | {
     name: string;
     annotations: {
@@ -80,6 +206,16 @@ export declare const toolDefinitions: ({
         };
         required: string[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            documentation: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 })[];
 /**
  * Handle a tool call by name and return the result.

package/dist/tools/index.js

@@ -37,6 +37,7 @@ import { mcpVersion, mcpVersionTool, mcpVersionToolDefinition, getServerVersion,
 import { metaApiDocs, metaApiDocsTool, metaApiDocsToolDefinition, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, } from "./meta_api_docs.js";
 import { cliDocs, cliDocsTool, cliDocsToolDefinition, cliTopics, getCliTopicNames, getCliTopicDescriptions, } from "./cli_docs.js";
 import { toMcpResponse } from "./types.js";
+import { z } from "zod";
 // =============================================================================
 // Standalone Tool Functions (for library usage)
 // =============================================================================
@@ -70,6 +71,41 @@ export const toolDefinitions = [
     cliDocsToolDefinition,
 ];
 // =============================================================================
+// Argument Schemas (Zod validation)
+// =============================================================================
+const validateXanoscriptSchema = z.object({
+    code: z.string().optional(),
+    file_path: z.string().optional(),
+    file_paths: z.array(z.string()).optional(),
+    directory: z.string().optional(),
+    pattern: z.string().optional(),
+});
+const xanoscriptDocsSchema = z.object({
+    topic: z.string().optional(),
+    file_path: z.string().optional(),
+    mode: z.enum(["full", "quick_reference", "index"]).optional(),
+    exclude_topics: z.array(z.string()).optional(),
+});
+const metaApiDocsSchema = z.object({
+    topic: z.string(),
+    detail_level: z.enum(["overview", "detailed", "examples"]).optional(),
+    include_schemas: z.boolean().optional(),
+});
+const cliDocsSchema = z.object({
+    topic: z.string(),
+    detail_level: z.enum(["overview", "detailed", "examples"]).optional(),
+});
+function parseArgs(schema, args) {
+    const result = schema.safeParse(args);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        return { ok: false, error: { success: false, error: `Invalid arguments: ${issues}` } };
+    }
+    return { ok: true, data: result.data };
+}
+// =============================================================================
 // Tool Handler (for MCP server)
 // =============================================================================
 /**
@@ -78,16 +114,32 @@ export const toolDefinitions = [
  */
 export function handleTool(name, args) {
     switch (name) {
-        case "validate_xanoscript":
-            return validateXanoscriptTool(args);
-        case "xanoscript_docs":
-            return xanoscriptDocsTool(args);
+        case "validate_xanoscript": {
+            const parsed = parseArgs(validateXanoscriptSchema, args);
+            if (!parsed.ok)
+                return parsed.error;
+            return validateXanoscriptTool(parsed.data);
+        }
+        case "xanoscript_docs": {
+            const parsed = parseArgs(xanoscriptDocsSchema, args);
+            if (!parsed.ok)
+                return parsed.error;
+            return xanoscriptDocsTool(parsed.data);
+        }
         case "mcp_version":
             return mcpVersionTool();
-        case "meta_api_docs":
-            return metaApiDocsTool(args);
-        case "cli_docs":
-            return cliDocsTool(args);
+        case "meta_api_docs": {
+            const parsed = parseArgs(metaApiDocsSchema, args);
+            if (!parsed.ok)
+                return parsed.error;
+            return metaApiDocsTool(parsed.data);
+        }
+        case "cli_docs": {
+            const parsed = parseArgs(cliDocsSchema, args);
+            if (!parsed.ok)
+                return parsed.error;
+            return cliDocsTool(parsed.data);
+        }
         default:
             return {
                 success: false,

package/dist/tools/index.test.d.ts

@@ -0,0 +1 @@
+export {};