@xano/developer-mcp 1.0.54 → 1.0.57

package/dist/tools/index.test.js

@@ -0,0 +1,179 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+import { handleTool, toMcpResponse, toolDefinitions, } from "./index.js";
+import { setXanoscriptDocsPath } from "./xanoscript_docs.js";
+import { XANOSCRIPT_DOCS_V2 } from "../xanoscript.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DOCS_PATH = join(__dirname, "..", "xanoscript_docs");
+beforeAll(() => {
+    setXanoscriptDocsPath(DOCS_PATH);
+});
+describe("handleTool", () => {
+    it("should handle xanoscript_docs tool", () => {
+        const result = handleTool("xanoscript_docs", {});
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+    });
+    it("should handle xanoscript_docs with topic arg", () => {
+        const result = handleTool("xanoscript_docs", { topic: "syntax" });
+        expect(result.success).toBe(true);
+        expect(typeof result.data).toBe("string");
+        expect(result.data).toContain("Documentation version:");
+    });
+    it("should handle xanoscript_docs with file_path and return multi-content", () => {
+        const result = handleTool("xanoscript_docs", { file_path: "apis/users/create.xs" });
+        expect(result.success).toBe(true);
+        expect(Array.isArray(result.data)).toBe(true);
+        const data = result.data;
+        expect(data.length).toBeGreaterThan(1);
+        expect(data[0]).toContain("Matched topics:");
+    });
+    it("should handle validate_xanoscript tool and return a ToolResult", () => {
+        const result = handleTool("validate_xanoscript", { code: "var $x:int = 1" });
+        expect(result).toHaveProperty("success");
+        expect(typeof result.success).toBe("boolean");
+        // Either data or error should be present
+        expect(result.data ?? result.error).toBeDefined();
+    });
+    it("should handle validate_xanoscript with missing input", () => {
+        const result = handleTool("validate_xanoscript", {});
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+    it("should handle mcp_version tool", () => {
+        const result = handleTool("mcp_version", {});
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+    });
+    it("should handle meta_api_docs tool with topic", () => {
+        const result = handleTool("meta_api_docs", { topic: "start" });
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+    });
+    it("should handle meta_api_docs tool without topic", () => {
+        const result = handleTool("meta_api_docs", {});
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("topic");
+    });
+    it("should handle cli_docs tool with topic", () => {
+        const result = handleTool("cli_docs", { topic: "start" });
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+    });
+    it("should handle cli_docs tool without topic", () => {
+        const result = handleTool("cli_docs", {});
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("topic");
+    });
+    it("should return error for unknown tool", () => {
+        const result = handleTool("nonexistent_tool", {});
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Unknown tool: nonexistent_tool");
+    });
+    it("should return validation error for wrong argument types", () => {
+        const result = handleTool("xanoscript_docs", { mode: 123 });
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Invalid arguments");
+    });
+    it("should return validation error for invalid enum value", () => {
+        const result = handleTool("xanoscript_docs", { mode: "invalid_mode" });
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Invalid arguments");
+    });
+    it("should return validation error when meta_api_docs topic is wrong type", () => {
+        const result = handleTool("meta_api_docs", { topic: 123 });
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Invalid arguments");
+    });
+});
+describe("toMcpResponse", () => {
+    it("should convert success result to MCP response", () => {
+        const response = toMcpResponse({ success: true, data: "test data" });
+        expect(response.content).toHaveLength(1);
+        expect(response.content[0].type).toBe("text");
+        expect(response.content[0].text).toBe("test data");
+        expect(response.isError).toBeUndefined();
+    });
+    it("should convert error result to MCP response with isError", () => {
+        const response = toMcpResponse({ success: false, error: "test error" });
+        expect(response.content).toHaveLength(1);
+        expect(response.content[0].text).toBe("test error");
+        expect(response.isError).toBe(true);
+    });
+    it("should convert string array data to multiple content blocks", () => {
+        const response = toMcpResponse({
+            success: true,
+            data: ["block one", "block two", "block three"],
+        });
+        expect(response.content).toHaveLength(3);
+        expect(response.content[0]).toEqual({ type: "text", text: "block one" });
+        expect(response.content[1]).toEqual({ type: "text", text: "block two" });
+        expect(response.content[2]).toEqual({ type: "text", text: "block three" });
+        expect(response.isError).toBeUndefined();
+    });
+    it("should handle single-element array data", () => {
+        const response = toMcpResponse({ success: true, data: ["only block"] });
+        expect(response.content).toHaveLength(1);
+        expect(response.content[0].text).toBe("only block");
+    });
+    it("should include structuredContent when provided", () => {
+        const response = toMcpResponse({
+            success: true,
+            data: "test",
+            structuredContent: { version: "1.0.0" },
+        });
+        expect(response.structuredContent).toEqual({ version: "1.0.0" });
+        expect(response.isError).toBeUndefined();
+    });
+    it("should omit structuredContent when not provided", () => {
+        const response = toMcpResponse({ success: true, data: "test" });
+        expect(response.structuredContent).toBeUndefined();
+    });
+    it("should not include structuredContent on error", () => {
+        const response = toMcpResponse({ success: false, error: "fail" });
+        expect(response.structuredContent).toBeUndefined();
+        expect(response.isError).toBe(true);
+    });
+});
+describe("toolDefinitions", () => {
+    it("should contain all 5 tools", () => {
+        expect(toolDefinitions).toHaveLength(5);
+    });
+    it("should have unique tool names", () => {
+        const names = toolDefinitions.map((t) => t.name);
+        expect(new Set(names).size).toBe(names.length);
+    });
+    it("should include expected tool names", () => {
+        const names = toolDefinitions.map((t) => t.name);
+        expect(names).toContain("validate_xanoscript");
+        expect(names).toContain("xanoscript_docs");
+        expect(names).toContain("mcp_version");
+        expect(names).toContain("meta_api_docs");
+        expect(names).toContain("cli_docs");
+    });
+    it("should have annotations on all tools", () => {
+        for (const tool of toolDefinitions) {
+            expect(tool).toHaveProperty("annotations");
+            expect(tool.annotations).toHaveProperty("readOnlyHint");
+            expect(tool.annotations).toHaveProperty("destructiveHint", false);
+        }
+    });
+    it("should have outputSchema on all tools", () => {
+        for (const tool of toolDefinitions) {
+            expect(tool).toHaveProperty("outputSchema");
+            expect(tool.outputSchema).toHaveProperty("type", "object");
+            expect(tool.outputSchema).toHaveProperty("properties");
+        }
+    });
+});
+describe("integration: all topic files exist on disk", () => {
+    for (const [topic, config] of Object.entries(XANOSCRIPT_DOCS_V2)) {
+        it(`topic "${topic}" -> file "${config.file}" should exist`, () => {
+            const filePath = join(DOCS_PATH, config.file);
+            expect(existsSync(filePath)).toBe(true);
+        });
+    }
+});

package/dist/tools/mcp_version.d.ts

@@ -48,4 +48,14 @@ export declare const mcpVersionToolDefinition: {
         properties: {};
         required: never[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            version: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 };

package/dist/tools/mcp_version.js

@@ -74,9 +74,11 @@ export function mcpVersion() {
  * Get the MCP version and return a ToolResult.
  */
 export function mcpVersionTool() {
+    const version = getServerVersion();
     return {
         success: true,
-        data: getServerVersion(),
+        data: version,
+        structuredContent: { version },
     };
 }
 // =============================================================================
@@ -97,4 +99,14 @@ export const mcpVersionToolDefinition = {
         properties: {},
         required: [],
     },
+    outputSchema: {
+        type: "object",
+        properties: {
+            version: {
+                type: "string",
+                description: "The semantic version string of the MCP server.",
+            },
+        },
+        required: ["version"],
+    },
 };

package/dist/tools/meta_api_docs.js

@@ -55,6 +55,7 @@ export function metaApiDocsTool(args) {
         return {
             success: true,
             data: result.documentation,
+            structuredContent: { documentation: result.documentation },
         };
     }
     catch (error) {

package/dist/tools/types.d.ts

@@ -1,18 +1,27 @@
 /**
  * Common types for tool results
  */
-export interface ToolResult {
-    success: boolean;
-    data?: string;
-    error?: string;
-}
+export type ToolResult = {
+    success: true;
+    data: string | string[];
+    structuredContent?: Record<string, unknown>;
+    error?: undefined;
+} | {
+    success: false;
+    error: string;
+    data?: undefined;
+    structuredContent?: undefined;
+};
 /**
- * Convert a ToolResult to MCP tool response format
+ * Convert a ToolResult to MCP tool response format.
+ * When data is a string[], each element becomes a separate content block.
+ * When structuredContent is provided, it's included for clients that support outputSchema.
  */
 export declare function toMcpResponse(result: ToolResult): {
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 };

package/dist/tools/types.js

@@ -2,13 +2,19 @@
  * Common types for tool results
  */
 /**
- * Convert a ToolResult to MCP tool response format
+ * Convert a ToolResult to MCP tool response format.
+ * When data is a string[], each element becomes a separate content block.
+ * When structuredContent is provided, it's included for clients that support outputSchema.
  */
 export function toMcpResponse(result) {
     if (result.success) {
-        return {
-            content: [{ type: "text", text: result.data }],
-        };
+        const content = Array.isArray(result.data)
+            ? result.data.map((text) => ({ type: "text", text }))
+            : [{ type: "text", text: result.data }];
+        if (result.structuredContent) {
+            return { content, structuredContent: result.structuredContent };
+        }
+        return { content };
     }
     return {
         content: [{ type: "text", text: result.error }],

package/dist/tools/validate_xanoscript.d.ts

@@ -145,5 +145,19 @@ export declare const validateXanoscriptToolDefinition: {
         };
         required: never[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            valid: {
+                type: string;
+                description: string;
+            };
+            message: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
 };
 export { TYPE_ALIASES, RESERVED_VARIABLES };

package/dist/tools/validate_xanoscript.js

@@ -377,11 +377,14 @@ export function validateXanoscript(args) {
  */
 export function validateXanoscriptTool(args) {
     const result = validateXanoscript(args);
-    return {
-        success: result.valid,
-        data: result.valid ? result.message : undefined,
-        error: result.valid ? undefined : result.message,
-    };
+    if (result.valid) {
+        return {
+            success: true,
+            data: result.message,
+            structuredContent: { valid: true, message: result.message },
+        };
+    }
+    return { success: false, error: result.message };
 }
 // =============================================================================
 // MCP Tool Definition
@@ -433,6 +436,20 @@ export const validateXanoscriptToolDefinition = {
         },
         required: [],
     },
+    outputSchema: {
+        type: "object",
+        properties: {
+            valid: {
+                type: "boolean",
+                description: "Whether the code passed validation without errors.",
+            },
+            message: {
+                type: "string",
+                description: "Human-readable validation summary with error details if any.",
+            },
+        },
+        required: ["valid", "message"],
+    },
 };
 // =============================================================================
 // Utility Exports

package/dist/tools/xanoscript_docs.d.ts

@@ -4,11 +4,13 @@
  * Retrieves XanoScript programming language documentation.
  * Can be used standalone or within the MCP server.
  */
-import { type XanoscriptDocsArgs } from "../xanoscript.js";
+import { type XanoscriptDocsArgs, type TopicDoc } from "../xanoscript.js";
 import type { ToolResult } from "./types.js";
 export type { XanoscriptDocsArgs };
+export type { TopicDoc };
 export interface XanoscriptDocsResult {
     documentation: string;
+    topics?: TopicDoc[];
 }
 /**
  * Get the path to XanoScript documentation files.
@@ -45,6 +47,7 @@ export declare function setXanoscriptDocsPath(path: string): void;
 export declare function xanoscriptDocs(args?: XanoscriptDocsArgs): XanoscriptDocsResult;
 /**
  * Get XanoScript documentation and return a ToolResult.
+ * For file_path mode, returns each topic as a separate content block.
  */
 export declare function xanoscriptDocsTool(args?: XanoscriptDocsArgs): ToolResult;
 export declare const xanoscriptDocsToolDefinition: {
@@ -83,4 +86,32 @@ export declare const xanoscriptDocsToolDefinition: {
         };
         required: never[];
     };
+    outputSchema: {
+        type: string;
+        properties: {
+            documentation: {
+                type: string;
+                description: string;
+            };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                description: string;
+            };
+            version: {
+                type: string;
+                description: string;
+            };
+            topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+    };
 };

package/dist/tools/xanoscript_docs.js

@@ -7,7 +7,7 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { readXanoscriptDocsV2, getTopicNames, getTopicDescriptions, } from "../xanoscript.js";
+import { readXanoscriptDocsV2, readXanoscriptDocsStructured, getXanoscriptDocsVersion, getTopicNames, getTopicDescriptions, } from "../xanoscript.js";
 // =============================================================================
 // Path Resolution
 // =============================================================================
@@ -75,17 +75,53 @@ export function setXanoscriptDocsPath(path) {
 export function xanoscriptDocs(args) {
     const docsPath = getXanoscriptDocsPath();
     const documentation = readXanoscriptDocsV2(docsPath, args);
+    // For file_path mode, also provide structured per-topic access
+    if (args?.file_path) {
+        const topics = readXanoscriptDocsStructured(docsPath, {
+            ...args,
+            file_path: args.file_path,
+        });
+        return { documentation, topics };
+    }
     return { documentation };
 }
 /**
  * Get XanoScript documentation and return a ToolResult.
+ * For file_path mode, returns each topic as a separate content block.
  */
 export function xanoscriptDocsTool(args) {
     try {
+        const docsPath = getXanoscriptDocsPath();
+        // file_path mode: return structured multi-content (one block per topic)
+        if (args?.file_path) {
+            const version = getXanoscriptDocsVersion(docsPath);
+            const topicDocs = readXanoscriptDocsStructured(docsPath, {
+                ...args,
+                file_path: args.file_path,
+            });
+            const mode = args.mode || "quick_reference";
+            const topics = topicDocs.map((d) => d.topic);
+            const header = `XanoScript Documentation for: ${args.file_path}\n` +
+                `Matched topics: ${topics.join(", ")}\n` +
+                `Mode: ${mode}\n` +
+                `Version: ${version}`;
+            return {
+                success: true,
+                data: [header, ...topicDocs.map((d) => d.content)],
+                structuredContent: {
+                    file_path: args.file_path,
+                    mode,
+                    version,
+                    topics,
+                },
+            };
+        }
+        // All other modes: return single content block
         const result = xanoscriptDocs(args);
         return {
             success: true,
             data: result.documentation,
+            structuredContent: { documentation: result.documentation },
         };
     }
     catch (error) {
@@ -104,7 +140,7 @@ export const xanoscriptDocsToolDefinition = {
     description: "Get XanoScript programming language documentation for AI code generation. " +
         "Call without parameters for overview (README). " +
         "Use 'topic' for specific documentation, or 'file_path' for context-aware docs based on the file you're editing. " +
-        "Use mode='quick_reference' for compact syntax cheatsheet (recommended for context efficiency). " +
+        "Use mode='quick_reference' for compact syntax reference (recommended for context efficiency). " +
         "file_path mode defaults to 'quick_reference' to reduce context size; use mode='full' to get complete docs.",
     annotations: {
         readOnlyHint: true,
@@ -131,9 +167,11 @@ export const xanoscriptDocsToolDefinition = {
             },
             mode: {
                 type: "string",
-                enum: ["full", "quick_reference"],
+                enum: ["full", "quick_reference", "index"],
                 description: "'full' = complete documentation with explanations and examples. " +
-                    "'quick_reference' = compact cheatsheet with just syntax patterns and signatures. " +
+                    "'quick_reference' = compact reference with just syntax patterns and signatures. " +
+                    "'index' = compact topic listing with descriptions and byte sizes (~1KB). " +
+                    "Use 'index' to discover available topics before loading them. " +
                     "Use 'quick_reference' to save context window space when you just need a reminder. " +
                     "Default: 'full' for topic mode, 'quick_reference' for file_path mode.",
             },
@@ -141,10 +179,36 @@ export const xanoscriptDocsToolDefinition = {
                 type: "array",
                 items: { type: "string" },
                 description: "List of topic names to exclude from file_path results. " +
-                    "Use this to skip topics you've already loaded (e.g., exclude_topics: ['syntax', 'quickstart']). " +
+                    "Use this to skip topics you've already loaded (e.g., exclude_topics: ['syntax', 'essentials']). " +
                     "Only applies when using file_path parameter.",
             },
         },
         required: [],
     },
+    outputSchema: {
+        type: "object",
+        properties: {
+            documentation: {
+                type: "string",
+                description: "The documentation content (topic or README mode).",
+            },
+            file_path: {
+                type: "string",
+                description: "The file path that was matched (file_path mode only).",
+            },
+            mode: {
+                type: "string",
+                description: "The documentation mode used.",
+            },
+            version: {
+                type: "string",
+                description: "The XanoScript documentation version.",
+            },
+            topics: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of matched topic names (file_path mode only).",
+            },
+        },
+    },
 };

package/dist/tools/xanoscript_docs.test.d.ts

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