@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/xanoscript.js

@@ -0,0 +1,261 @@
+/**
+ * XanoScript Documentation Module
+ *
+ * This module contains the core logic for XanoScript documentation
+ * handling, separated from the MCP server for testability.
+ */
+import { readFileSync } from "fs";
+import { join } from "path";
+import { minimatch } from "minimatch";
+// =============================================================================
+// Documentation Configuration
+// =============================================================================
+export const XANOSCRIPT_DOCS_V2 = {
+    readme: {
+        file: "README.md",
+        applyTo: [],
+        description: "XanoScript overview, workspace structure, and quick reference",
+    },
+    syntax: {
+        file: "syntax.md",
+        applyTo: ["**/*.xs"],
+        description: "Expressions, operators, and filters for all XanoScript code",
+    },
+    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",
+    },
+    testing: {
+        file: "testing.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        description: "Unit tests, mocks, and assertions",
+    },
+    integrations: {
+        file: "integrations.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs"],
+        description: "Cloud storage, Redis, security, and external APIs",
+    },
+    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", "functions/**/*.xs", "apis/**/*.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: ["functions/**/*.xs", "apis/**/*.xs", "triggers/**/*.xs"],
+        description: "Real-time channels and events for push updates",
+    },
+    schema: {
+        file: "schema.md",
+        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
+        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: ["functions/**/*.xs", "apis/**/*.xs"],
+        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",
+    },
+};
+// =============================================================================
+// Core Functions
+// =============================================================================
+/**
+ * Get list of topics that apply to a given file path based on applyTo patterns
+ */
+export function getDocsForFilePath(filePath) {
+    const matches = [];
+    for (const [topic, config] of Object.entries(XANOSCRIPT_DOCS_V2)) {
+        if (topic === "readme")
+            continue; // Don't auto-include readme
+        for (const pattern of config.applyTo) {
+            if (minimatch(filePath, pattern)) {
+                matches.push(topic);
+                break;
+            }
+        }
+    }
+    // Always include syntax as foundation (if not already matched)
+    if (!matches.includes("syntax")) {
+        matches.unshift("syntax");
+    }
+    return matches;
+}
+/**
+ * Extract just the Quick Reference section from a doc
+ */
+export function extractQuickReference(content, topic) {
+    const lines = content.split("\n");
+    const startIdx = lines.findIndex((l) => l.startsWith("## Quick Reference"));
+    if (startIdx === -1) {
+        // Fallback: return first 50 lines or up to first ## section
+        const firstSection = lines.findIndex((l, i) => i > 0 && l.startsWith("## "));
+        return lines.slice(0, firstSection > 0 ? firstSection : 50).join("\n");
+    }
+    // Find the next ## section after Quick Reference
+    let endIdx = lines.findIndex((l, i) => i > startIdx && l.startsWith("## "));
+    if (endIdx === -1)
+        endIdx = lines.length;
+    // Include topic header for context
+    const header = `# ${topic}\n\n`;
+    return header + lines.slice(startIdx, endIdx).join("\n");
+}
+/**
+ * Get the documentation version from the version.json file
+ */
+export function getXanoscriptDocsVersion(docsPath) {
+    try {
+        const versionFile = readFileSync(join(docsPath, "version.json"), "utf-8");
+        return JSON.parse(versionFile).version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Read XanoScript documentation with v2 structure
+ */
+export function readXanoscriptDocsV2(docsPath, args) {
+    const mode = args?.mode || "full";
+    const version = getXanoscriptDocsVersion(docsPath);
+    try {
+        // Default: return README
+        if (!args?.topic && !args?.file_path) {
+            const readme = readFileSync(join(docsPath, "README.md"), "utf-8");
+            return `${readme}\n\n---\nDocumentation version: ${version}`;
+        }
+        // Context-aware: return docs matching file pattern
+        if (args?.file_path) {
+            const topics = getDocsForFilePath(args.file_path);
+            if (topics.length === 0) {
+                return `No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`;
+            }
+            const docs = topics.map((t) => {
+                const config = XANOSCRIPT_DOCS_V2[t];
+                const content = readFileSync(join(docsPath, config.file), "utf-8");
+                return mode === "quick_reference"
+                    ? extractQuickReference(content, t)
+                    : content;
+            });
+            const header = `# XanoScript Documentation for: ${args.file_path}\n\nMatched topics: ${topics.join(", ")}\nMode: ${mode}\nVersion: ${version}\n\n---\n\n`;
+            return header + docs.join("\n\n---\n\n");
+        }
+        // Topic-based: return specific doc
+        if (args?.topic) {
+            const config = XANOSCRIPT_DOCS_V2[args.topic];
+            if (!config) {
+                const availableTopics = Object.keys(XANOSCRIPT_DOCS_V2).join(", ");
+                return `Error: Unknown topic "${args.topic}".\n\nAvailable topics: ${availableTopics}`;
+            }
+            const content = readFileSync(join(docsPath, config.file), "utf-8");
+            const doc = mode === "quick_reference"
+                ? extractQuickReference(content, args.topic)
+                : content;
+            return `${doc}\n\n---\nDocumentation version: ${version}`;
+        }
+        return "Error: Invalid parameters";
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return `Error reading XanoScript documentation: ${errorMessage}`;
+    }
+}
+/**
+ * Get available topic names
+ */
+export function getTopicNames() {
+    return Object.keys(XANOSCRIPT_DOCS_V2);
+}
+/**
+ * Get topic descriptions for documentation
+ */
+export function getTopicDescriptions() {
+    return Object.entries(XANOSCRIPT_DOCS_V2)
+        .map(([k, v]) => `${k} (${v.description.split(".")[0]})`)
+        .join(", ");
+}

package/dist/xanoscript.test.d.ts

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

package/dist/xanoscript.test.js

@@ -0,0 +1,303 @@
+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";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DOCS_PATH = join(__dirname, "xanoscript_docs");
+describe("xanoscript module", () => {
+    describe("XANOSCRIPT_DOCS_V2", () => {
+        it("should have all expected topics", () => {
+            const expectedTopics = [
+                "readme",
+                "syntax",
+                "types",
+                "tables",
+                "functions",
+                "apis",
+                "tasks",
+                "triggers",
+                "database",
+                "agents",
+                "tools",
+                "mcp-servers",
+                "testing",
+                "integrations",
+                "frontend",
+                "run",
+                "addons",
+                "debugging",
+                "performance",
+                "realtime",
+                "schema",
+                "security",
+                "streaming",
+                "middleware",
+                "branch",
+                "workspace",
+            ];
+            expect(Object.keys(XANOSCRIPT_DOCS_V2)).toEqual(expectedTopics);
+        });
+        it("should have valid DocConfig structure for each topic", () => {
+            for (const [key, config] of Object.entries(XANOSCRIPT_DOCS_V2)) {
+                expect(config).toHaveProperty("file");
+                expect(config).toHaveProperty("applyTo");
+                expect(config).toHaveProperty("description");
+                expect(typeof config.file).toBe("string");
+                expect(Array.isArray(config.applyTo)).toBe(true);
+                expect(typeof config.description).toBe("string");
+                expect(config.file).toMatch(/\.md$/);
+            }
+        });
+    });
+    describe("getDocsForFilePath", () => {
+        it("should always include syntax for .xs files", () => {
+            const result = getDocsForFilePath("test.xs");
+            expect(result).toContain("syntax");
+        });
+        it("should match apis files", () => {
+            const result = getDocsForFilePath("apis/users/create.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("apis");
+            expect(result).toContain("types");
+            expect(result).toContain("database");
+            expect(result).toContain("testing");
+            expect(result).toContain("addons");
+        });
+        it("should match functions files", () => {
+            const result = getDocsForFilePath("functions/utils/format.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("functions");
+            expect(result).toContain("types");
+            expect(result).toContain("database");
+        });
+        it("should match tables files", () => {
+            const result = getDocsForFilePath("tables/users.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("tables");
+        });
+        it("should match tasks files", () => {
+            const result = getDocsForFilePath("tasks/cleanup.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("tasks");
+            expect(result).toContain("database");
+            expect(result).toContain("integrations");
+        });
+        it("should match triggers files", () => {
+            const result = getDocsForFilePath("triggers/table/users.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("triggers");
+            expect(result).toContain("realtime");
+        });
+        it("should match agents files", () => {
+            const result = getDocsForFilePath("agents/assistant/main.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("agents");
+            expect(result).toContain("types");
+        });
+        it("should match tools files", () => {
+            const result = getDocsForFilePath("tools/search/main.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("tools");
+            expect(result).toContain("types");
+            expect(result).toContain("database");
+        });
+        it("should match mcp_servers files", () => {
+            const result = getDocsForFilePath("mcp_servers/myserver/main.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("mcp-servers");
+        });
+        it("should match middleware files", () => {
+            const result = getDocsForFilePath("middleware/auth/main.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("middleware");
+        });
+        it("should match branch.xs", () => {
+            const result = getDocsForFilePath("branch.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("branch");
+        });
+        it("should match workspace.xs", () => {
+            const result = getDocsForFilePath("workspace.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("workspace");
+        });
+        it("should match static frontend files", () => {
+            const result = getDocsForFilePath("static/index.html");
+            expect(result).toContain("frontend");
+        });
+        it("should match run files", () => {
+            const result = getDocsForFilePath("run/job/main.xs");
+            expect(result).toContain("syntax");
+            expect(result).toContain("run");
+        });
+        it("should not include readme automatically", () => {
+            const result = getDocsForFilePath("apis/test.xs");
+            expect(result).not.toContain("readme");
+        });
+        it("should put syntax first if not already matched", () => {
+            const result = getDocsForFilePath("some/random/file.xs");
+            expect(result[0]).toBe("syntax");
+        });
+    });
+    describe("extractQuickReference", () => {
+        it("should extract Quick Reference section when present", () => {
+            const content = `# Title
+
+Some intro text.
+
+## Quick Reference
+
+Quick reference content here.
+
+More quick reference.
+
+## Next Section
+
+Other content.
+`;
+            const result = extractQuickReference(content, "test");
+            expect(result).toContain("# test");
+            expect(result).toContain("## Quick Reference");
+            expect(result).toContain("Quick reference content here.");
+            expect(result).not.toContain("## Next Section");
+            expect(result).not.toContain("Other content.");
+        });
+        it("should return fallback when no Quick Reference section", () => {
+            const content = `# Title
+
+Some intro text.
+
+## First Section
+
+Section content.
+
+## Second Section
+
+More content.
+`;
+            const result = extractQuickReference(content, "test");
+            expect(result).toContain("# Title");
+            expect(result).toContain("Some intro text.");
+            expect(result).not.toContain("## First Section");
+        });
+        it("should return up to 50 lines if no sections found", () => {
+            const lines = Array(100).fill("Line content").join("\n");
+            const result = extractQuickReference(lines, "test");
+            const resultLines = result.split("\n");
+            expect(resultLines.length).toBeLessThanOrEqual(50);
+        });
+        it("should include Quick Reference to end if no following section", () => {
+            const content = `# Title
+
+## Quick Reference
+
+Quick reference content.
+More content.
+Even more content.
+`;
+            const result = extractQuickReference(content, "test");
+            expect(result).toContain("Quick reference content.");
+            expect(result).toContain("More content.");
+            expect(result).toContain("Even more content.");
+        });
+    });
+    describe("getXanoscriptDocsVersion", () => {
+        it("should return version from valid docs path", () => {
+            const version = getXanoscriptDocsVersion(DOCS_PATH);
+            expect(typeof version).toBe("string");
+            // Version should be a semver-like string or "unknown"
+            expect(version).toMatch(/^(\d+\.\d+\.\d+|unknown)$/);
+        });
+        it("should return unknown for invalid path", () => {
+            const version = getXanoscriptDocsVersion("/nonexistent/path");
+            expect(version).toBe("unknown");
+        });
+    });
+    describe("readXanoscriptDocsV2", () => {
+        it("should return README when no args provided", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH);
+            expect(result).toContain("Documentation version:");
+        });
+        it("should return README when empty args provided", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, {});
+            expect(result).toContain("Documentation version:");
+        });
+        it("should return specific topic documentation", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, { topic: "syntax" });
+            expect(result).toContain("Documentation version:");
+        });
+        it("should return error for unknown topic", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, { topic: "nonexistent" });
+            expect(result).toContain('Error: Unknown topic "nonexistent"');
+            expect(result).toContain("Available topics:");
+        });
+        it("should return context-aware docs for file_path", () => {
+            const result = readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "apis/users/create.xs",
+            });
+            expect(result).toContain("XanoScript Documentation for: apis/users/create.xs");
+            expect(result).toContain("Matched topics:");
+            expect(result).toContain("Version:");
+        });
+        it("should support quick_reference mode for topic", () => {
+            const fullResult = readXanoscriptDocsV2(DOCS_PATH, {
+                topic: "syntax",
+                mode: "full",
+            });
+            const quickResult = readXanoscriptDocsV2(DOCS_PATH, {
+                topic: "syntax",
+                mode: "quick_reference",
+            });
+            // Quick reference should be shorter
+            expect(quickResult.length).toBeLessThanOrEqual(fullResult.length);
+        });
+        it("should support quick_reference mode for file_path", () => {
+            const fullResult = readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "apis/test.xs",
+                mode: "full",
+            });
+            const quickResult = readXanoscriptDocsV2(DOCS_PATH, {
+                file_path: "apis/test.xs",
+                mode: "quick_reference",
+            });
+            expect(quickResult).toContain("Mode: quick_reference");
+        });
+        it("should return error for invalid docs path", () => {
+            const result = readXanoscriptDocsV2("/nonexistent/path", {
+                topic: "syntax",
+            });
+            expect(result).toContain("Error reading XanoScript documentation:");
+        });
+    });
+    describe("getTopicNames", () => {
+        it("should return all topic names", () => {
+            const names = getTopicNames();
+            expect(names).toEqual(Object.keys(XANOSCRIPT_DOCS_V2));
+        });
+        it("should return an array of strings", () => {
+            const names = getTopicNames();
+            expect(Array.isArray(names)).toBe(true);
+            names.forEach((name) => {
+                expect(typeof name).toBe("string");
+            });
+        });
+    });
+    describe("getTopicDescriptions", () => {
+        it("should return formatted descriptions string", () => {
+            const descriptions = getTopicDescriptions();
+            expect(typeof descriptions).toBe("string");
+        });
+        it("should include all topics", () => {
+            const descriptions = getTopicDescriptions();
+            for (const key of Object.keys(XANOSCRIPT_DOCS_V2)) {
+                expect(descriptions).toContain(key);
+            }
+        });
+        it("should include topic descriptions", () => {
+            const descriptions = getTopicDescriptions();
+            expect(descriptions).toContain("XanoScript overview");
+            expect(descriptions).toContain("Expressions, operators");
+        });
+    });
+});