@xano/developer-mcp 1.0.53 → 1.0.54

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 cheatsheet (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,
@@ -134,7 +135,14 @@ export const xanoscriptDocsToolDefinition = {
                 description: "'full' = complete documentation with explanations and examples. " +
                     "'quick_reference' = compact cheatsheet 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', 'quickstart']). " +
+                    "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

@@ -93,7 +93,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 +133,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 +148,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 +163,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 +241,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 +252,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

@@ -70,7 +70,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 +83,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 +100,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");
@@ -270,6 +282,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", "quickstart"],
+            });
+            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("quickstart");
+        });
+        it("should throw when all topics are excluded via exclude_topics", () => {
+            expect(() => readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "branch.xs",
+                exclude_topics: ["syntax", "cheatsheet", "quickstart", "debugging", "branch"],
+            })).toThrow("No documentation found");
+        });
         it("should throw for invalid docs path", () => {
             expect(() => readXanoscriptDocsV2("/nonexistent/path", { topic: "syntax" })).toThrow();
         });

package/package.json

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