@xano/developer-mcp 1.0.56 → 1.0.58

package/dist/tools/xanoscript_docs.test.js

@@ -0,0 +1,197 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { getXanoscriptDocsPath, setXanoscriptDocsPath, xanoscriptDocs, xanoscriptDocsTool, } from "./xanoscript_docs.js";
+import { toMcpResponse } from "./types.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DOCS_PATH = join(__dirname, "..", "xanoscript_docs");
+afterEach(() => {
+    // Reset to default so tests don't interfere with each other
+    setXanoscriptDocsPath(DOCS_PATH);
+});
+describe("getXanoscriptDocsPath", () => {
+    it("should return a string path", () => {
+        const path = getXanoscriptDocsPath();
+        expect(typeof path).toBe("string");
+        expect(path.length).toBeGreaterThan(0);
+    });
+    it("should return a path ending with xanoscript_docs", () => {
+        const path = getXanoscriptDocsPath();
+        expect(path).toMatch(/xanoscript_docs$/);
+    });
+    it("should return a consistent path on repeated calls", () => {
+        const path1 = getXanoscriptDocsPath();
+        const path2 = getXanoscriptDocsPath();
+        expect(path1).toBe(path2);
+    });
+});
+describe("setXanoscriptDocsPath", () => {
+    it("should override the docs path", () => {
+        const customPath = "/custom/docs/path";
+        setXanoscriptDocsPath(customPath);
+        expect(getXanoscriptDocsPath()).toBe(customPath);
+    });
+    it("should be used by xanoscriptDocs when set", () => {
+        setXanoscriptDocsPath(DOCS_PATH);
+        const result = xanoscriptDocs();
+        expect(result.documentation).toContain("Documentation version:");
+    });
+});
+describe("xanoscriptDocs", () => {
+    it("should return README when called with no args", () => {
+        const result = xanoscriptDocs();
+        expect(result).toHaveProperty("documentation");
+        expect(typeof result.documentation).toBe("string");
+        expect(result.documentation).toContain("Documentation version:");
+    });
+    it("should return specific topic documentation", () => {
+        const result = xanoscriptDocs({ topic: "syntax" });
+        expect(result.documentation).toContain("Documentation version:");
+    });
+    it("should return context-aware docs for file_path", () => {
+        const result = xanoscriptDocs({ file_path: "apis/users/create.xs" });
+        expect(result.documentation).toContain("XanoScript Documentation for:");
+        expect(result.documentation).toContain("Matched topics:");
+    });
+    it("should support quick_reference mode", () => {
+        const full = xanoscriptDocs({ topic: "syntax", mode: "full" });
+        const quick = xanoscriptDocs({ topic: "syntax", mode: "quick_reference" });
+        expect(quick.documentation.length).toBeLessThanOrEqual(full.documentation.length);
+    });
+    it("should throw for unknown topic", () => {
+        expect(() => xanoscriptDocs({ topic: "nonexistent" })).toThrow('Unknown topic "nonexistent"');
+    });
+    it("should throw for invalid docs path", () => {
+        setXanoscriptDocsPath("/nonexistent/path");
+        expect(() => xanoscriptDocs({ topic: "syntax" })).toThrow();
+    });
+});
+describe("xanoscriptDocsTool", () => {
+    it("should return success with data for valid call", () => {
+        const result = xanoscriptDocsTool();
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+        expect(typeof result.data).toBe("string");
+        expect(result.error).toBeUndefined();
+    });
+    it("should return success with topic docs", () => {
+        const result = xanoscriptDocsTool({ topic: "syntax" });
+        expect(result.success).toBe(true);
+        expect(result.data).toContain("Documentation version:");
+    });
+    it("should return error for unknown topic", () => {
+        const result = xanoscriptDocsTool({ topic: "nonexistent" });
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Unknown topic");
+    });
+    it("should return error for invalid docs path", () => {
+        setXanoscriptDocsPath("/nonexistent/path");
+        const result = xanoscriptDocsTool({ topic: "syntax" });
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Error retrieving XanoScript documentation");
+    });
+    it("should return multi-content array for file_path mode", () => {
+        const result = xanoscriptDocsTool({ file_path: "apis/users/create.xs" });
+        expect(result.success).toBe(true);
+        expect(Array.isArray(result.data)).toBe(true);
+        const data = result.data;
+        // First element is the header
+        expect(data[0]).toContain("XanoScript Documentation for: apis/users/create.xs");
+        expect(data[0]).toContain("Matched topics:");
+        expect(data[0]).toContain("Version:");
+        // Remaining elements are per-topic content
+        expect(data.length).toBeGreaterThan(1);
+    });
+    it("should return single string for topic mode", () => {
+        const result = xanoscriptDocsTool({ topic: "syntax" });
+        expect(result.success).toBe(true);
+        expect(typeof result.data).toBe("string");
+        expect(Array.isArray(result.data)).toBe(false);
+    });
+    it("should return single string for no-args mode", () => {
+        const result = xanoscriptDocsTool();
+        expect(result.success).toBe(true);
+        expect(typeof result.data).toBe("string");
+        expect(Array.isArray(result.data)).toBe(false);
+    });
+    it("should produce multiple MCP content blocks for file_path via toMcpResponse", () => {
+        const result = xanoscriptDocsTool({ file_path: "apis/users/create.xs" });
+        const mcpResponse = toMcpResponse(result);
+        expect(mcpResponse.isError).toBeUndefined();
+        // Should have multiple content blocks (header + N topics)
+        expect(mcpResponse.content.length).toBeGreaterThan(1);
+        // All blocks should be text type
+        for (const block of mcpResponse.content) {
+            expect(block.type).toBe("text");
+            expect(typeof block.text).toBe("string");
+        }
+    });
+    it("should produce single MCP content block for topic mode via toMcpResponse", () => {
+        const result = xanoscriptDocsTool({ topic: "syntax" });
+        const mcpResponse = toMcpResponse(result);
+        expect(mcpResponse.content).toHaveLength(1);
+        expect(mcpResponse.content[0].type).toBe("text");
+    });
+    it("should include structuredContent for file_path mode", () => {
+        const result = xanoscriptDocsTool({ file_path: "apis/users/create.xs" });
+        expect(result.success).toBe(true);
+        expect(result.structuredContent).toBeDefined();
+        expect(result.structuredContent).toHaveProperty("file_path", "apis/users/create.xs");
+        expect(result.structuredContent).toHaveProperty("mode", "quick_reference");
+        expect(result.structuredContent).toHaveProperty("version");
+        expect(result.structuredContent).toHaveProperty("topics");
+        expect(Array.isArray(result.structuredContent.topics)).toBe(true);
+    });
+    it("should include structuredContent for topic mode", () => {
+        const result = xanoscriptDocsTool({ topic: "syntax" });
+        expect(result.success).toBe(true);
+        expect(result.structuredContent).toBeDefined();
+        expect(result.structuredContent).toHaveProperty("documentation");
+    });
+    it("should include structuredContent in MCP response", () => {
+        const result = xanoscriptDocsTool({ file_path: "apis/users/create.xs" });
+        const mcpResponse = toMcpResponse(result);
+        expect(mcpResponse.structuredContent).toBeDefined();
+        expect(mcpResponse.structuredContent).toHaveProperty("file_path");
+        expect(mcpResponse.structuredContent).toHaveProperty("topics");
+    });
+});
+describe("xanoscriptDocs structured output", () => {
+    it("should include topics array for file_path mode", () => {
+        const result = xanoscriptDocs({ file_path: "apis/users/create.xs" });
+        expect(result.topics).toBeDefined();
+        expect(Array.isArray(result.topics)).toBe(true);
+        expect(result.topics.length).toBeGreaterThan(0);
+    });
+    it("should have topic and content fields in each TopicDoc", () => {
+        const result = xanoscriptDocs({ file_path: "apis/users/create.xs" });
+        for (const doc of result.topics) {
+            expect(doc).toHaveProperty("topic");
+            expect(doc).toHaveProperty("content");
+            expect(typeof doc.topic).toBe("string");
+            expect(typeof doc.content).toBe("string");
+            expect(doc.content.length).toBeGreaterThan(0);
+        }
+    });
+    it("should not include topics array for topic mode", () => {
+        const result = xanoscriptDocs({ topic: "syntax" });
+        expect(result.topics).toBeUndefined();
+    });
+    it("should not include topics array for no-args mode", () => {
+        const result = xanoscriptDocs();
+        expect(result.topics).toBeUndefined();
+    });
+    it("should respect exclude_topics in structured output", () => {
+        const result = xanoscriptDocs({
+            file_path: "apis/users/create.xs",
+            exclude_topics: ["syntax", "essentials"],
+        });
+        expect(result.topics).toBeDefined();
+        const topicNames = result.topics.map((d) => d.topic);
+        expect(topicNames).not.toContain("syntax");
+        expect(topicNames).not.toContain("essentials");
+    });
+});

package/dist/xanoscript.d.ts

@@ -12,10 +12,15 @@ export interface DocConfig {
 export interface XanoscriptDocsArgs {
     topic?: string;
     file_path?: string;
-    mode?: "full" | "quick_reference";
+    mode?: "full" | "quick_reference" | "index";
     exclude_topics?: string[];
 }
 export declare const XANOSCRIPT_DOCS_V2: Record<string, DocConfig>;
+/**
+ * Clear all cached documentation content and version data.
+ * Useful for testing or when docs files change at runtime.
+ */
+export declare function clearDocsCache(): void;
 /**
  * Get list of topics that apply to a given file path based on applyTo patterns
  */
@@ -32,6 +37,17 @@ export declare function getXanoscriptDocsVersion(docsPath: string): string;
  * Read XanoScript documentation with v2 structure
  */
 export declare function readXanoscriptDocsV2(docsPath: string, args?: XanoscriptDocsArgs): string;
+export interface TopicDoc {
+    topic: string;
+    content: string;
+}
+/**
+ * Read documentation as structured per-topic entries for file_path mode.
+ * Returns each matched topic as a separate object for multi-content MCP responses.
+ */
+export declare function readXanoscriptDocsStructured(docsPath: string, args: XanoscriptDocsArgs & {
+    file_path: string;
+}): TopicDoc[];
 /**
  * Get available topic names
  */

package/dist/xanoscript.js

@@ -7,191 +7,43 @@
 import { readFileSync } from "fs";
 import { join } from "path";
 import { minimatch } from "minimatch";
+import docsIndex from "./xanoscript_docs/docs_index.json" with { type: "json" };
 // =============================================================================
-// Documentation Configuration
+// Documentation Configuration (loaded from docs_index.json)
 // =============================================================================
-export const XANOSCRIPT_DOCS_V2 = {
-    readme: {
-        file: "README.md",
-        applyTo: [],
-        description: "XanoScript overview, workspace structure, and quick reference",
-    },
-    essentials: {
-        file: "essentials.md",
-        applyTo: ["**/*.xs"],
-        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",
-    },
-    "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",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tools/**/*.xs", "agents/**/*.xs"],
-        description: "Data types, input blocks, and validation",
-    },
-    tables: {
-        file: "tables.md",
-        applyTo: ["tables/*.xs"],
-        description: "Database schema definitions with indexes and relationships",
-    },
-    functions: {
-        file: "functions.md",
-        applyTo: ["functions/**/*.xs"],
-        description: "Reusable function stacks with inputs and responses",
-    },
-    apis: {
-        file: "apis.md",
-        applyTo: ["apis/**/*.xs"],
-        description: "HTTP endpoint definitions with authentication and CRUD patterns",
-    },
-    tasks: {
-        file: "tasks.md",
-        applyTo: ["tasks/*.xs"],
-        description: "Scheduled and cron jobs",
-    },
-    triggers: {
-        file: "triggers.md",
-        applyTo: ["triggers/**/*.xs"],
-        description: "Event-driven handlers (table, realtime, workspace, agent, MCP)",
-    },
-    database: {
-        file: "database.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs", "tools/**/*.xs"],
-        description: "All db.* operations: query, get, add, edit, patch, delete",
-    },
-    agents: {
-        file: "agents.md",
-        applyTo: ["agents/**/*.xs"],
-        description: "AI agent configuration with LLM providers and tools",
-    },
-    tools: {
-        file: "tools.md",
-        applyTo: ["tools/**/*.xs"],
-        description: "AI tools for agents and MCP servers",
-    },
-    "mcp-servers": {
-        file: "mcp-servers.md",
-        applyTo: ["mcp_servers/**/*.xs"],
-        description: "MCP server definitions exposing tools",
-    },
-    "unit-testing": {
-        file: "unit-testing.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "middleware/**/*.xs"],
-        description: "Unit tests, mocks, and assertions within functions, APIs, and middleware",
-    },
-    "workflow-tests": {
-        file: "workflow-tests.md",
-        applyTo: ["workflow_test/**/*.xs"],
-        description: "End-to-end workflow tests with data source selection and tags",
-    },
-    integrations: {
-        file: "integrations.md",
-        applyTo: [],
-        description: "External service integrations index - see sub-topics for details",
-    },
-    "integrations/cloud-storage": {
-        file: "integrations/cloud-storage.md",
-        applyTo: [],
-        description: "AWS S3, Azure Blob, and GCP Storage operations",
-    },
-    "integrations/search": {
-        file: "integrations/search.md",
-        applyTo: [],
-        description: "Elasticsearch, OpenSearch, and Algolia search operations",
-    },
-    "integrations/redis": {
-        file: "integrations/redis.md",
-        applyTo: [],
-        description: "Redis caching, rate limiting, and queue operations",
-    },
-    "integrations/external-apis": {
-        file: "integrations/external-apis.md",
-        applyTo: [],
-        description: "HTTP requests with api.request patterns",
-    },
-    "integrations/utilities": {
-        file: "integrations/utilities.md",
-        applyTo: [],
-        description: "Local storage, email, zip, and Lambda utilities",
-    },
-    frontend: {
-        file: "frontend.md",
-        applyTo: ["static/**/*"],
-        description: "Static frontend development and deployment",
-    },
-    run: {
-        file: "run.md",
-        applyTo: ["run/**/*.xs"],
-        description: "Run job and service configurations for the Xano Job Runner",
-    },
-    addons: {
-        file: "addons.md",
-        applyTo: ["addons/*.xs"],
-        description: "Reusable subqueries for fetching related data",
-    },
-    debugging: {
-        file: "debugging.md",
-        applyTo: ["**/*.xs"],
-        description: "Logging, inspecting, and debugging XanoScript execution",
-    },
-    performance: {
-        file: "performance.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Performance optimization best practices",
-    },
-    realtime: {
-        file: "realtime.md",
-        applyTo: ["triggers/**/*.xs"],
-        description: "Real-time channels and events for push updates",
-    },
-    schema: {
-        file: "schema.md",
-        applyTo: [],
-        description: "Runtime schema parsing and validation",
-    },
-    security: {
-        file: "security.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Security best practices for authentication and authorization",
-    },
-    streaming: {
-        file: "streaming.md",
-        applyTo: [],
-        description: "Streaming data from files, requests, and responses",
-    },
-    middleware: {
-        file: "middleware.md",
-        applyTo: ["middleware/**/*.xs"],
-        description: "Request/response interceptors for functions, queries, tasks, and tools",
-    },
-    branch: {
-        file: "branch.md",
-        applyTo: ["branch.xs"],
-        description: "Branch-level settings: middleware, history retention, visual styling",
-    },
-    workspace: {
-        file: "workspace.md",
-        applyTo: ["workspace/**/*.xs"],
-        description: "Workspace-level settings: environment variables, preferences, realtime",
-    },
-};
+function buildDocsConfig() {
+    const config = {};
+    for (const [key, topic] of Object.entries(docsIndex.topics)) {
+        config[key] = {
+            file: topic.file,
+            applyTo: topic.applyTo,
+            description: topic.description,
+        };
+    }
+    return config;
+}
+export const XANOSCRIPT_DOCS_V2 = buildDocsConfig();
+// =============================================================================
+// Content Cache
+// =============================================================================
+const _fileCache = new Map();
+let _versionCache = null;
+/**
+ * Clear all cached documentation content and version data.
+ * Useful for testing or when docs files change at runtime.
+ */
+export function clearDocsCache() {
+    _fileCache.clear();
+    _versionCache = null;
+}
+function cachedReadFile(filePath) {
+    const cached = _fileCache.get(filePath);
+    if (cached !== undefined)
+        return cached;
+    const content = readFileSync(filePath, "utf-8");
+    _fileCache.set(filePath, content);
+    return content;
+}
 // =============================================================================
 // Core Functions
 // =============================================================================
@@ -239,9 +91,14 @@ export function extractQuickReference(content, topic) {
  * Get the documentation version from the version.json file
  */
 export function getXanoscriptDocsVersion(docsPath) {
+    if (_versionCache && _versionCache.path === docsPath) {
+        return _versionCache.version;
+    }
     try {
-        const versionFile = readFileSync(join(docsPath, "version.json"), "utf-8");
-        return JSON.parse(versionFile).version || "unknown";
+        const versionFile = cachedReadFile(join(docsPath, "version.json"));
+        const version = JSON.parse(versionFile).version || "unknown";
+        _versionCache = { path: docsPath, version };
+        return version;
     }
     catch {
         return "unknown";
@@ -251,13 +108,39 @@ export function getXanoscriptDocsVersion(docsPath) {
  * Read XanoScript documentation with v2 structure
  */
 export function readXanoscriptDocsV2(docsPath, args) {
+    const version = getXanoscriptDocsVersion(docsPath);
+    // Index mode: return compact topic listing with byte sizes
+    if (args?.mode === "index") {
+        const rows = Object.entries(XANOSCRIPT_DOCS_V2).map(([name, config]) => {
+            let size;
+            try {
+                size = cachedReadFile(join(docsPath, config.file)).length;
+            }
+            catch {
+                size = 0;
+            }
+            const sizeKb = (size / 1024).toFixed(1);
+            return `| ${name} | ${config.description} | ${sizeKb} KB |`;
+        });
+        return [
+            `# XanoScript Documentation Index`,
+            ``,
+            `Version: ${version}`,
+            `Topics: ${rows.length}`,
+            ``,
+            `| Topic | Description | Size |`,
+            `|-------|-------------|------|`,
+            ...rows,
+            ``,
+            `Use topic='<name>' to load a specific topic. Use mode='quick_reference' for compact output.`,
+        ].join("\n");
+    }
     // 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) {
-        const readme = readFileSync(join(docsPath, "README.md"), "utf-8");
+        const readme = cachedReadFile(join(docsPath, "README.md"));
         return `${readme}\n\n---\nDocumentation version: ${version}`;
     }
     // Context-aware: return docs matching file pattern
@@ -272,7 +155,7 @@ export function readXanoscriptDocsV2(docsPath, args) {
         }
         const docs = topics.map((t) => {
             const config = XANOSCRIPT_DOCS_V2[t];
-            const content = readFileSync(join(docsPath, config.file), "utf-8");
+            const content = cachedReadFile(join(docsPath, config.file));
             return mode === "quick_reference"
                 ? extractQuickReference(content, t)
                 : content;
@@ -286,12 +169,39 @@ export function readXanoscriptDocsV2(docsPath, args) {
         const availableTopics = Object.keys(XANOSCRIPT_DOCS_V2).join(", ");
         throw new Error(`Unknown topic "${args.topic}".\n\nAvailable topics: ${availableTopics}`);
     }
-    const content = readFileSync(join(docsPath, config.file), "utf-8");
+    const content = cachedReadFile(join(docsPath, config.file));
     const doc = mode === "quick_reference"
         ? extractQuickReference(content, args.topic)
         : content;
     return `${doc}\n\n---\nDocumentation version: ${version}`;
 }
+/**
+ * Read documentation as structured per-topic entries for file_path mode.
+ * Returns each matched topic as a separate object for multi-content MCP responses.
+ */
+export function readXanoscriptDocsStructured(docsPath, args) {
+    const mode = args.mode || "quick_reference";
+    let topics = getDocsForFilePath(args.file_path);
+    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(", ")}`);
+    }
+    return topics.map((t) => {
+        const config = XANOSCRIPT_DOCS_V2[t];
+        const content = cachedReadFile(join(docsPath, config.file));
+        return {
+            topic: t,
+            content: mode === "quick_reference"
+                ? extractQuickReference(content, t)
+                : content,
+        };
+    });
+}
+// =============================================================================
+// Topic Metadata
+// =============================================================================
 /**
  * Get available topic names
  */

package/dist/xanoscript.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { XANOSCRIPT_DOCS_V2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, readXanoscriptDocsV2, getTopicNames, getTopicDescriptions, } from "./xanoscript.js";
+import { XANOSCRIPT_DOCS_V2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, readXanoscriptDocsV2, readXanoscriptDocsStructured, getTopicNames, getTopicDescriptions, } from "./xanoscript.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const DOCS_PATH = join(__dirname, "xanoscript_docs");
@@ -316,6 +316,30 @@ Even more content.
         it("should throw for invalid docs path", () => {
             expect(() => readXanoscriptDocsV2("/nonexistent/path", { topic: "syntax" })).toThrow();
         });
+        it("should return compact index with mode: index", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, { mode: "index" });
+            expect(result).toContain("# XanoScript Documentation Index");
+            expect(result).toContain("Version:");
+            expect(result).toContain("Topics:");
+            expect(result).toContain("| Topic | Description | Size |");
+            // Should contain some known topics
+            expect(result).toContain("| syntax |");
+            expect(result).toContain("| essentials |");
+            expect(result).toContain("| database |");
+            // Should contain KB size indicators
+            expect(result).toContain("KB |");
+        });
+        it("should return index mode without requiring topic or file_path", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, { mode: "index" });
+            // Index mode ignores topic/file_path — just returns the listing
+            expect(result).toContain("# XanoScript Documentation Index");
+        });
+        it("should return index that is significantly smaller than full docs", () => {
+            const index = readXanoscriptDocsV2(DOCS_PATH, { mode: "index" });
+            const full = readXanoscriptDocsV2(DOCS_PATH, { topic: "syntax", mode: "full" });
+            // Index should be compact — smaller than even a single full topic
+            expect(index.length).toBeLessThan(full.length);
+        });
     });
     describe("getTopicNames", () => {
         it("should return all topic names", () => {
@@ -347,4 +371,54 @@ Even more content.
             expect(descriptions).toContain("Expressions, operators");
         });
     });
+    describe("readXanoscriptDocsStructured", () => {
+        it("should return array of TopicDoc objects", () => {
+            const result = readXanoscriptDocsStructured(DOCS_PATH, {
+                file_path: "apis/users/create.xs",
+            });
+            expect(Array.isArray(result)).toBe(true);
+            expect(result.length).toBeGreaterThan(0);
+            for (const doc of result) {
+                expect(doc).toHaveProperty("topic");
+                expect(doc).toHaveProperty("content");
+                expect(typeof doc.topic).toBe("string");
+                expect(typeof doc.content).toBe("string");
+            }
+        });
+        it("should match the same topics as getDocsForFilePath", () => {
+            const filePath = "apis/users/create.xs";
+            const expected = getDocsForFilePath(filePath);
+            const result = readXanoscriptDocsStructured(DOCS_PATH, { file_path: filePath });
+            const resultTopics = result.map((d) => d.topic);
+            expect(resultTopics).toEqual(expected);
+        });
+        it("should respect exclude_topics", () => {
+            const result = readXanoscriptDocsStructured(DOCS_PATH, {
+                file_path: "apis/users/create.xs",
+                exclude_topics: ["syntax", "essentials"],
+            });
+            const topics = result.map((d) => d.topic);
+            expect(topics).not.toContain("syntax");
+            expect(topics).not.toContain("essentials");
+        });
+        it("should throw when all topics are excluded", () => {
+            expect(() => readXanoscriptDocsStructured(DOCS_PATH, {
+                file_path: "branch.xs",
+                exclude_topics: ["syntax", "essentials", "debugging", "branch"],
+            })).toThrow("No documentation found");
+        });
+        it("should use quick_reference mode by default", () => {
+            const quickResult = readXanoscriptDocsStructured(DOCS_PATH, {
+                file_path: "tables/users.xs",
+            });
+            const fullResult = readXanoscriptDocsStructured(DOCS_PATH, {
+                file_path: "tables/users.xs",
+                mode: "full",
+            });
+            // Quick reference content should be shorter than full
+            const quickTotal = quickResult.reduce((sum, d) => sum + d.content.length, 0);
+            const fullTotal = fullResult.reduce((sum, d) => sum + d.content.length, 0);
+            expect(quickTotal).toBeLessThanOrEqual(fullTotal);
+        });
+    });
 });