@xano/developer-mcp 1.0.30 → 1.0.32

package/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-An MCP server that gives AI assistants superpowers for developing on [Xano](https://xano.com) — complete with documentation, code validation, and workflow guides.
+An MCP server and standalone library that gives AI assistants superpowers for developing on [Xano](https://xano.com) — complete with documentation, code validation, and workflow guides. Use it as an MCP server or import the tools directly in your own applications.
 
 > 💡 **What's Xano?** The fastest way to build a scalable backend for your app — no code required. Build APIs, manage databases, and deploy instantly.
 
@@ -145,6 +145,159 @@ claude mcp add xano-developer node /path/to/xano-developer-mcp/dist/index.js
 }
 ```
 
+## Library Usage
+
+In addition to using this package as an MCP server, you can import and use the tools directly in your own applications.
+
+### Installation
+
+```bash
+npm install @xano/developer-mcp
+```
+
+### Importing Tools
+
+```typescript
+import {
+  validateXanoscript,
+  xanoscriptDocs,
+  metaApiDocs,
+  runApiDocs,
+  cliDocs,
+  mcpVersion
+} from '@xano/developer-mcp';
+```
+
+### Validate XanoScript Code
+
+```typescript
+import { validateXanoscript } from '@xano/developer-mcp';
+
+const result = validateXanoscript({ code: 'var:result = 1 + 2' });
+
+if (result.valid) {
+  console.log('Code is valid!');
+} else {
+  console.log('Validation errors:');
+  result.errors.forEach(error => {
+    console.log(`  Line ${error.range.start.line + 1}: ${error.message}`);
+  });
+}
+```
+
+### Get XanoScript Documentation
+
+```typescript
+import { xanoscriptDocs } from '@xano/developer-mcp';
+
+// Get overview (README)
+const overview = xanoscriptDocs();
+console.log(overview.documentation);
+
+// Get specific topic
+const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });
+
+// Get context-aware docs for a file path
+const apiDocs = xanoscriptDocs({ file_path: 'apis/users/create.xs' });
+
+// Get compact quick reference
+const quickRef = xanoscriptDocs({ topic: 'database', mode: 'quick_reference' });
+```
+
+### Get Meta API Documentation
+
+```typescript
+import { metaApiDocs } from '@xano/developer-mcp';
+
+// Get overview
+const overview = metaApiDocs({ topic: 'start' });
+
+// Get detailed documentation with examples
+const workspaceDocs = metaApiDocs({
+  topic: 'workspace',
+  detail_level: 'examples',
+  include_schemas: true
+});
+
+console.log(workspaceDocs.documentation);
+```
+
+### Get Run API Documentation
+
+```typescript
+import { runApiDocs } from '@xano/developer-mcp';
+
+const sessionDocs = runApiDocs({
+  topic: 'session',
+  detail_level: 'detailed'
+});
+
+console.log(sessionDocs.documentation);
+```
+
+### Get CLI Documentation
+
+```typescript
+import { cliDocs } from '@xano/developer-mcp';
+
+const cliSetup = cliDocs({ topic: 'start' });
+console.log(cliSetup.documentation);
+```
+
+### Get Package Version
+
+```typescript
+import { mcpVersion } from '@xano/developer-mcp';
+
+const { version } = mcpVersion();
+console.log(`Using version ${version}`);
+```
+
+### Available Exports
+
+| Export | Description |
+|--------|-------------|
+| `validateXanoscript` | Validate XanoScript code and get detailed error information |
+| `xanoscriptDocs` | Get XanoScript language documentation |
+| `metaApiDocs` | Get Meta API documentation |
+| `runApiDocs` | Get Run API documentation |
+| `cliDocs` | Get CLI documentation |
+| `mcpVersion` | Get the package version |
+| `toolDefinitions` | MCP tool definitions (for building custom MCP servers) |
+| `handleTool` | Tool dispatcher function (for building custom MCP servers) |
+
+### TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  ValidateXanoscriptArgs,
+  ValidationResult,
+  ParserDiagnostic,
+  XanoscriptDocsArgs,
+  MetaApiDocsArgs,
+  RunApiDocsArgs,
+  CliDocsArgs,
+  ToolResult
+} from '@xano/developer-mcp';
+```
+
+### Package Entry Points
+
+The package provides multiple entry points:
+
+```typescript
+// Main library entry (recommended)
+import { validateXanoscript } from '@xano/developer-mcp';
+
+// Tools module directly
+import { validateXanoscript } from '@xano/developer-mcp/tools';
+
+// Server module (for extending the MCP server)
+import '@xano/developer-mcp/server';
+```
+
 ## Available Tools
 
 ### 1. `validate_xanoscript`
@@ -407,12 +560,22 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 ```
 xano-developer-mcp/
 ├── src/
-│   ├── index.ts                        # Main MCP server implementation
+│   ├── index.ts                        # MCP server entry point
+│   ├── lib.ts                          # Library entry point (for npm imports)
 │   ├── xanoscript.ts                   # XanoScript documentation logic
 │   ├── xanoscript.test.ts              # Tests for xanoscript module
 │   ├── xanoscript-language-server.d.ts # TypeScript declarations
+│   ├── tools/                          # Standalone tool modules
+│   │   ├── index.ts                    # Unified tool exports
+│   │   ├── types.ts                    # Common types (ToolResult)
+│   │   ├── validate_xanoscript.ts      # XanoScript validation tool
+│   │   ├── xanoscript_docs.ts          # XanoScript docs tool
+│   │   ├── mcp_version.ts              # Version tool
+│   │   ├── meta_api_docs.ts            # Meta API docs tool wrapper
+│   │   ├── run_api_docs.ts             # Run API docs tool wrapper
+│   │   └── cli_docs.ts                 # CLI docs tool wrapper
 │   ├── meta_api_docs/                  # Meta API documentation
-│   │   ├── index.ts                    # API docs tool handler
+│   │   ├── index.ts                    # API docs handler
 │   │   ├── index.test.ts               # Tests for index
 │   │   ├── types.ts                    # Type definitions
 │   │   ├── types.test.ts               # Tests for types
@@ -420,13 +583,13 @@ xano-developer-mcp/
 │   │   ├── format.test.ts              # Tests for formatter
 │   │   └── topics/                     # Individual topic modules
 │   ├── run_api_docs/                   # Run API documentation
-│   │   ├── index.ts                    # Run API tool handler
+│   │   ├── index.ts                    # Run API handler
 │   │   ├── index.test.ts               # Tests for index
 │   │   ├── format.ts                   # Documentation formatter
 │   │   ├── format.test.ts              # Tests for formatter
 │   │   └── topics/                     # Individual topic modules
 │   ├── cli_docs/                       # Xano CLI documentation
-│   │   ├── index.ts                    # CLI docs tool handler
+│   │   ├── index.ts                    # CLI docs handler
 │   │   ├── types.ts                    # Type definitions
 │   │   ├── format.ts                   # Documentation formatter
 │   │   └── topics/                     # Individual topic modules
@@ -486,7 +649,7 @@ Xano Developer MCP Server
 
 ## Authentication
 
-The MCP server itself does not require authentication. However, when using the documented APIs to interact with actual Xano services, you will need appropriate Xano Headless API credentials.
+The MCP server and library functions do not require authentication. However, when using the documented APIs (Meta API, Run API) to interact with actual Xano services, you will need appropriate Xano API credentials. See the `meta_api_docs` and `run_api_docs` tools for authentication details.
 
 ## Development
 

package/dist/cli_docs/topics/integration.js

@@ -71,7 +71,7 @@ The CLI uses both APIs internally.`,
 **If CLI not installed:**
 - Recommend installation: \`npm install -g @xano/cli\`
 - Or use Meta API endpoints directly for equivalent functionality
-- The multidoc endpoint (\`/api:meta/beta/workspace/{id}/multidoc\`) provides pull/push functionality
+- The multidoc endpoint (\`/api:meta/workspace/{id}/multidoc\`) provides pull/push functionality
 
 **Token reuse (if CLI is installed):**
 The same access token works for both:

package/dist/index.d.ts

@@ -1,2 +1,10 @@
 #!/usr/bin/env node
+/**
+ * Xano Developer MCP Server
+ *
+ * This is the MCP server entry point. For library usage, import from the package root:
+ * ```ts
+ * import { validateXanoscript, xanoscriptDocs } from '@xano/developer-mcp';
+ * ```
+ */
 export {};

package/dist/index.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
+/**
+ * Xano Developer MCP Server
+ *
+ * This is the MCP server entry point. For library usage, import from the package root:
+ * ```ts
+ * import { validateXanoscript, xanoscriptDocs } from '@xano/developer-mcp';
+ * ```
+ */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser.js";
-import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
-import { metaApiDocsToolDefinition, handleMetaApiDocs } from "./meta_api_docs/index.js";
-import { runApiDocsToolDefinition, handleRunApiDocs } from "./run_api_docs/index.js";
-import { cliDocsToolDefinition, handleCliDocs } from "./cli_docs/index.js";
-import { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getXanoscriptDocsVersion, getTopicDescriptions, } from "./xanoscript.js";
+import { XANOSCRIPT_DOCS_V2, getXanoscriptDocsVersion } from "./xanoscript.js";
+import { toolDefinitions, handleTool, toMcpResponse, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -91,288 +95,12 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 // Tool Handlers
 // =============================================================================
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: "validate_xanoscript",
-                description: "Validate XanoScript code for syntax errors. Returns a list of errors with line/column positions, or confirms the code is valid. The language server auto-detects the object type from the code syntax.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        code: {
-                            type: "string",
-                            description: "The XanoScript code to validate",
-                        },
-                    },
-                    required: ["code"],
-                },
-            },
-            {
-                name: "xanoscript_docs",
-                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).",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        topic: {
-                            type: "string",
-                            description: "Documentation topic. Available: " + getTopicDescriptions(),
-                        },
-                        file_path: {
-                            type: "string",
-                            description: "File path being edited (e.g., 'apis/users/create.xs', 'functions/utils/format.xs'). " +
-                                "Returns all relevant docs based on file type using applyTo pattern matching.",
-                        },
-                        mode: {
-                            type: "string",
-                            enum: ["full", "quick_reference"],
-                            description: "full = complete documentation, quick_reference = compact Quick Reference sections only. " +
-                                "Use quick_reference for smaller context window usage.",
-                        },
-                    },
-                    required: [],
-                },
-            },
-            {
-                name: "mcp_version",
-                description: "Get the current version of the Xano Developer MCP server. " +
-                    "Returns the version string from package.json.",
-                inputSchema: {
-                    type: "object",
-                    properties: {},
-                    required: [],
-                },
-            },
-            metaApiDocsToolDefinition,
-            runApiDocsToolDefinition,
-            cliDocsToolDefinition,
-        ],
-    };
+    return { tools: toolDefinitions };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name === "validate_xanoscript") {
-        const args = request.params.arguments;
-        if (!args?.code) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: 'code' parameter is required",
-                    },
-                ],
-                isError: true,
-            };
-        }
-        try {
-            const text = args.code;
-            const scheme = getSchemeFromContent(text);
-            const parser = xanoscriptParser(text, scheme);
-            if (parser.errors.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "XanoScript is valid. No syntax errors found.",
-                        },
-                    ],
-                };
-            }
-            const diagnostics = parser.errors.map((error) => {
-                const startOffset = error.token?.startOffset ?? 0;
-                const endOffset = error.token?.endOffset ?? 5;
-                const lines = text.substring(0, startOffset).split("\n");
-                const line = lines.length - 1;
-                const character = lines[lines.length - 1].length;
-                const endLines = text.substring(0, endOffset + 1).split("\n");
-                const endLine = endLines.length - 1;
-                const endCharacter = endLines[endLines.length - 1].length;
-                return {
-                    range: {
-                        start: { line, character },
-                        end: { line: endLine, character: endCharacter },
-                    },
-                    message: error.message,
-                    source: error.name || "XanoScript Parser",
-                };
-            });
-            const errorMessages = diagnostics.map((d, i) => {
-                const location = `Line ${d.range.start.line + 1}, Column ${d.range.start.character + 1}`;
-                return `${i + 1}. [${location}] ${d.message}`;
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Found ${diagnostics.length} error(s):\n\n${errorMessages.join("\n")}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Validation error: ${errorMessage}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }
-    if (request.params.name === "xanoscript_docs") {
-        const args = request.params.arguments;
-        const documentation = readXanoscriptDocsV2(XANOSCRIPT_DOCS_PATH, args);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: documentation,
-                },
-            ],
-        };
-    }
-    if (request.params.name === "mcp_version") {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: SERVER_VERSION,
-                },
-            ],
-        };
-    }
-    if (request.params.name === "meta_api_docs") {
-        const args = request.params.arguments;
-        if (!args?.topic) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: 'topic' parameter is required. Use meta_api_docs with topic='start' for overview.",
-                    },
-                ],
-                isError: true,
-            };
-        }
-        try {
-            const documentation = handleMetaApiDocs({
-                topic: args.topic,
-                detail_level: args.detail_level,
-                include_schemas: args.include_schemas,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: documentation,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error retrieving API documentation: ${errorMessage}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }
-    if (request.params.name === "run_api_docs") {
-        const args = request.params.arguments;
-        if (!args?.topic) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: 'topic' parameter is required. Use run_api_docs with topic='start' for overview.",
-                    },
-                ],
-                isError: true,
-            };
-        }
-        try {
-            const documentation = handleRunApiDocs(args.topic, args.detail_level, args.include_schemas);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: documentation,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error retrieving Run API documentation: ${errorMessage}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }
-    if (request.params.name === "cli_docs") {
-        const args = request.params.arguments;
-        if (!args?.topic) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: 'topic' parameter is required. Use cli_docs with topic='start' for overview.",
-                    },
-                ],
-                isError: true,
-            };
-        }
-        try {
-            const documentation = handleCliDocs({
-                topic: args.topic,
-                detail_level: args.detail_level,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: documentation,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error retrieving CLI documentation: ${errorMessage}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Unknown tool: ${request.params.name}`,
-            },
-        ],
-        isError: true,
-    };
+    const { name, arguments: args } = request.params;
+    const result = handleTool(name, args || {});
+    return toMcpResponse(result);
 });
 // =============================================================================
 // Start Server

package/dist/lib.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @xano/developer-mcp Library Entry Point
+ *
+ * This module exports all tools for use as a standalone library.
+ * Use this when you want to use the Xano tools outside of the MCP context.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   validateXanoscript,
+ *   xanoscriptDocs,
+ *   metaApiDocs,
+ *   runApiDocs,
+ *   cliDocs,
+ *   mcpVersion
+ * } from '@xano/developer-mcp';
+ *
+ * // Validate XanoScript code
+ * const validation = validateXanoscript({ code: 'return 1 + 1' });
+ * if (validation.valid) {
+ *   console.log('Code is valid!');
+ * } else {
+ *   console.log('Errors:', validation.errors);
+ * }
+ *
+ * // Get XanoScript documentation
+ * const docs = xanoscriptDocs({ topic: 'syntax', mode: 'quick_reference' });
+ * console.log(docs.documentation);
+ *
+ * // Get Meta API documentation
+ * const apiDocs = metaApiDocs({ topic: 'workspace', detail_level: 'examples' });
+ * console.log(apiDocs.documentation);
+ *
+ * // Get CLI documentation
+ * const cliDocs = cliDocs({ topic: 'start' });
+ * console.log(cliDocs.documentation);
+ *
+ * // Get version
+ * const { version } = mcpVersion();
+ * console.log(`Version: ${version}`);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { validateXanoscript, type ValidateXanoscriptArgs, type ValidationResult, type ParserDiagnostic, } from "./tools/validate_xanoscript.js";
+export { xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, type XanoscriptDocsArgs, type XanoscriptDocsResult, } from "./tools/xanoscript_docs.js";
+export { mcpVersion, getServerVersion, setServerVersion, type McpVersionResult, } from "./tools/mcp_version.js";
+export { metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, type MetaApiDocsArgs, type MetaApiDocsResult, } from "./tools/meta_api_docs.js";
+export { runApiDocs, runApiTopics, getRunApiTopicNames, getRunApiTopicDescriptions, type RunApiDocsArgs, type RunApiDocsResult, } from "./tools/run_api_docs.js";
+export { cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, type CliDocsArgs, type CliDocsResult, } from "./tools/cli_docs.js";
+export { type ToolResult, toMcpResponse } from "./tools/types.js";
+export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, type DocConfig, } from "./xanoscript.js";
+export { toolDefinitions, handleTool, validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVersionToolDefinition, metaApiDocsToolDefinition, runApiDocsToolDefinition, cliDocsToolDefinition, } from "./tools/index.js";

package/dist/lib.js

@@ -0,0 +1,71 @@
+/**
+ * @xano/developer-mcp Library Entry Point
+ *
+ * This module exports all tools for use as a standalone library.
+ * Use this when you want to use the Xano tools outside of the MCP context.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   validateXanoscript,
+ *   xanoscriptDocs,
+ *   metaApiDocs,
+ *   runApiDocs,
+ *   cliDocs,
+ *   mcpVersion
+ * } from '@xano/developer-mcp';
+ *
+ * // Validate XanoScript code
+ * const validation = validateXanoscript({ code: 'return 1 + 1' });
+ * if (validation.valid) {
+ *   console.log('Code is valid!');
+ * } else {
+ *   console.log('Errors:', validation.errors);
+ * }
+ *
+ * // Get XanoScript documentation
+ * const docs = xanoscriptDocs({ topic: 'syntax', mode: 'quick_reference' });
+ * console.log(docs.documentation);
+ *
+ * // Get Meta API documentation
+ * const apiDocs = metaApiDocs({ topic: 'workspace', detail_level: 'examples' });
+ * console.log(apiDocs.documentation);
+ *
+ * // Get CLI documentation
+ * const cliDocs = cliDocs({ topic: 'start' });
+ * console.log(cliDocs.documentation);
+ *
+ * // Get version
+ * const { version } = mcpVersion();
+ * console.log(`Version: ${version}`);
+ * ```
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Main Tool Exports
+// =============================================================================
+// Validation
+export { validateXanoscript, } from "./tools/validate_xanoscript.js";
+// XanoScript Documentation
+export { xanoscriptDocs, getXanoscriptDocsPath, setXanoscriptDocsPath, } from "./tools/xanoscript_docs.js";
+// MCP Version
+export { mcpVersion, getServerVersion, setServerVersion, } from "./tools/mcp_version.js";
+// Meta API Documentation
+export { metaApiDocs, metaApiTopics, getMetaApiTopicNames, getMetaApiTopicDescriptions, } from "./tools/meta_api_docs.js";
+// Run API Documentation
+export { runApiDocs, runApiTopics, getRunApiTopicNames, getRunApiTopicDescriptions, } from "./tools/run_api_docs.js";
+// CLI Documentation
+export { cliDocs, cliTopics, getCliTopicNames, getCliTopicDescriptions, } from "./tools/cli_docs.js";
+// =============================================================================
+// Utility Exports
+// =============================================================================
+export { toMcpResponse } from "./tools/types.js";
+// =============================================================================
+// XanoScript Core Exports (for advanced usage)
+// =============================================================================
+export { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getDocsForFilePath, extractQuickReference, getXanoscriptDocsVersion, getTopicNames as getXanoscriptTopicNames, getTopicDescriptions as getXanoscriptTopicDescriptions, } from "./xanoscript.js";
+// =============================================================================
+// MCP Tool Definitions (for building custom MCP servers)
+// =============================================================================
+export { toolDefinitions, handleTool, validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVersionToolDefinition, metaApiDocsToolDefinition, runApiDocsToolDefinition, cliDocsToolDefinition, } from "./tools/index.js";