@xano/developer-mcp 1.0.41 → 1.0.42

package/dist/run_api_docs/format.test.js

@@ -1,86 +0,0 @@
-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.d.ts

@@ -1,52 +0,0 @@
-/**
- * Xano Run API Documentation Index
- *
- * This module exports all documentation topics and provides
- * the run_api_docs tool handler for the MCP server.
- */
-import type { TopicDoc } from "../meta_api_docs/types.js";
-/**
- * All available documentation topics
- */
-export declare const topics: Record<string, TopicDoc>;
-/**
- * Get list of all available topic names
- */
-export declare function getTopicNames(): string[];
-/**
- * Get topic descriptions for tool documentation
- */
-export declare function getTopicDescriptions(): string;
-/**
- * Handler for the run_api_docs tool
- */
-export declare function handleRunApiDocs(topic?: string, detailLevel?: string, includeSchemas?: boolean): string;
-/**
- * Tool definition for MCP server
- */
-export declare const runApiDocsToolDefinition: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            topic: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
-            detail_level: {
-                type: string;
-                enum: string[];
-                default: string;
-                description: string;
-            };
-            include_schemas: {
-                type: string;
-                default: boolean;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};

package/dist/run_api_docs/index.js

@@ -1,90 +0,0 @@
-/**
- * Xano Run API Documentation Index
- *
- * This module exports all documentation topics and provides
- * the run_api_docs tool handler for the MCP server.
- */
-import { formatDocumentation } from "./format.js";
-// Import all topic documentation
-import { startDoc } from "./topics/start.js";
-import { runDoc } from "./topics/run.js";
-import { sessionDoc } from "./topics/session.js";
-import { historyDoc } from "./topics/history.js";
-import { dataDoc } from "./topics/data.js";
-import { workflowsDoc } from "./topics/workflows.js";
-/**
- * All available documentation topics
- */
-export const topics = {
-    start: startDoc,
-    run: runDoc,
-    session: sessionDoc,
-    history: historyDoc,
-    data: dataDoc,
-    workflows: workflowsDoc,
-};
-/**
- * Get list of all available topic names
- */
-export function getTopicNames() {
-    return Object.keys(topics);
-}
-/**
- * Get topic descriptions for tool documentation
- */
-export function getTopicDescriptions() {
-    return Object.entries(topics)
-        .map(([key, doc]) => `- ${key}: ${doc.title}`)
-        .join("\n");
-}
-/**
- * Handler for the run_api_docs tool
- */
-export function handleRunApiDocs(topic, detailLevel, includeSchemas) {
-    // Validate topic
-    if (!topic || !topics[topic]) {
-        const available = getTopicNames().join(", ");
-        return `Error: Unknown topic "${topic}".\n\nAvailable topics: ${available}`;
-    }
-    const doc = topics[topic];
-    return formatDocumentation(doc, detailLevel || "detailed", includeSchemas !== false);
-}
-/**
- * Tool definition for MCP server
- */
-export const runApiDocsToolDefinition = {
-    name: "run_api_docs",
-    description: `Get documentation for Xano's Run API. Use this to understand runtime execution, session management, and XanoScript execution.
-
-**Important:** The Run API uses a fixed base URL: https://app.dev.xano.com/api:run/<endpoint> (NOT your Xano instance URL)
-
-## Topics
-${getTopicDescriptions()}
-
-## Usage
-- Start with "start" topic for overview and getting started
-- Use "workflows" for step-by-step guides
-- Use specific topics (run, session, etc.) for detailed endpoint docs`,
-    inputSchema: {
-        type: "object",
-        properties: {
-            topic: {
-                type: "string",
-                enum: getTopicNames(),
-                description: "Documentation topic to retrieve",
-            },
-            detail_level: {
-                type: "string",
-                enum: ["overview", "detailed", "examples"],
-                default: "detailed",
-                description: "Level of detail: overview (brief), detailed (full docs), examples (with code examples)",
-            },
-            include_schemas: {
-                type: "boolean",
-                default: true,
-                description: "Include JSON schemas for requests/responses",
-            },
-        },
-        required: ["topic"],
-    },
-};

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

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

package/dist/run_api_docs/index.test.js

@@ -1,127 +0,0 @@
-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/run_api_docs/topics/data.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const dataDoc: TopicDoc;

package/dist/run_api_docs/topics/data.js

@@ -1,104 +0,0 @@
-export const dataDoc = {
-    topic: "data",
-    title: "Session Data Export",
-    description: `The sink endpoint provides complete data export from session backups. This is the "kitchen sink" - everything from a session's database state in a single JSON response.
-
-## Prerequisites
-- Session must have been hibernated at least once (backup must exist)
-- Hibernation creates a complete snapshot of all tables and data
-
-## Use Cases
-- Export complete session state for analysis
-- Backup data before session termination
-- Transfer data between sessions
-- Debugging and auditing
-
-## Data Included
-- All table schemas
-- All table data/records
-- Complete as single JSON object`,
-    ai_hints: `- Session must be hibernated before sink is available
-- Hibernation happens automatically after project timeout or manually
-- Large datasets may take time to export - be patient
-- Use for complete data snapshots, not real-time queries
-- Data is read-only - cannot modify via sink endpoint
-- Public sessions can export without authentication`,
-    endpoints: [
-        {
-            method: "GET",
-            path: "/session/{session_id}/sink",
-            tool_name: "getSessionSink",
-            description: "Get full backup data from a session as JSON. Returns the complete 'kitchen sink' - all table schemas and data in one response. Session must have been hibernated at least once.",
-            parameters: [
-                { name: "session_id", type: "uuid", required: true, in: "path", description: "Session UUID" }
-            ],
-            example: {
-                method: "GET",
-                path: "/session/session-uuid-here/sink"
-            }
-        }
-    ],
-    schemas: {
-        SinkResponse: {
-            type: "object",
-            properties: {
-                tables: {
-                    type: "object",
-                    description: "Map of table names to their data",
-                    additionalProperties: {
-                        type: "object",
-                        properties: {
-                            schema: { type: "array", description: "Field definitions" },
-                            records: { type: "array", description: "All records in the table" }
-                        }
-                    }
-                },
-                metadata: {
-                    type: "object",
-                    properties: {
-                        session_id: { type: "uuid", description: "Source session" },
-                        exported_at: { type: "timestamp", description: "Export timestamp" },
-                        size: { type: "integer", description: "Backup size in bytes" }
-                    }
-                }
-            }
-        }
-    },
-    examples: [
-        {
-            title: "Export session data",
-            description: "Get all data from a hibernated session",
-            request: {
-                method: "GET",
-                path: "/session/abc123-session-uuid/sink",
-                headers: { "Authorization": "Bearer <token>" }
-            },
-            response: {
-                tables: {
-                    users: {
-                        schema: [
-                            { name: "id", type: "int" },
-                            { name: "email", type: "text" },
-                            { name: "name", type: "text" }
-                        ],
-                        records: [
-                            { id: 1, email: "alice@example.com", name: "Alice" },
-                            { id: 2, email: "bob@example.com", name: "Bob" }
-                        ]
-                    },
-                    orders: {
-                        schema: [
-                            { name: "id", type: "int" },
-                            { name: "user_id", type: "int" },
-                            { name: "total", type: "decimal" }
-                        ],
-                        records: [
-                            { id: 1, user_id: 1, total: 99.99 }
-                        ]
-                    }
-                }
-            }
-        }
-    ],
-    related_topics: ["session", "workflows"]
-};

package/dist/run_api_docs/topics/history.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const historyDoc: TopicDoc;

package/dist/run_api_docs/topics/history.js

@@ -1,93 +0,0 @@
-export const historyDoc = {
-    topic: "history",
-    title: "Run History & Document Analysis",
-    description: `Endpoints for viewing run execution history and analyzing XanoScript documents before execution.
-
-## Use Cases
-- **Run History**: Review past executions, track patterns, audit usage
-- **Document Analysis**: Validate scripts, understand structure before execution
-
-## History Features
-- Paginated access to run history
-- Sorted by creation time (newest first)
-- Includes run metadata and configuration`,
-    ai_hints: `- Use doc/info to validate scripts before execution
-- History is sorted by created_at descending (newest first)
-- Check existing runs before creating duplicates with same script
-- Use pagination for large history sets (default 20 per page, max 100)
-- Document info reveals functions, services, and jobs defined in a script`,
-    endpoints: [
-        {
-            method: "GET",
-            path: "/project/{project_id}/run",
-            tool_name: "getRunHistory",
-            description: "List run execution history for a project with pagination. Returns runs sorted by creation time (newest first).",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project UUID" },
-                { name: "page", type: "integer", default: 1, description: "Page number (min: 1)" },
-                { name: "per_page", type: "integer", default: 20, description: "Items per page (1-100)" }
-            ],
-            example: {
-                method: "GET",
-                path: "/project/abc123-uuid/run?page=1&per_page=20"
-            }
-        },
-        {
-            method: "POST",
-            path: "/project/{project_id}/doc/info",
-            tool_name: "getDocInfo",
-            description: "Parse and analyze a XanoScript document. Returns metadata about the document including defined functions, services, and jobs. Use this to validate scripts before execution.",
-            parameters: [
-                { name: "project_id", type: "uuid", required: true, in: "path", description: "Project context" }
-            ],
-            request_body: {
-                type: "application/json",
-                properties: {
-                    doc: { type: "text", required: true, description: "XanoScript document content to analyze" }
-                }
-            },
-            example: {
-                method: "POST",
-                path: "/project/abc123-uuid/doc/info",
-                body: {
-                    doc: "job my_job {\n  input { text name }\n  response = \"Hello, \" + $input.name\n}\n\nservice my_service {\n  // service code\n}"
-                }
-            }
-        }
-    ],
-    schemas: {
-        RunHistoryItem: {
-            type: "object",
-            properties: {
-                id: { type: "uuid", description: "Run identifier" },
-                name: { type: "text", description: "Run name" },
-                type: { type: "enum", enum: ["job", "service"], description: "Run type" },
-                sig: { type: "text", description: "Document signature" },
-                project_id: { type: "uuid", description: "Project reference" },
-                user_id: { type: "integer", description: "Owner user ID" },
-                created_at: { type: "timestamp", description: "Creation time" },
-                updated_at: { type: "timestamp", description: "Last update time" }
-            }
-        },
-        DocInfo: {
-            type: "object",
-            properties: {
-                functions: { type: "array", description: "Defined functions" },
-                services: { type: "array", description: "Defined services" },
-                jobs: { type: "array", description: "Defined jobs" },
-                valid: { type: "boolean", description: "Whether document is valid" },
-                errors: { type: "array", description: "Parsing errors if any" }
-            }
-        },
-        PaginatedResponse: {
-            type: "object",
-            properties: {
-                items: { type: "array", description: "List of runs" },
-                curPage: { type: "integer", description: "Current page number" },
-                nextPage: { type: "integer", description: "Next page number or null" },
-                prevPage: { type: "integer", description: "Previous page number or null" }
-            }
-        }
-    },
-    related_topics: ["run", "session", "workflows"]
-};

package/dist/run_api_docs/topics/run.d.ts

@@ -1,2 +0,0 @@
-import type { TopicDoc } from "../../meta_api_docs/types.js";
-export declare const runDoc: TopicDoc;