@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/meta_api_docs/format.test.js

@@ -0,0 +1,274 @@
+import { describe, it, expect } from "vitest";
+import { formatDocumentation, META_API_CONFIG, RUN_API_CONFIG, } from "./format.js";
+describe("meta_api_docs/format", () => {
+    describe("META_API_CONFIG", () => {
+        it("should have correct base URL info", () => {
+            expect(META_API_CONFIG.baseUrlInfo).toContain("https://<your-instance-subdomain>.xano.io/api:meta/");
+            expect(META_API_CONFIG.toolName).toBe("meta_api_docs");
+        });
+    });
+    describe("RUN_API_CONFIG", () => {
+        it("should have correct base URL info", () => {
+            expect(RUN_API_CONFIG.baseUrlInfo).toContain("https://app.dev.xano.com/api:run/");
+            expect(RUN_API_CONFIG.toolName).toBe("run_api_docs");
+        });
+    });
+    describe("formatDocumentation", () => {
+        const minimalDoc = {
+            topic: "test",
+            title: "Test Topic",
+            description: "A test topic description",
+        };
+        it("should format minimal documentation", () => {
+            const result = formatDocumentation(minimalDoc);
+            expect(result).toContain("# Test Topic");
+            expect(result).toContain("A test topic description");
+        });
+        it("should include AI hints when present", () => {
+            const docWithHints = {
+                ...minimalDoc,
+                ai_hints: "Use this for testing purposes",
+            };
+            const result = formatDocumentation(docWithHints);
+            expect(result).toContain("## AI Usage Hints");
+            expect(result).toContain("Use this for testing purposes");
+        });
+        it("should format endpoints correctly", () => {
+            const docWithEndpoints = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "GET",
+                        path: "/test",
+                        description: "Get test data",
+                    },
+                    {
+                        method: "POST",
+                        path: "/test",
+                        description: "Create test data",
+                        tool_name: "create_test",
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithEndpoints);
+            expect(result).toContain("## Endpoints");
+            expect(result).toContain("### GET /test");
+            expect(result).toContain("### POST /test");
+            expect(result).toContain("**Tool:** `create_test`");
+        });
+        it("should format endpoint parameters", () => {
+            const docWithParams = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "GET",
+                        path: "/test/{id}",
+                        description: "Get test by ID",
+                        parameters: [
+                            {
+                                name: "id",
+                                type: "integer",
+                                required: true,
+                                description: "The test ID",
+                            },
+                            {
+                                name: "include_details",
+                                type: "boolean",
+                                required: false,
+                                default: false,
+                                description: "Include extra details",
+                            },
+                            {
+                                name: "format",
+                                type: "string",
+                                description: "Output format",
+                                enum: ["json", "xml", "csv"],
+                            },
+                        ],
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithParams);
+            expect(result).toContain("**Parameters:**");
+            expect(result).toContain("`id`: integer (required)");
+            expect(result).toContain("`include_details`: boolean [default: false]");
+            expect(result).toContain("[options: json, xml, csv]");
+        });
+        it("should format request body", () => {
+            const docWithBody = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "POST",
+                        path: "/test",
+                        description: "Create test",
+                        request_body: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    required: true,
+                                    description: "The name",
+                                },
+                                value: {
+                                    type: "number",
+                                    description: "The value",
+                                },
+                            },
+                        },
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithBody);
+            expect(result).toContain("**Request Body:** `object`");
+            expect(result).toContain("`name`: string (required)");
+            expect(result).toContain("`value`: number");
+        });
+        it("should format examples in detailed mode", () => {
+            const docWithExamples = {
+                ...minimalDoc,
+                examples: [
+                    {
+                        title: "Basic Example",
+                        description: "A simple example",
+                        request: {
+                            method: "GET",
+                            path: "/test",
+                            headers: { Authorization: "Bearer token" },
+                        },
+                        response: { data: "test" },
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithExamples, "detailed");
+            expect(result).toContain("## Examples");
+            expect(result).toContain("### Basic Example");
+            expect(result).toContain("**Request:**");
+            expect(result).toContain("GET /test");
+            expect(result).toContain("Authorization: Bearer token");
+            expect(result).toContain("**Response:**");
+        });
+        it("should format examples with request body", () => {
+            const docWithBodyExample = {
+                ...minimalDoc,
+                examples: [
+                    {
+                        title: "Create Example",
+                        description: "Creating data",
+                        request: {
+                            method: "POST",
+                            path: "/test",
+                            body: { name: "test", value: 42 },
+                        },
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithBodyExample, "detailed");
+            expect(result).toContain('"name": "test"');
+            expect(result).toContain('"value": 42');
+        });
+        it("should format patterns/workflows", () => {
+            const docWithPatterns = {
+                ...minimalDoc,
+                patterns: [
+                    {
+                        name: "Basic Workflow",
+                        description: "A simple workflow",
+                        steps: ["1. Do step 1", "2. Do step 2", "3. Do step 3"],
+                        example: "example code here",
+                    },
+                ],
+            };
+            const result = formatDocumentation(docWithPatterns);
+            expect(result).toContain("## Workflows");
+            expect(result).toContain("### Basic Workflow");
+            expect(result).toContain("A simple workflow");
+            expect(result).toContain("**Steps:**");
+            expect(result).toContain("1. Do step 1");
+            expect(result).toContain("**Example:**");
+            expect(result).toContain("example code here");
+        });
+        it("should include schemas when includeSchemas is true", () => {
+            const docWithSchemas = {
+                ...minimalDoc,
+                schemas: {
+                    TestSchema: {
+                        type: "object",
+                        properties: {
+                            id: { type: "integer" },
+                        },
+                    },
+                },
+            };
+            const result = formatDocumentation(docWithSchemas, "detailed", true);
+            expect(result).toContain("## Schemas");
+            expect(result).toContain('"TestSchema"');
+        });
+        it("should exclude schemas when includeSchemas is false", () => {
+            const docWithSchemas = {
+                ...minimalDoc,
+                schemas: {
+                    TestSchema: { type: "object" },
+                },
+            };
+            const result = formatDocumentation(docWithSchemas, "detailed", false);
+            expect(result).not.toContain("## Schemas");
+        });
+        it("should include related topics", () => {
+            const docWithRelated = {
+                ...minimalDoc,
+                related_topics: ["topic1", "topic2", "topic3"],
+            };
+            const result = formatDocumentation(docWithRelated);
+            expect(result).toContain("## Related Topics");
+            expect(result).toContain("topic1, topic2, topic3");
+            expect(result).toContain("meta_api_docs");
+        });
+        it("should use custom config", () => {
+            const result = formatDocumentation({ ...minimalDoc, patterns: [{ name: "Test", steps: ["step"] }] }, "detailed", true, RUN_API_CONFIG);
+            expect(result).toContain("https://app.dev.xano.com/api:run/");
+        });
+        describe("detail levels", () => {
+            const docWithAll = {
+                ...minimalDoc,
+                endpoints: [
+                    {
+                        method: "GET",
+                        path: "/test",
+                        description: "Test endpoint",
+                        parameters: [
+                            { name: "id", type: "integer", required: true, description: "ID" },
+                        ],
+                        example: {
+                            method: "GET",
+                            path: "/test/1",
+                        },
+                    },
+                ],
+                examples: [
+                    {
+                        title: "Example",
+                        description: "Test",
+                        request: { method: "GET", path: "/test" },
+                    },
+                ],
+            };
+            it("overview should show minimal endpoint info", () => {
+                const result = formatDocumentation(docWithAll, "overview");
+                expect(result).toContain("### GET /test");
+                expect(result).toContain("Test endpoint");
+                expect(result).not.toContain("**Parameters:**");
+            });
+            it("detailed should show parameters but not inline examples", () => {
+                const result = formatDocumentation(docWithAll, "detailed");
+                expect(result).toContain("**Parameters:**");
+                expect(result).toContain("## Examples");
+            });
+            it("examples should show inline examples in endpoints", () => {
+                const result = formatDocumentation(docWithAll, "examples");
+                expect(result).toContain("**Example:**");
+                expect(result).toContain("GET /test/1");
+            });
+        });
+    });
+});

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

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

package/dist/meta_api_docs/index.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { topics, getTopicNames, getTopicDescriptions, handleMetaApiDocs, metaApiDocsToolDefinition, } from "./index.js";
+describe("meta_api_docs/index", () => {
+    describe("topics", () => {
+        it("should have all expected topics", () => {
+            const expectedTopics = [
+                "start",
+                "authentication",
+                "workspace",
+                "apigroup",
+                "api",
+                "table",
+                "function",
+                "task",
+                "agent",
+                "tool",
+                "mcp_server",
+                "middleware",
+                "branch",
+                "realtime",
+                "file",
+                "history",
+                "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("- workspace:");
+            expect(descriptions).toContain("- api:");
+        });
+        it("should include all topics", () => {
+            const descriptions = getTopicDescriptions();
+            for (const key of Object.keys(topics)) {
+                expect(descriptions).toContain(`- ${key}:`);
+            }
+        });
+    });
+    describe("handleMetaApiDocs", () => {
+        it("should return error for unknown topic", () => {
+            const result = handleMetaApiDocs({ topic: "nonexistent" });
+            expect(result).toContain('Error: Unknown topic "nonexistent"');
+            expect(result).toContain("Available topics:");
+        });
+        it("should return documentation for valid topic", () => {
+            const result = handleMetaApiDocs({ topic: "start" });
+            expect(result).toContain("Xano Meta API - Getting Started");
+            expect(result).not.toContain("Error:");
+        });
+        it("should use default detail_level of detailed", () => {
+            const result = handleMetaApiDocs({ topic: "start" });
+            expect(result).toContain("Examples");
+        });
+        it("should respect overview detail_level", () => {
+            const result = handleMetaApiDocs({
+                topic: "start",
+                detail_level: "overview",
+            });
+            expect(result).toContain("Xano Meta API");
+        });
+        it("should respect examples detail_level", () => {
+            const result = handleMetaApiDocs({
+                topic: "start",
+                detail_level: "examples",
+            });
+            expect(result).toContain("Examples");
+        });
+        it("should include schemas by default", () => {
+            const result = handleMetaApiDocs({ topic: "workspace" });
+            // Schemas may or may not be present depending on the topic
+            expect(typeof result).toBe("string");
+        });
+        it("should respect include_schemas=false", () => {
+            const result = handleMetaApiDocs({
+                topic: "workspace",
+                include_schemas: false,
+            });
+            expect(typeof result).toBe("string");
+        });
+    });
+    describe("metaApiDocsToolDefinition", () => {
+        it("should have required tool properties", () => {
+            expect(metaApiDocsToolDefinition).toHaveProperty("name", "meta_api_docs");
+            expect(metaApiDocsToolDefinition).toHaveProperty("description");
+            expect(metaApiDocsToolDefinition).toHaveProperty("inputSchema");
+        });
+        it("should have valid inputSchema", () => {
+            const schema = metaApiDocsToolDefinition.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 = metaApiDocsToolDefinition.inputSchema.properties.topic.enum;
+            expect(topicEnum).toEqual(getTopicNames());
+        });
+    });
+});

package/dist/meta_api_docs/types.test.d.ts

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

package/dist/meta_api_docs/types.test.js

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+describe("meta_api_docs/types", () => {
+    describe("type structures", () => {
+        it("should allow valid HttpMethod values", () => {
+            const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+            expect(methods).toHaveLength(5);
+        });
+        it("should allow valid ParameterDoc structure", () => {
+            const param = {
+                name: "id",
+                type: "integer",
+                required: true,
+                default: 1,
+                description: "The ID",
+                enum: ["a", "b"],
+                in: "path",
+            };
+            expect(param.name).toBe("id");
+            expect(param.in).toBe("path");
+        });
+        it("should allow minimal ParameterDoc", () => {
+            const param = {
+                name: "test",
+                type: "string",
+                description: "A test parameter",
+            };
+            expect(param.required).toBeUndefined();
+        });
+        it("should allow valid RequestBodyDoc structure", () => {
+            const body = {
+                type: "object",
+                description: "Request body",
+                properties: {
+                    name: { type: "string", required: true, description: "Name" },
+                },
+                example: { name: "test" },
+            };
+            expect(body.type).toBe("object");
+        });
+        it("should allow valid ResponseDoc structure", () => {
+            const response = {
+                type: "object",
+                description: "Response",
+                properties: { id: { type: "integer" } },
+            };
+            expect(response.type).toBe("object");
+        });
+        it("should allow valid RequestExampleDoc structure", () => {
+            const example = {
+                method: "POST",
+                path: "/test",
+                headers: { "Content-Type": "application/json" },
+                body: { data: "test" },
+            };
+            expect(example.method).toBe("POST");
+        });
+        it("should allow valid EndpointDoc structure", () => {
+            const endpoint = {
+                method: "GET",
+                path: "/test/{id}",
+                tool_name: "get_test",
+                description: "Get a test",
+                tags: ["test", "example"],
+                parameters: [
+                    { name: "id", type: "integer", description: "ID" },
+                ],
+                request_body: { type: "object" },
+                response: { type: "object" },
+                example: { method: "GET", path: "/test/1" },
+            };
+            expect(endpoint.method).toBe("GET");
+            expect(endpoint.tags).toContain("test");
+        });
+        it("should allow valid ExampleDoc structure", () => {
+            const example = {
+                title: "Example Title",
+                description: "Example description",
+                request: {
+                    method: "GET",
+                    path: "/test",
+                    headers: { Authorization: "Bearer token" },
+                    body: undefined,
+                },
+                response: { success: true },
+            };
+            expect(example.title).toBe("Example Title");
+        });
+        it("should allow valid PatternDoc structure", () => {
+            const pattern = {
+                name: "Workflow Name",
+                description: "Workflow description",
+                steps: ["Step 1", "Step 2"],
+                example: "example code",
+            };
+            expect(pattern.steps).toHaveLength(2);
+        });
+        it("should allow valid TopicDoc structure", () => {
+            const topic = {
+                topic: "test",
+                title: "Test Topic",
+                description: "Test description",
+                endpoints: [],
+                examples: [],
+                related_topics: ["other"],
+                schemas: { TestSchema: {} },
+                patterns: [],
+                ai_hints: "AI hints here",
+            };
+            expect(topic.topic).toBe("test");
+            expect(topic.ai_hints).toBeDefined();
+        });
+        it("should allow valid DetailLevel values", () => {
+            const levels = ["overview", "detailed", "examples"];
+            expect(levels).toHaveLength(3);
+        });
+        it("should allow valid MetaApiDocsArgs structure", () => {
+            const args = {
+                topic: "start",
+                detail_level: "detailed",
+                include_schemas: true,
+            };
+            expect(args.topic).toBe("start");
+        });
+        it("should allow minimal MetaApiDocsArgs", () => {
+            const args = {
+                topic: "start",
+            };
+            expect(args.detail_level).toBeUndefined();
+            expect(args.include_schemas).toBeUndefined();
+        });
+    });
+});

package/dist/run_api_docs/format.d.ts

@@ -1,5 +1,6 @@
 /**
  * Formatting utilities for Run API documentation output
+ * Re-exports the shared formatter with Run API configuration
  */
 import type { TopicDoc, DetailLevel } from "../meta_api_docs/types.js";
 export declare function formatDocumentation(doc: TopicDoc, detailLevel?: DetailLevel, includeSchemas?: boolean): string;