@xano/developer-mcp 1.0.21 → 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/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;