@xano/developer-mcp 1.0.31 → 1.0.33

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: 'api/users/create_post.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`
@@ -173,7 +326,7 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `topic` | string | No | Specific documentation topic to retrieve |
-| `file_path` | string | No | File path being edited for context-aware docs (e.g., `apis/users/create.xs`) |
+| `file_path` | string | No | File path being edited for context-aware docs (e.g., `api/users/create_post.xs`) |
 | `mode` | string | No | `full` (default) or `quick_reference` for compact syntax cheatsheet |
 
 **Available Topics:**
@@ -213,7 +366,7 @@ xanoscript_docs()
 xanoscript_docs({ topic: "functions" })
 
 // Context-aware: get all docs relevant to file being edited
-xanoscript_docs({ file_path: "apis/users/create.xs" })
+xanoscript_docs({ file_path: "api/users/create_post.xs" })
 
 // Compact quick reference (uses less context)
 xanoscript_docs({ topic: "database", mode: "quick_reference" })
@@ -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
 
@@ -504,7 +667,7 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
 - Markdown files for XanoScript language reference
 - Configured in `src/index.ts` via `XANOSCRIPT_DOCS_V2` with:
   - **file**: The markdown file containing the documentation
-  - **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
+  - **applyTo**: Glob patterns for context-aware matching (e.g., `api/**/*.xs`)
   - **description**: Human-readable description of the topic
 
 **Meta API Documentation** (`src/meta_api_docs/`):

package/dist/cli_docs/topics/workspace.js

@@ -17,16 +17,59 @@ function: refresh_token
 ...
 \`\`\`
 
-When you pull, the CLI splits these into individual \`.xs\` files organized by type.`,
+When you pull, the CLI splits these into individual \`.xs\` files organized by type.
+
+## Directory Structure
+
+After \`workspace:pull\`, files are organized using snake_case naming:
+
+\`\`\`
+./xano-code/
+├── workspace/
+│   ├── my_workspace.xs           # Workspace configuration
+│   └── trigger/
+│       └── on_deploy.xs          # Workspace triggers
+├── api/
+│   └── users/                    # API group folder (snake_case)
+│       ├── api_group.xs          # API group definition
+│       ├── get_all.xs            # GET /users
+│       ├── get_one_get.xs        # GET /users/:id
+│       ├── create_post.xs        # POST /users
+│       └── nested/
+│           └── profile_get.xs    # GET /users/nested/profile
+├── function/
+│   └── validate_token.xs         # Reusable functions
+├── task/
+│   └── daily_cleanup.xs          # Scheduled tasks
+├── table/
+│   ├── users.xs                  # Table schema
+│   └── trigger/
+│       └── on_user_create.xs     # Table triggers
+├── agent/
+│   ├── support_bot.xs            # AI agents
+│   └── trigger/
+│       └── on_message.xs         # Agent triggers
+└── mcp_server/
+    ├── my_server.xs              # MCP server definitions
+    └── trigger/
+        └── on_connect.xs         # MCP server triggers
+\`\`\``,
     ai_hints: `**Key concepts:**
 - \`pull\` downloads workspace code and splits into organized .xs files
 - \`push\` combines .xs files and uploads to Xano
-- Files are organized by type: functions/, apis/, tasks/, etc.
+- Files use snake_case naming for folders and filenames
+- API endpoints are nested under their API group folder
 
 **Typical workflow:**
 1. \`xano workspace:pull ./xano-code\` - download
-2. Edit .xs files with your editor/IDE
-3. \`xano workspace:push ./xano-code\` - deploy
+2. Navigate to \`api/{group}/\` for API endpoints, \`function/\` for functions, etc.
+3. Edit .xs files with your editor/IDE
+4. \`xano workspace:push ./xano-code\` - deploy
+
+**File naming:**
+- All folders and files use snake_case (e.g., \`my_function.xs\`, \`user_profile/\`)
+- API endpoints include verb suffix (e.g., \`create_post.xs\`, \`get_one_get.xs\`)
+- Triggers are nested under \`{type}/trigger/\` folders
 
 **Version control:**
 - The pulled directory structure is git-friendly
@@ -159,13 +202,14 @@ When you pull, the CLI splits these into individual \`.xs\` files organized by t
             description: "Edit Xano code locally with your preferred tools",
             steps: [
                 "Pull workspace: `xano workspace:pull ./code`",
-                "Edit .xs files in your IDE",
+                "Navigate to organized folders: `api/{group}/`, `function/`, `table/`, etc.",
+                "Edit .xs files in your IDE (files use snake_case naming)",
                 "Validate changes: Use xanoscript_docs MCP tool",
                 "Push changes: `xano workspace:push ./code`",
                 "Test in Xano dashboard or via API"
             ],
             example: `xano workspace:pull ./my-app
-# Edit files...
+# Files organized: api/users/create_post.xs, function/validate_token.xs, etc.
 xano workspace:push ./my-app`
         },
         {

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