@xano/developer-mcp 1.0.53 → 1.0.56

package/dist/tools/xanoscript_docs.d.ts

@@ -73,6 +73,13 @@ export declare const xanoscriptDocsToolDefinition: {
                 enum: string[];
                 description: string;
             };
+            exclude_topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: never[];
     };

package/dist/tools/xanoscript_docs.js

@@ -104,7 +104,8 @@ export const xanoscriptDocsToolDefinition = {
     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).",
+        "Use mode='quick_reference' for compact syntax reference (recommended for context efficiency). " +
+        "file_path mode defaults to 'quick_reference' to reduce context size; use mode='full' to get complete docs.",
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -132,9 +133,16 @@ export const xanoscriptDocsToolDefinition = {
                 type: "string",
                 enum: ["full", "quick_reference"],
                 description: "'full' = complete documentation with explanations and examples. " +
-                    "'quick_reference' = compact cheatsheet with just syntax patterns and signatures. " +
+                    "'quick_reference' = compact reference with just syntax patterns and signatures. " +
                     "Use 'quick_reference' to save context window space when you just need a reminder. " +
-                    "Default: 'full'.",
+                    "Default: 'full' for topic mode, 'quick_reference' for file_path mode.",
+            },
+            exclude_topics: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of topic names to exclude from file_path results. " +
+                    "Use this to skip topics you've already loaded (e.g., exclude_topics: ['syntax', 'essentials']). " +
+                    "Only applies when using file_path parameter.",
             },
         },
         required: [],

package/dist/xanoscript.d.ts

@@ -13,6 +13,7 @@ export interface XanoscriptDocsArgs {
     topic?: string;
     file_path?: string;
     mode?: "full" | "quick_reference";
+    exclude_topics?: string[];
 }
 export declare const XANOSCRIPT_DOCS_V2: Record<string, DocConfig>;
 /**

package/dist/xanoscript.js

@@ -16,20 +16,30 @@ export const XANOSCRIPT_DOCS_V2 = {
         applyTo: [],
         description: "XanoScript overview, workspace structure, and quick reference",
     },
-    cheatsheet: {
-        file: "cheatsheet.md",
+    essentials: {
+        file: "essentials.md",
         applyTo: ["**/*.xs"],
-        description: "Quick reference for 20 most common XanoScript patterns",
+        description: "Common patterns, quick reference, and common mistakes to avoid",
     },
     syntax: {
         file: "syntax.md",
         applyTo: ["**/*.xs"],
         description: "Expressions, operators, and filters for all XanoScript code",
     },
-    quickstart: {
-        file: "quickstart.md",
-        applyTo: ["**/*.xs"],
-        description: "Common patterns, quick reference, and common mistakes to avoid",
+    "syntax/string-filters": {
+        file: "syntax/string-filters.md",
+        applyTo: [],
+        description: "String filters, regex, encoding, security filters, text functions",
+    },
+    "syntax/array-filters": {
+        file: "syntax/array-filters.md",
+        applyTo: [],
+        description: "Array filters, functional operations, and array functions",
+    },
+    "syntax/functions": {
+        file: "syntax/functions.md",
+        applyTo: [],
+        description: "Math filters/functions, object functions, bitwise operations",
     },
     types: {
         file: "types.md",
@@ -93,7 +103,7 @@ export const XANOSCRIPT_DOCS_V2 = {
     },
     integrations: {
         file: "integrations.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs"],
+        applyTo: [],
         description: "External service integrations index - see sub-topics for details",
     },
     "integrations/cloud-storage": {
@@ -133,7 +143,7 @@ export const XANOSCRIPT_DOCS_V2 = {
     },
     addons: {
         file: "addons.md",
-        applyTo: ["addons/*.xs", "functions/**/*.xs", "apis/**/*.xs"],
+        applyTo: ["addons/*.xs"],
         description: "Reusable subqueries for fetching related data",
     },
     debugging: {
@@ -148,12 +158,12 @@ export const XANOSCRIPT_DOCS_V2 = {
     },
     realtime: {
         file: "realtime.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "triggers/**/*.xs"],
+        applyTo: ["triggers/**/*.xs"],
         description: "Real-time channels and events for push updates",
     },
     schema: {
         file: "schema.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        applyTo: [],
         description: "Runtime schema parsing and validation",
     },
     security: {
@@ -163,7 +173,7 @@ export const XANOSCRIPT_DOCS_V2 = {
     },
     streaming: {
         file: "streaming.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        applyTo: [],
         description: "Streaming data from files, requests, and responses",
     },
     middleware: {
@@ -241,7 +251,9 @@ export function getXanoscriptDocsVersion(docsPath) {
  * Read XanoScript documentation with v2 structure
  */
 export function readXanoscriptDocsV2(docsPath, args) {
-    const mode = args?.mode || "full";
+    // Default to quick_reference for file_path mode (loads many topics),
+    // full for topic mode (loads single topic)
+    const mode = args?.mode || (args?.file_path ? "quick_reference" : "full");
     const version = getXanoscriptDocsVersion(docsPath);
     // Default: return README
     if (!args?.topic && !args?.file_path) {
@@ -250,7 +262,11 @@ export function readXanoscriptDocsV2(docsPath, args) {
     }
     // Context-aware: return docs matching file pattern
     if (args?.file_path) {
-        const topics = getDocsForFilePath(args.file_path);
+        let topics = getDocsForFilePath(args.file_path);
+        // Filter out excluded topics
+        if (args.exclude_topics && args.exclude_topics.length > 0) {
+            topics = topics.filter((t) => !args.exclude_topics.includes(t));
+        }
         if (topics.length === 0) {
             throw new Error(`No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`);
         }

package/dist/xanoscript.test.js

@@ -10,9 +10,11 @@ describe("xanoscript module", () => {
         it("should have all expected topics", () => {
             const expectedTopics = [
                 "readme",
-                "cheatsheet",
+                "essentials",
                 "syntax",
-                "quickstart",
+                "syntax/string-filters",
+                "syntax/array-filters",
+                "syntax/functions",
                 "types",
                 "tables",
                 "functions",
@@ -70,7 +72,12 @@ describe("xanoscript module", () => {
             expect(result).toContain("types");
             expect(result).toContain("database");
             expect(result).toContain("unit-testing");
-            expect(result).toContain("addons");
+            // Niche topics should NOT be auto-included for apis
+            expect(result).not.toContain("addons");
+            expect(result).not.toContain("integrations");
+            expect(result).not.toContain("realtime");
+            expect(result).not.toContain("schema");
+            expect(result).not.toContain("streaming");
         });
         it("should match functions files", () => {
             const result = getDocsForFilePath("functions/utils/format.xs");
@@ -78,6 +85,12 @@ describe("xanoscript module", () => {
             expect(result).toContain("functions");
             expect(result).toContain("types");
             expect(result).toContain("database");
+            // Niche topics should NOT be auto-included for functions
+            expect(result).not.toContain("addons");
+            expect(result).not.toContain("integrations");
+            expect(result).not.toContain("realtime");
+            expect(result).not.toContain("schema");
+            expect(result).not.toContain("streaming");
         });
         it("should match tables files", () => {
             const result = getDocsForFilePath("tables/users.xs");
@@ -89,7 +102,8 @@ describe("xanoscript module", () => {
             expect(result).toContain("syntax");
             expect(result).toContain("tasks");
             expect(result).toContain("database");
-            expect(result).toContain("integrations");
+            // integrations is now topic-only (not auto-included)
+            expect(result).not.toContain("integrations");
         });
         it("should match triggers files", () => {
             const result = getDocsForFilePath("triggers/table/users.xs");
@@ -143,10 +157,10 @@ describe("xanoscript module", () => {
             const result = getDocsForFilePath("apis/test.xs");
             expect(result).not.toContain("readme");
         });
-        it("should include syntax and quickstart for .xs files", () => {
+        it("should include syntax and essentials for .xs files", () => {
             const result = getDocsForFilePath("some/random/file.xs");
             expect(result).toContain("syntax");
-            expect(result).toContain("quickstart");
+            expect(result).toContain("essentials");
         });
     });
     describe("extractQuickReference", () => {
@@ -270,6 +284,35 @@ Even more content.
             });
             expect(quickResult).toContain("Mode: quick_reference");
         });
+        it("should default to quick_reference mode for file_path", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "apis/test.xs",
+            });
+            expect(result).toContain("Mode: quick_reference");
+        });
+        it("should default to full mode for topic", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, { topic: "syntax" });
+            // Full mode returns the complete doc content, not quick_reference
+            expect(result).not.toContain("Mode: quick_reference");
+        });
+        it("should support exclude_topics with file_path", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "apis/users/create.xs",
+                exclude_topics: ["syntax", "essentials"],
+            });
+            expect(result).toContain("Matched topics:");
+            expect(result).not.toContain("Matched topics: syntax");
+            // Verify excluded topics are not in the matched list
+            const matchLine = result.split("\n").find((l) => l.startsWith("Matched topics:"));
+            expect(matchLine).not.toContain("syntax");
+            expect(matchLine).not.toContain("essentials");
+        });
+        it("should throw when all topics are excluded via exclude_topics", () => {
+            expect(() => readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "branch.xs",
+                exclude_topics: ["syntax", "essentials", "debugging", "branch"],
+            })).toThrow("No documentation found");
+        });
         it("should throw for invalid docs path", () => {
             expect(() => readXanoscriptDocsV2("/nonexistent/path", { topic: "syntax" })).toThrow();
         });

package/dist/xanoscript_docs/README.md

@@ -111,7 +111,7 @@ $db.table.field     // Database field reference (in queries)
 $this               // Current item in loops/maps
 ```
 
-**Reserved Variables:** The following cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`, `$index`.
+**Reserved Variables:** The following cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`, `$index`. See `xanoscript_docs({ topic: "essentials" })` for detailed variable access rules.
 
 ### Type Names
 
@@ -162,7 +162,7 @@ This helps AI tools apply the correct documentation based on the file being edit
 
 For common patterns and quick examples, use:
 ```
-xanoscript_docs({ topic: "quickstart" })
+xanoscript_docs({ topic: "essentials" })
 ```
 
 This includes:
@@ -182,8 +182,8 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 | Topic        | Description                                          | Key Sections |
 | ------------ | ---------------------------------------------------- | ------------ |
-| `quickstart` | Common patterns, quick examples, mistakes to avoid   | Patterns, Common Mistakes |
-| `syntax`     | Expressions, operators, filters, system variables    | Filters (L179-275), Error Handling (L411-477) |
+| `essentials` | Common patterns, quick examples, mistakes to avoid   | Patterns, Common Mistakes |
+| `syntax`     | Expressions, operators, filters, system variables    | Filters, Error Handling |
 | `types`      | Data types, validation, input blocks                 | Validation Filters, Input Blocks |
 | `functions`  | Reusable function stacks, async, loops               | Loops, Async Patterns |
 | `schema`     | Runtime schema parsing and validation                | parse.object, parse.array |
@@ -193,7 +193,7 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 | Topic       | Description                                                | Key Sections |
 | ----------- | ---------------------------------------------------------- | ------------ |
 | `tables`    | Database schema definitions with indexes and relationships | Indexes, Foreign Keys |
-| `database`  | All db.\* operations: query, get, add, edit, patch, delete | Decision Tree (L11), Bulk Ops (L450-529) |
+| `database`  | All db.\* operations: query, get, add, edit, patch, delete | Decision Tree, Bulk Ops |
 | `addons`    | Reusable subqueries for fetching related data              | Usage Patterns |
 | `streaming` | Streaming data from files, requests, and responses         | File Streams, API Streams |
 
@@ -201,7 +201,7 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 | Topic      | Description                                                     | Key Sections |
 | ---------- | --------------------------------------------------------------- | ------------ |
-| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns | Decision Tree (L9), CRUD Examples (L220-350) |
+| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns | Decision Tree, CRUD Examples |
 | `tasks`    | Scheduled and cron jobs                                         | Cron Syntax, Input Handling |
 | `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP)  | Predefined Inputs, Event Types |
 | `realtime` | Real-time channels and events for push updates                  | Channels, Events |
@@ -287,4 +287,4 @@ function "call_external_api" {
 }
 ```
 
-For more patterns, see `xanoscript_docs({ topic: "quickstart" })` or `xanoscript_docs({ topic: "integrations" })`.
+For more patterns, see `xanoscript_docs({ topic: "essentials" })` or `xanoscript_docs({ topic: "integrations" })`.

package/dist/xanoscript_docs/cheatsheet.md

@@ -112,7 +112,10 @@ db.edit "user" {
 }
 
 // Delete record
-db.del "user" { field_name = "id", field_value = $input.user_id }
+db.del "user" {
+  field_name = "id"
+  field_value = $input.user_id
+}
 ```
 
 ### API Requests

package/dist/xanoscript_docs/database.md

@@ -613,7 +613,7 @@ try_catch {
     conditional {
       if ($error.name == "DeadlockError") {
         // Retry logic
-        util.sleep { value = 100 }
+        util.sleep { value = 1 }                // value = seconds
         function.run "retry_transaction" { input = $input }
       }
       else {
@@ -646,6 +646,6 @@ Explore more with `xanoscript_docs({ topic: "<topic>" })`:
 |-------|-------------|
 | `tables` | Database schema definitions with indexes and relationships |
 | `syntax` | Query filters, operators, and expressions |
-| `quickstart` | Common CRUD patterns and examples |
+| `essentials` | Common CRUD patterns and examples |
 | `addons` | Reusable subqueries for fetching related data |
 | `performance` | Query optimization best practices |

package/dist/xanoscript_docs/docs_index.json

@@ -3,24 +3,33 @@
   "description": "Machine-readable index for XanoScript documentation",
 
   "topics": {
-    "cheatsheet": {
-      "file": "cheatsheet.md",
-      "purpose": "Quick reference for 20 most common operations",
+    "essentials": {
+      "file": "essentials.md",
+      "purpose": "Common patterns, quick reference, and mistakes to avoid",
       "priority": 1,
-      "aliases": ["quick", "common", "basics", "start"]
-    },
-    "quickstart": {
-      "file": "quickstart.md",
-      "purpose": "Common patterns and mistakes to avoid",
-      "priority": 2,
-      "aliases": ["start", "getting-started", "patterns", "mistakes"]
+      "aliases": ["quick", "common", "basics", "start", "cheatsheet", "quickstart", "patterns", "mistakes"]
     },
     "syntax": {
       "file": "syntax.md",
-      "purpose": "Operators, filters, expressions, error handling",
-      "priority": 3,
+      "purpose": "Operators, core filters, expressions, error handling",
+      "priority": 2,
       "aliases": ["filters", "operators", "expressions"]
     },
+    "syntax/string-filters": {
+      "file": "syntax/string-filters.md",
+      "purpose": "String filters, regex, encoding, security filters, text functions",
+      "aliases": ["string", "regex", "encoding", "security-filters"]
+    },
+    "syntax/array-filters": {
+      "file": "syntax/array-filters.md",
+      "purpose": "Array filters, functional operations, array functions",
+      "aliases": ["array", "map", "filter", "reduce", "sort"]
+    },
+    "syntax/functions": {
+      "file": "syntax/functions.md",
+      "purpose": "Math filters/functions, object functions, bitwise operations",
+      "aliases": ["math", "object", "bitwise"]
+    },
     "types": {
       "file": "types.md",
       "purpose": "Data types, validation, input blocks",
@@ -220,46 +229,44 @@
     "function.run": { "file": "functions.md" },
     "redis.get": { "file": "integrations/redis.md" },
     "redis.set": { "file": "integrations/redis.md" },
-    "storage.s3_put": { "file": "integrations/cloud-storage.md" },
-    "storage.s3_get": { "file": "integrations/cloud-storage.md" },
-    "array.push": { "file": "syntax.md" },
-    "array.pop": { "file": "syntax.md" },
-    "array.shift": { "file": "syntax.md" },
-    "array.unshift": { "file": "syntax.md" },
-    "array.merge": { "file": "syntax.md" },
-    "array.find": { "file": "syntax.md" },
-    "array.find_index": { "file": "syntax.md" },
-    "array.has": { "file": "syntax.md" },
-    "array.every": { "file": "syntax.md" },
-    "array.filter": { "file": "syntax.md" },
-    "array.filter_count": { "file": "syntax.md" },
-    "array.map": { "file": "syntax.md" },
-    "array.partition": { "file": "syntax.md" },
-    "array.group_by": { "file": "syntax.md" },
-    "array.union": { "file": "syntax.md" },
-    "array.difference": { "file": "syntax.md" },
-    "array.intersection": { "file": "syntax.md" },
-    "text.contains": { "file": "syntax.md" },
-    "text.icontains": { "file": "syntax.md" },
-    "text.starts_with": { "file": "syntax.md" },
-    "text.istarts_with": { "file": "syntax.md" },
-    "text.ends_with": { "file": "syntax.md" },
-    "text.iends_with": { "file": "syntax.md" },
-    "text.trim": { "file": "syntax.md" },
-    "text.ltrim": { "file": "syntax.md" },
-    "text.rtrim": { "file": "syntax.md" },
-    "text.append": { "file": "syntax.md" },
-    "text.prepend": { "file": "syntax.md" },
-    "math.add": { "file": "syntax.md" },
-    "math.sub": { "file": "syntax.md" },
-    "math.mul": { "file": "syntax.md" },
-    "math.div": { "file": "syntax.md" },
-    "math.bitwise.and": { "file": "syntax.md" },
-    "math.bitwise.or": { "file": "syntax.md" },
-    "math.bitwise.xor": { "file": "syntax.md" },
-    "object.keys": { "file": "syntax.md" },
-    "object.values": { "file": "syntax.md" },
-    "object.entries": { "file": "syntax.md" },
+    "array.push": { "file": "syntax/array-filters.md" },
+    "array.pop": { "file": "syntax/array-filters.md" },
+    "array.shift": { "file": "syntax/array-filters.md" },
+    "array.unshift": { "file": "syntax/array-filters.md" },
+    "array.merge": { "file": "syntax/array-filters.md" },
+    "array.find": { "file": "syntax/array-filters.md" },
+    "array.find_index": { "file": "syntax/array-filters.md" },
+    "array.has": { "file": "syntax/array-filters.md" },
+    "array.every": { "file": "syntax/array-filters.md" },
+    "array.filter": { "file": "syntax/array-filters.md" },
+    "array.filter_count": { "file": "syntax/array-filters.md" },
+    "array.map": { "file": "syntax/array-filters.md" },
+    "array.partition": { "file": "syntax/array-filters.md" },
+    "array.group_by": { "file": "syntax/array-filters.md" },
+    "array.union": { "file": "syntax/array-filters.md" },
+    "array.difference": { "file": "syntax/array-filters.md" },
+    "array.intersection": { "file": "syntax/array-filters.md" },
+    "text.contains": { "file": "syntax/string-filters.md" },
+    "text.icontains": { "file": "syntax/string-filters.md" },
+    "text.starts_with": { "file": "syntax/string-filters.md" },
+    "text.istarts_with": { "file": "syntax/string-filters.md" },
+    "text.ends_with": { "file": "syntax/string-filters.md" },
+    "text.iends_with": { "file": "syntax/string-filters.md" },
+    "text.trim": { "file": "syntax/string-filters.md" },
+    "text.ltrim": { "file": "syntax/string-filters.md" },
+    "text.rtrim": { "file": "syntax/string-filters.md" },
+    "text.append": { "file": "syntax/string-filters.md" },
+    "text.prepend": { "file": "syntax/string-filters.md" },
+    "math.add": { "file": "syntax/functions.md" },
+    "math.sub": { "file": "syntax/functions.md" },
+    "math.mul": { "file": "syntax/functions.md" },
+    "math.div": { "file": "syntax/functions.md" },
+    "math.bitwise.and": { "file": "syntax/functions.md" },
+    "math.bitwise.or": { "file": "syntax/functions.md" },
+    "math.bitwise.xor": { "file": "syntax/functions.md" },
+    "object.keys": { "file": "syntax/functions.md" },
+    "object.values": { "file": "syntax/functions.md" },
+    "object.entries": { "file": "syntax/functions.md" },
     "redis.remove": { "file": "integrations/redis.md" },
     "redis.keys": { "file": "integrations/redis.md" },
     "security.jwe_encode": { "file": "security.md" },
@@ -297,7 +304,7 @@
     "authentication": ["security.md", "apis.md"],
     "authorization": ["security.md"],
     "rate_limiting": ["security.md", "integrations/redis.md"],
-    "error_handling": ["syntax.md", "quickstart.md"],
+    "error_handling": ["syntax.md", "essentials.md"],
     "pagination": ["database.md", "apis.md"],
     "file_upload": ["integrations/cloud-storage.md", "streaming.md"],
     "caching": ["performance.md", "integrations/redis.md"],