@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/run_api_docs/format.js

@@ -1,175 +1,8 @@
 /**
  * Formatting utilities for Run API documentation output
+ * Re-exports the shared formatter with Run API configuration
  */
-/**
- * Base URL information included with any topic that has endpoints
- * NOTE: The Run API uses a FIXED base URL, not the user's Xano instance URL
- */
-const BASE_URL_INFO = `## Base URL
-\`\`\`
-https://app.dev.xano.com/api:run/<endpoint>
-\`\`\`
-
-**Important:** This is a fixed URL - NOT your Xano instance URL. All Run API requests go to this central endpoint.
-
-Authorization: \`Bearer <your-access-token>\`
-`;
-function formatParameter(param) {
-    const required = param.required ? " (required)" : "";
-    const defaultVal = param.default !== undefined ? ` [default: ${param.default}]` : "";
-    const enumVals = param.enum ? ` [options: ${param.enum.join(", ")}]` : "";
-    return `  - \`${param.name}\`: ${param.type}${required}${defaultVal}${enumVals} - ${param.description}`;
-}
-function formatEndpoint(ep, detailLevel) {
-    const lines = [];
-    // Method and path
-    lines.push(`### ${ep.method} ${ep.path}`);
-    if (ep.tool_name) {
-        lines.push(`**Tool:** \`${ep.tool_name}\``);
-    }
-    lines.push("");
-    lines.push(ep.description);
-    if (detailLevel === "overview") {
-        return lines.join("\n");
-    }
-    // Parameters
-    if (ep.parameters?.length) {
-        lines.push("");
-        lines.push("**Parameters:**");
-        for (const param of ep.parameters) {
-            lines.push(formatParameter(param));
-        }
-    }
-    // Request body
-    if (ep.request_body) {
-        lines.push("");
-        lines.push(`**Request Body:** \`${ep.request_body.type}\``);
-        if (ep.request_body.properties) {
-            for (const [key, val] of Object.entries(ep.request_body.properties)) {
-                const req = val.required ? " (required)" : "";
-                lines.push(`  - \`${key}\`: ${val.type}${req} - ${val.description || ""}`);
-            }
-        }
-    }
-    // Example (only in detailed/examples mode)
-    if (detailLevel === "examples" && ep.example) {
-        lines.push("");
-        lines.push("**Example:**");
-        lines.push("```");
-        lines.push(`${ep.example.method} ${ep.example.path}`);
-        if (ep.example.body) {
-            lines.push(JSON.stringify(ep.example.body, null, 2));
-        }
-        lines.push("```");
-    }
-    return lines.join("\n");
-}
-function formatExample(ex) {
-    const lines = [];
-    lines.push(`### ${ex.title}`);
-    lines.push("");
-    lines.push(ex.description);
-    lines.push("");
-    lines.push("**Request:**");
-    lines.push("```");
-    lines.push(`${ex.request.method} ${ex.request.path}`);
-    if (ex.request.headers) {
-        for (const [key, val] of Object.entries(ex.request.headers)) {
-            lines.push(`${key}: ${val}`);
-        }
-    }
-    if (ex.request.body) {
-        lines.push("");
-        lines.push(JSON.stringify(ex.request.body, null, 2));
-    }
-    lines.push("```");
-    if (ex.response !== undefined) {
-        lines.push("");
-        lines.push("**Response:**");
-        lines.push("```json");
-        lines.push(JSON.stringify(ex.response, null, 2));
-        lines.push("```");
-    }
-    return lines.join("\n");
-}
-function formatPattern(pattern) {
-    const lines = [];
-    lines.push(`### ${pattern.name}`);
-    if (pattern.description) {
-        lines.push("");
-        lines.push(pattern.description);
-    }
-    lines.push("");
-    lines.push("**Steps:**");
-    for (const step of pattern.steps) {
-        lines.push(step);
-    }
-    if (pattern.example) {
-        lines.push("");
-        lines.push("**Example:**");
-        lines.push("```");
-        lines.push(pattern.example);
-        lines.push("```");
-    }
-    return lines.join("\n");
-}
+import { formatDocumentation as formatDoc, RUN_API_CONFIG, } from "../meta_api_docs/format.js";
 export function formatDocumentation(doc, detailLevel = "detailed", includeSchemas = true) {
-    const sections = [];
-    // Header
-    sections.push(`# ${doc.title}`);
-    sections.push("");
-    sections.push(doc.description);
-    // AI Hints (always include for AI optimization)
-    if (doc.ai_hints) {
-        sections.push("");
-        sections.push("## AI Usage Hints");
-        sections.push(doc.ai_hints);
-    }
-    // Include base URL info if topic has endpoints or patterns (workflows)
-    if (doc.endpoints?.length || doc.patterns?.length) {
-        sections.push("");
-        sections.push(BASE_URL_INFO);
-    }
-    // Endpoints
-    if (doc.endpoints?.length) {
-        sections.push("## Endpoints");
-        for (const ep of doc.endpoints) {
-            sections.push("");
-            sections.push(formatEndpoint(ep, detailLevel));
-        }
-    }
-    // Patterns/Workflows
-    if (doc.patterns?.length) {
-        sections.push("");
-        sections.push("## Workflows");
-        for (const pattern of doc.patterns) {
-            sections.push("");
-            sections.push(formatPattern(pattern));
-        }
-    }
-    // Examples
-    if ((detailLevel === "detailed" || detailLevel === "examples") && doc.examples?.length) {
-        sections.push("");
-        sections.push("## Examples");
-        for (const ex of doc.examples) {
-            sections.push("");
-            sections.push(formatExample(ex));
-        }
-    }
-    // Schemas
-    if (includeSchemas && doc.schemas && Object.keys(doc.schemas).length > 0) {
-        sections.push("");
-        sections.push("## Schemas");
-        sections.push("");
-        sections.push("```json");
-        sections.push(JSON.stringify(doc.schemas, null, 2));
-        sections.push("```");
-    }
-    // Related topics
-    if (doc.related_topics?.length) {
-        sections.push("");
-        sections.push("## Related Topics");
-        sections.push(`Use \`run_api_docs\` with topic: ${doc.related_topics.join(", ")}`);
-    }
-    return sections.join("\n");
+    return formatDoc(doc, detailLevel, includeSchemas, RUN_API_CONFIG);
 }

package/dist/run_api_docs/format.test.d.ts

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

package/dist/run_api_docs/format.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import { formatDocumentation } from "./format.js";
+describe("run_api_docs/format", () => {
+    describe("formatDocumentation", () => {
+        const minimalDoc = {
+            topic: "test",
+            title: "Test Topic",
+            description: "A test topic description",
+        };
+        it("should use Run API config by default", () => {
+            const docWithEndpoints = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "GET",
+                        path: "/test",
+                        description: "Test endpoint",
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithEndpoints);
+            expect(result).toContain("https://app.dev.xano.com/api:run/");
+            expect(result).toContain("NOT your Xano instance URL");
+        });
+        it("should format documentation with title", () => {
+            const result = formatDocumentation(minimalDoc);
+            expect(result).toContain("# Test Topic");
+        });
+        it("should format documentation with description", () => {
+            const result = formatDocumentation(minimalDoc);
+            expect(result).toContain("A test topic description");
+        });
+        it("should respect detail level", () => {
+            const docWithExamples = {
+                ...minimalDoc,
+                examples: [
+                    {
+                        title: "Example",
+                        description: "Test",
+                        request: { method: "GET", path: "/test" },
+                    },
+                ],
+            };
+            const overviewResult = formatDocumentation(docWithExamples, "overview");
+            expect(overviewResult).not.toContain("## Examples");
+            const detailedResult = formatDocumentation(docWithExamples, "detailed");
+            expect(detailedResult).toContain("## Examples");
+        });
+        it("should use run_api_docs in related topics", () => {
+            const docWithRelated = {
+                ...minimalDoc,
+                related_topics: ["session", "history"],
+            };
+            const result = formatDocumentation(docWithRelated);
+            expect(result).toContain("run_api_docs");
+            expect(result).toContain("session, history");
+        });
+        it("should default to detailed level", () => {
+            const docWithEndpoints = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "GET",
+                        path: "/test",
+                        description: "Test",
+                        parameters: [
+                            { name: "id", type: "string", description: "ID" },
+                        ],
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithEndpoints);
+            expect(result).toContain("**Parameters:**");
+        });
+        it("should default to including schemas", () => {
+            const docWithSchemas = {
+                ...minimalDoc,
+                schemas: {
+                    TestSchema: { type: "object" },
+                },
+            };
+            const result = formatDocumentation(docWithSchemas);
+            expect(result).toContain("## Schemas");
+        });
+    });
+});

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

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

package/dist/run_api_docs/index.test.js

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { topics, getTopicNames, getTopicDescriptions, handleRunApiDocs, runApiDocsToolDefinition, } from "./index.js";
+describe("run_api_docs/index", () => {
+    describe("topics", () => {
+        it("should have all expected topics", () => {
+            const expectedTopics = [
+                "start",
+                "run",
+                "session",
+                "history",
+                "data",
+                "workflows",
+            ];
+            expect(Object.keys(topics)).toEqual(expectedTopics);
+        });
+        it("should have valid TopicDoc structure for each topic", () => {
+            for (const [key, doc] of Object.entries(topics)) {
+                expect(doc).toHaveProperty("topic");
+                expect(doc).toHaveProperty("title");
+                expect(doc).toHaveProperty("description");
+                expect(typeof doc.topic).toBe("string");
+                expect(typeof doc.title).toBe("string");
+                expect(typeof doc.description).toBe("string");
+                expect(doc.topic).toBe(key);
+            }
+        });
+    });
+    describe("getTopicNames", () => {
+        it("should return all topic names", () => {
+            const names = getTopicNames();
+            expect(names).toEqual(Object.keys(topics));
+        });
+        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 topic descriptions", () => {
+            const descriptions = getTopicDescriptions();
+            expect(typeof descriptions).toBe("string");
+            expect(descriptions).toContain("- start:");
+            expect(descriptions).toContain("- run:");
+            expect(descriptions).toContain("- session:");
+        });
+        it("should include all topics", () => {
+            const descriptions = getTopicDescriptions();
+            for (const key of Object.keys(topics)) {
+                expect(descriptions).toContain(`- ${key}:`);
+            }
+        });
+    });
+    describe("handleRunApiDocs", () => {
+        it("should return error for undefined topic", () => {
+            const result = handleRunApiDocs(undefined);
+            expect(result).toContain('Error: Unknown topic "undefined"');
+            expect(result).toContain("Available topics:");
+        });
+        it("should return error for unknown topic", () => {
+            const result = handleRunApiDocs("nonexistent");
+            expect(result).toContain('Error: Unknown topic "nonexistent"');
+            expect(result).toContain("Available topics:");
+        });
+        it("should return documentation for valid topic", () => {
+            const result = handleRunApiDocs("start");
+            expect(result).not.toContain("Error:");
+        });
+        it("should return run documentation", () => {
+            const result = handleRunApiDocs("run");
+            expect(result).toContain("Run Execution");
+            expect(result).toContain("/run/exec");
+        });
+        it("should return session documentation", () => {
+            const result = handleRunApiDocs("session");
+            expect(result).toContain("Session");
+        });
+        it("should use default detail_level of detailed", () => {
+            const result = handleRunApiDocs("run");
+            expect(result).toContain("**Parameters:**");
+        });
+        it("should respect overview detail_level", () => {
+            const result = handleRunApiDocs("run", "overview");
+            expect(result).toContain("Run Execution");
+        });
+        it("should respect examples detail_level", () => {
+            const result = handleRunApiDocs("run", "examples");
+            expect(result).toContain("**Example:**");
+        });
+        it("should include schemas by default", () => {
+            const result = handleRunApiDocs("run");
+            expect(result).toContain("## Schemas");
+        });
+        it("should exclude schemas when includeSchemas is false", () => {
+            const result = handleRunApiDocs("run", "detailed", false);
+            expect(result).not.toContain("## Schemas");
+        });
+        it("should use Run API base URL", () => {
+            const result = handleRunApiDocs("run");
+            expect(result).toContain("https://app.dev.xano.com/api:run/");
+        });
+    });
+    describe("runApiDocsToolDefinition", () => {
+        it("should have required tool properties", () => {
+            expect(runApiDocsToolDefinition).toHaveProperty("name", "run_api_docs");
+            expect(runApiDocsToolDefinition).toHaveProperty("description");
+            expect(runApiDocsToolDefinition).toHaveProperty("inputSchema");
+        });
+        it("should mention fixed base URL in description", () => {
+            expect(runApiDocsToolDefinition.description).toContain("https://app.dev.xano.com/api:run/");
+        });
+        it("should have valid inputSchema", () => {
+            const schema = runApiDocsToolDefinition.inputSchema;
+            expect(schema.type).toBe("object");
+            expect(schema.properties).toHaveProperty("topic");
+            expect(schema.properties).toHaveProperty("detail_level");
+            expect(schema.properties).toHaveProperty("include_schemas");
+            expect(schema.required).toEqual(["topic"]);
+        });
+        it("should include all topic names in enum", () => {
+            const topicEnum = runApiDocsToolDefinition.inputSchema.properties.topic.enum;
+            expect(topicEnum).toEqual(getTopicNames());
+        });
+    });
+});

package/dist/templates/init-workspace.js

@@ -260,10 +260,10 @@ const response = await fetch(
 For writing XanoScript code, use:
 
 - \`xanoscript_docs()\` - Full documentation index
-- \`xanoscript_docs({ keyword: "function" })\` - Function syntax
-- \`xanoscript_docs({ keyword: "table" })\` - Table schema syntax
-- \`xanoscript_docs({ keyword: "api_query" })\` - API endpoint syntax
-- \`xanoscript_docs({ keyword: "syntax" })\` - Language reference
+- \`xanoscript_docs({ topic: "functions" })\` - Function syntax
+- \`xanoscript_docs({ topic: "tables" })\` - Table schema syntax
+- \`xanoscript_docs({ topic: "apis" })\` - API endpoint syntax
+- \`xanoscript_docs({ topic: "syntax" })\` - Language reference
 
 ## Validating XanoScript
 

package/dist/templates/xanoscript-index.d.ts

@@ -1,9 +1,11 @@
 /**
  * Template for xanoscript_docs index documentation
  * Edit this file to update the XanoScript documentation index
+ *
+ * NOTE: This template is currently unused. The actual documentation is served
+ * directly from the XANOSCRIPT_DOCS_V2 config in index.ts.
  */
 export interface XanoscriptIndexParams {
     version: string;
-    aliasLookup: Record<string, string[]>;
 }
 export declare function generateXanoscriptIndexTemplate(params: XanoscriptIndexParams): string;

package/dist/templates/xanoscript-index.js

@@ -1,69 +1,72 @@
 /**
  * Template for xanoscript_docs index documentation
  * Edit this file to update the XanoScript documentation index
+ *
+ * NOTE: This template is currently unused. The actual documentation is served
+ * directly from the XANOSCRIPT_DOCS_V2 config in index.ts.
  */
 export function generateXanoscriptIndexTemplate(params) {
-    const { version, aliasLookup } = params;
-    const formatRow = (keyword, description) => {
-        const aliases = aliasLookup[keyword]?.slice(0, 3).join(", ") || "";
-        return `| \`${keyword}\` | ${aliases ? aliases : "-"} | ${description} |`;
-    };
+    const { version } = params;
     return `# XanoScript Documentation Index
 Version: ${version}
 
-Use \`xanoscript_docs\` with a keyword to retrieve documentation.
+Use \`xanoscript_docs({ topic: "<topic>" })\` to retrieve documentation.
 
-## Core Concepts
-These return guidelines + examples for writing XanoScript code.
+## Core Language
+| Topic | Description |
+|-------|-------------|
+| \`syntax\` | Expressions, operators, filters, system variables |
+| \`types\` | Data types, validation, input blocks |
+| \`functions\` | Reusable function stacks, async, loops |
+| \`schema\` | Runtime schema parsing and validation |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("function", "Custom reusable functions in `functions/`")}
-${formatRow("api_query", "HTTP API endpoints in `apis/`")}
-${formatRow("table", "Database table schemas in `tables/`")}
-${formatRow("task", "Scheduled background tasks in `tasks/`")}
-${formatRow("triggers", "Event-driven handlers in `triggers/`")}
-${formatRow("tool", "AI-callable tools in `tools/`")}
-${formatRow("agent", "AI agents in `agents/`")}
-${formatRow("mcp_server", "MCP servers in `mcp_servers/`")}
+## Data
+| Topic | Description |
+|-------|-------------|
+| \`tables\` | Database schema definitions with indexes and relationships |
+| \`database\` | All db.* operations: query, get, add, edit, patch, delete |
+| \`addons\` | Reusable subqueries for fetching related data |
+| \`streaming\` | Streaming data from files, requests, and responses |
 
-## Language Reference
-Core syntax and operators.
+## APIs & Endpoints
+| Topic | Description |
+|-------|-------------|
+| \`apis\` | HTTP endpoint definitions with authentication and CRUD patterns |
+| \`tasks\` | Scheduled and cron jobs |
+| \`triggers\` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
+| \`realtime\` | Real-time channels and events for push updates |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("syntax", "Complete XanoScript syntax (stack, var, conditional, foreach, etc.)")}
-${formatRow("expressions", "Pipe operators and filters (string, math, array, date)")}
-${formatRow("input", "Input definition syntax (types, filters, validation)")}
-${formatRow("db_query", "Database query patterns (query, add, edit, delete)")}
-${formatRow("query_filter", "WHERE clause and filter syntax")}
+## AI & Agents
+| Topic | Description |
+|-------|-------------|
+| \`agents\` | AI agent configuration with LLM providers and tools |
+| \`tools\` | AI tools for agents and MCP servers |
+| \`mcp-servers\` | MCP server definitions exposing tools |
 
-## Development Workflows
-AI agent development strategies and phases.
+## Integrations
+| Topic | Description |
+|-------|-------------|
+| \`integrations\` | Cloud storage, Redis, security, and external APIs |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("workflow", "Overall XanoScript development workflow")}
-${formatRow("function_workflow", "AI workflow for creating functions")}
-${formatRow("api_workflow", "AI workflow for creating API endpoints")}
-${formatRow("table_workflow", "AI workflow for creating tables")}
-${formatRow("task_workflow", "AI workflow for creating tasks")}
+## Configuration
+| Topic | Description |
+|-------|-------------|
+| \`workspace\` | Workspace-level settings: environment variables, preferences, realtime |
+| \`branch\` | Branch-level settings: middleware, history retention, visual styling |
+| \`middleware\` | Request/response interceptors for functions, queries, tasks, and tools |
 
-## Specialized Topics
+## Development
+| Topic | Description |
+|-------|-------------|
+| \`testing\` | Unit tests, mocks, and assertions |
+| \`debugging\` | Logging, inspecting, and debugging XanoScript execution |
+| \`frontend\` | Static frontend development and deployment |
+| \`run\` | Run job and service configurations for the Xano Job Runner |
 
-| Keyword | Aliases | Description |
-|---------|---------|-------------|
-${formatRow("addons", "Reusable subqueries for related data")}
-${formatRow("debugging", "Logging and debugging tools")}
-${formatRow("frontend", "Frontend development with Xano")}
-${formatRow("lovable", "Building from Lovable-generated websites")}
-${formatRow("performance", "Performance optimization best practices")}
-${formatRow("realtime", "Real-time channels and events")}
-${formatRow("schema", "Runtime schema parsing and validation")}
-${formatRow("security", "Security best practices")}
-${formatRow("streaming", "Streaming data from files and responses")}
-${formatRow("testing", "Unit testing XanoScript code")}
-${formatRow("tips", "Tips and tricks")}
-${formatRow("run", "Run job and service configurations")}
+## Best Practices
+| Topic | Description |
+|-------|-------------|
+| \`performance\` | Performance optimization best practices |
+| \`security\` | Security best practices for authentication and authorization |
 `;
 }

package/dist/xanoscript.d.ts

@@ -0,0 +1,41 @@
+/**
+ * XanoScript Documentation Module
+ *
+ * This module contains the core logic for XanoScript documentation
+ * handling, separated from the MCP server for testability.
+ */
+export interface DocConfig {
+    file: string;
+    applyTo: string[];
+    description: string;
+}
+export interface XanoscriptDocsArgs {
+    topic?: string;
+    file_path?: string;
+    mode?: "full" | "quick_reference";
+}
+export declare const XANOSCRIPT_DOCS_V2: Record<string, DocConfig>;
+/**
+ * Get list of topics that apply to a given file path based on applyTo patterns
+ */
+export declare function getDocsForFilePath(filePath: string): string[];
+/**
+ * Extract just the Quick Reference section from a doc
+ */
+export declare function extractQuickReference(content: string, topic: string): string;
+/**
+ * Get the documentation version from the version.json file
+ */
+export declare function getXanoscriptDocsVersion(docsPath: string): string;
+/**
+ * Read XanoScript documentation with v2 structure
+ */
+export declare function readXanoscriptDocsV2(docsPath: string, args?: XanoscriptDocsArgs): string;
+/**
+ * Get available topic names
+ */
+export declare function getTopicNames(): string[];
+/**
+ * Get topic descriptions for documentation
+ */
+export declare function getTopicDescriptions(): string;