@xano/developer-mcp 1.0.21 → 1.0.22

package/README.md

@@ -355,31 +355,40 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 | `build` | `tsc` | Compile TypeScript to JavaScript |
 | `start` | `node dist/index.js` | Run the MCP server |
 | `dev` | `tsc && node dist/index.js` | Build and run in development |
+| `test` | `vitest run` | Run unit tests |
+| `test:watch` | `vitest` | Run tests in watch mode |
+| `test:coverage` | `vitest run --coverage` | Run tests with coverage report |
 
 ## Project Structure
 
 ```
 xano-developer-mcp/
 ├── src/
-│   ├── index.ts              # Main MCP server implementation
-│   ├── xanoscript.d.ts       # TypeScript declarations
-│   ├── meta_api_docs/        # Meta API documentation
-│   │   ├── index.ts          # API docs tool handler
-│   │   ├── types.ts          # Type definitions
-│   │   ├── format.ts         # Documentation formatter
-│   │   └── topics/           # Individual topic modules
-│   ├── run_api_docs/         # Run API documentation
-│   │   ├── index.ts          # Run API tool handler
-│   │   ├── format.ts         # Documentation formatter
-│   │   └── topics/           # Individual topic modules
-│   ├── xanoscript_docs/      # XanoScript language documentation
-│   │   ├── version.json
-│   │   ├── README.md
-│   │   ├── syntax.md
-│   │   └── ...
-│   └── templates/
-│       └── xanoscript-index.ts
-├── dist/                      # Compiled JavaScript output
+│   ├── index.ts                        # Main MCP server implementation
+│   ├── xanoscript.ts                   # XanoScript documentation logic
+│   ├── xanoscript.test.ts              # Tests for xanoscript module
+│   ├── xanoscript-language-server.d.ts # TypeScript declarations
+│   ├── meta_api_docs/                  # Meta API documentation
+│   │   ├── index.ts                    # API docs tool handler
+│   │   ├── index.test.ts               # Tests for index
+│   │   ├── types.ts                    # Type definitions
+│   │   ├── types.test.ts               # Tests for types
+│   │   ├── format.ts                   # Documentation formatter
+│   │   ├── format.test.ts              # Tests for formatter
+│   │   └── topics/                     # Individual topic modules
+│   ├── run_api_docs/                   # Run API documentation
+│   │   ├── index.ts                    # Run API tool handler
+│   │   ├── index.test.ts               # Tests for index
+│   │   ├── format.ts                   # Documentation formatter
+│   │   ├── format.test.ts              # Tests for formatter
+│   │   └── topics/                     # Individual topic modules
+│   └── xanoscript_docs/                # XanoScript language documentation
+│       ├── version.json
+│       ├── README.md
+│       ├── syntax.md
+│       └── ...
+├── dist/                               # Compiled JavaScript output
+├── vitest.config.ts                    # Test configuration
 ├── package.json
 └── tsconfig.json
 ```
@@ -392,6 +401,15 @@ xano-developer-mcp/
 | `@xano/xanoscript-language-server` | ^11.6.3 | XanoScript parser and validation |
 | `minimatch` | ^10.1.2 | Glob pattern matching for context-aware docs |
 
+### Dev Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `typescript` | ^5.9.0 | TypeScript compiler |
+| `vitest` | ^3.0.0 | Fast unit test framework |
+| `@types/node` | ^22.0.0 | Node.js type definitions |
+| `@types/minimatch` | ^5.1.2 | Minimatch type definitions |
+
 ## How It Works
 
 ```
@@ -444,6 +462,69 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
 - Supports parameterized output (detail levels, schema inclusion)
 - Better for AI consumption due to context efficiency
 
+## Testing
+
+The project uses [Vitest](https://vitest.dev/) as its test framework with comprehensive unit tests.
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode (re-runs on file changes)
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+### Test Coverage
+
+| Module | Test File | Description |
+|--------|-----------|-------------|
+| `xanoscript.ts` | `xanoscript.test.ts` | Core XanoScript documentation logic including file path matching and quick reference extraction |
+| `meta_api_docs/index.ts` | `meta_api_docs/index.test.ts` | Meta API documentation handler and topic management |
+| `meta_api_docs/format.ts` | `meta_api_docs/format.test.ts` | Documentation formatting for endpoints, examples, and patterns |
+| `meta_api_docs/types.ts` | `meta_api_docs/types.test.ts` | Type structure validation |
+| `run_api_docs/index.ts` | `run_api_docs/index.test.ts` | Run API documentation handler |
+| `run_api_docs/format.ts` | `run_api_docs/format.test.ts` | Run API formatting with correct base URL |
+
+### Test Structure
+
+Tests are co-located with source files using the `.test.ts` suffix:
+
+```
+src/
+├── xanoscript.ts
+├── xanoscript.test.ts          # Tests for xanoscript.ts
+├── meta_api_docs/
+│   ├── index.ts
+│   ├── index.test.ts           # Tests for index.ts
+│   ├── format.ts
+│   ├── format.test.ts          # Tests for format.ts
+│   └── ...
+└── run_api_docs/
+    ├── index.ts
+    ├── index.test.ts           # Tests for index.ts
+    └── ...
+```
+
+### Writing Tests
+
+Tests use Vitest's API which is compatible with Jest:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { myFunction } from "./myModule.js";
+
+describe("myFunction", () => {
+  it("should return expected result", () => {
+    expect(myFunction("input")).toBe("expected");
+  });
+});
+```
+
 ## License
 
 See [LICENSE](LICENSE) for details.

package/dist/index.js

@@ -5,11 +5,11 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { minimatch } from "minimatch";
 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 { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getXanoscriptDocsVersion, getTopicDescriptions, } from "./xanoscript.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -18,138 +18,6 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
     console.log(SERVER_VERSION);
     process.exit(0);
 }
-const XANOSCRIPT_DOCS_V2 = {
-    readme: {
-        file: "README.md",
-        applyTo: [],
-        description: "XanoScript overview, workspace structure, and quick reference",
-    },
-    syntax: {
-        file: "syntax.md",
-        applyTo: ["**/*.xs"],
-        description: "Expressions, operators, and filters for all XanoScript code",
-    },
-    types: {
-        file: "types.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tools/**/*.xs", "agents/**/*.xs"],
-        description: "Data types, input blocks, and validation",
-    },
-    tables: {
-        file: "tables.md",
-        applyTo: ["tables/*.xs"],
-        description: "Database schema definitions with indexes and relationships",
-    },
-    functions: {
-        file: "functions.md",
-        applyTo: ["functions/**/*.xs"],
-        description: "Reusable function stacks with inputs and responses",
-    },
-    apis: {
-        file: "apis.md",
-        applyTo: ["apis/**/*.xs"],
-        description: "HTTP endpoint definitions with authentication and CRUD patterns",
-    },
-    tasks: {
-        file: "tasks.md",
-        applyTo: ["tasks/*.xs"],
-        description: "Scheduled and cron jobs",
-    },
-    triggers: {
-        file: "triggers.md",
-        applyTo: ["triggers/**/*.xs"],
-        description: "Event-driven handlers (table, realtime, workspace, agent, MCP)",
-    },
-    database: {
-        file: "database.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs", "tools/**/*.xs"],
-        description: "All db.* operations: query, get, add, edit, patch, delete",
-    },
-    agents: {
-        file: "agents.md",
-        applyTo: ["agents/**/*.xs"],
-        description: "AI agent configuration with LLM providers and tools",
-    },
-    tools: {
-        file: "tools.md",
-        applyTo: ["tools/**/*.xs"],
-        description: "AI tools for agents and MCP servers",
-    },
-    "mcp-servers": {
-        file: "mcp-servers.md",
-        applyTo: ["mcp_servers/**/*.xs"],
-        description: "MCP server definitions exposing tools",
-    },
-    testing: {
-        file: "testing.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Unit tests, mocks, and assertions",
-    },
-    integrations: {
-        file: "integrations.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs"],
-        description: "Cloud storage, Redis, security, and external APIs",
-    },
-    frontend: {
-        file: "frontend.md",
-        applyTo: ["static/**/*"],
-        description: "Static frontend development and deployment",
-    },
-    run: {
-        file: "run.md",
-        applyTo: ["run/**/*.xs"],
-        description: "Run job and service configurations for the Xano Job Runner",
-    },
-    addons: {
-        file: "addons.md",
-        applyTo: ["addons/*.xs", "functions/**/*.xs", "apis/**/*.xs"],
-        description: "Reusable subqueries for fetching related data",
-    },
-    debugging: {
-        file: "debugging.md",
-        applyTo: ["**/*.xs"],
-        description: "Logging, inspecting, and debugging XanoScript execution",
-    },
-    performance: {
-        file: "performance.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Performance optimization best practices",
-    },
-    realtime: {
-        file: "realtime.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs", "triggers/**/*.xs"],
-        description: "Real-time channels and events for push updates",
-    },
-    schema: {
-        file: "schema.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Runtime schema parsing and validation",
-    },
-    security: {
-        file: "security.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Security best practices for authentication and authorization",
-    },
-    streaming: {
-        file: "streaming.md",
-        applyTo: ["functions/**/*.xs", "apis/**/*.xs"],
-        description: "Streaming data from files, requests, and responses",
-    },
-    middleware: {
-        file: "middleware.md",
-        applyTo: ["middleware/**/*.xs"],
-        description: "Request/response interceptors for functions, queries, tasks, and tools",
-    },
-    branch: {
-        file: "branch.md",
-        applyTo: ["branch.xs"],
-        description: "Branch-level settings: middleware, history retention, visual styling",
-    },
-    workspace: {
-        file: "workspace.md",
-        applyTo: ["workspace.xs"],
-        description: "Workspace-level settings: environment variables, preferences, realtime",
-    },
-};
 // =============================================================================
 // Path Resolution
 // =============================================================================
@@ -171,109 +39,6 @@ function getXanoscriptDocsPath() {
 }
 const XANOSCRIPT_DOCS_PATH = getXanoscriptDocsPath();
 // =============================================================================
-// Documentation Helpers
-// =============================================================================
-function getXanoscriptDocsVersion() {
-    try {
-        const versionFile = readFileSync(join(XANOSCRIPT_DOCS_PATH, "version.json"), "utf-8");
-        return JSON.parse(versionFile).version || "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
-// =============================================================================
-// XanoScript Documentation v2 Functions
-// =============================================================================
-/**
- * Get list of topics that apply to a given file path based on applyTo patterns
- */
-function getDocsForFilePath(filePath) {
-    const matches = [];
-    for (const [topic, config] of Object.entries(XANOSCRIPT_DOCS_V2)) {
-        if (topic === "readme")
-            continue; // Don't auto-include readme
-        for (const pattern of config.applyTo) {
-            if (minimatch(filePath, pattern)) {
-                matches.push(topic);
-                break;
-            }
-        }
-    }
-    // Always include syntax as foundation (if not already matched)
-    if (!matches.includes("syntax")) {
-        matches.unshift("syntax");
-    }
-    return matches;
-}
-/**
- * Extract just the Quick Reference section from a doc
- */
-function extractQuickReference(content, topic) {
-    const lines = content.split("\n");
-    const startIdx = lines.findIndex((l) => l.startsWith("## Quick Reference"));
-    if (startIdx === -1) {
-        // Fallback: return first 50 lines or up to first ## section
-        const firstSection = lines.findIndex((l, i) => i > 0 && l.startsWith("## "));
-        return lines.slice(0, firstSection > 0 ? firstSection : 50).join("\n");
-    }
-    // Find the next ## section after Quick Reference
-    let endIdx = lines.findIndex((l, i) => i > startIdx && l.startsWith("## "));
-    if (endIdx === -1)
-        endIdx = lines.length;
-    // Include topic header for context
-    const header = `# ${topic}\n\n`;
-    return header + lines.slice(startIdx, endIdx).join("\n");
-}
-/**
- * Read XanoScript documentation with new v2 structure
- */
-function readXanoscriptDocsV2(args) {
-    const mode = args?.mode || "full";
-    const version = getXanoscriptDocsVersion();
-    try {
-        // Default: return README
-        if (!args?.topic && !args?.file_path) {
-            const readme = readFileSync(join(XANOSCRIPT_DOCS_PATH, "README.md"), "utf-8");
-            return `${readme}\n\n---\nDocumentation version: ${version}`;
-        }
-        // Context-aware: return docs matching file pattern
-        if (args?.file_path) {
-            const topics = getDocsForFilePath(args.file_path);
-            if (topics.length === 0) {
-                return `No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`;
-            }
-            const docs = topics.map((t) => {
-                const config = XANOSCRIPT_DOCS_V2[t];
-                const content = readFileSync(join(XANOSCRIPT_DOCS_PATH, config.file), "utf-8");
-                return mode === "quick_reference"
-                    ? extractQuickReference(content, t)
-                    : content;
-            });
-            const header = `# XanoScript Documentation for: ${args.file_path}\n\nMatched topics: ${topics.join(", ")}\nMode: ${mode}\nVersion: ${version}\n\n---\n\n`;
-            return header + docs.join("\n\n---\n\n");
-        }
-        // Topic-based: return specific doc
-        if (args?.topic) {
-            const config = XANOSCRIPT_DOCS_V2[args.topic];
-            if (!config) {
-                const availableTopics = Object.keys(XANOSCRIPT_DOCS_V2).join(", ");
-                return `Error: Unknown topic "${args.topic}".\n\nAvailable topics: ${availableTopics}`;
-            }
-            const content = readFileSync(join(XANOSCRIPT_DOCS_PATH, config.file), "utf-8");
-            const doc = mode === "quick_reference"
-                ? extractQuickReference(content, args.topic)
-                : content;
-            return `${doc}\n\n---\nDocumentation version: ${version}`;
-        }
-        return "Error: Invalid parameters";
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return `Error reading XanoScript documentation: ${errorMessage}`;
-    }
-}
-// =============================================================================
 // MCP Server Setup
 // =============================================================================
 const server = new Server({
@@ -310,7 +75,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         throw new Error(`Unknown topic: ${topic}. Available: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`);
     }
     const content = readFileSync(join(XANOSCRIPT_DOCS_PATH, config.file), "utf-8");
-    const version = getXanoscriptDocsVersion();
+    const version = getXanoscriptDocsVersion(XANOSCRIPT_DOCS_PATH);
     return {
         contents: [
             {
@@ -352,10 +117,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         topic: {
                             type: "string",
-                            description: "Documentation topic. Available: " +
-                                Object.entries(XANOSCRIPT_DOCS_V2)
-                                    .map(([k, v]) => `${k} (${v.description.split(".")[0]})`)
-                                    .join(", "),
+                            description: "Documentation topic. Available: " + getTopicDescriptions(),
                         },
                         file_path: {
                             type: "string",
@@ -462,7 +224,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     if (request.params.name === "xanoscript_docs") {
         const args = request.params.arguments;
-        const documentation = readXanoscriptDocsV2(args);
+        const documentation = readXanoscriptDocsV2(XANOSCRIPT_DOCS_PATH, args);
         return {
             content: [
                 {

package/dist/meta_api_docs/format.d.ts

@@ -2,4 +2,19 @@
  * Formatting utilities for API documentation output
  */
 import type { TopicDoc, DetailLevel } from "./types.js";
-export declare function formatDocumentation(doc: TopicDoc, detailLevel?: DetailLevel, includeSchemas?: boolean): string;
+/**
+ * Configuration for documentation formatting
+ */
+export interface FormatConfig {
+    baseUrlInfo: string;
+    toolName: string;
+}
+/**
+ * Default config for Meta API
+ */
+export declare const META_API_CONFIG: FormatConfig;
+/**
+ * Config for Run API
+ */
+export declare const RUN_API_CONFIG: FormatConfig;
+export declare function formatDocumentation(doc: TopicDoc, detailLevel?: DetailLevel, includeSchemas?: boolean, config?: FormatConfig): string;

package/dist/meta_api_docs/format.js

@@ -2,14 +2,32 @@
  * Formatting utilities for API documentation output
  */
 /**
- * Base URL information included with any topic that has endpoints
+ * Default config for Meta API
  */
-const BASE_URL_INFO = `## Base URL
+export const META_API_CONFIG = {
+    baseUrlInfo: `## Base URL
 \`\`\`
 https://<your-instance-subdomain>.xano.io/api:meta/<endpoint>
 \`\`\`
 Authorization: \`Bearer <your-access-token>\`
-`;
+`,
+    toolName: "meta_api_docs",
+};
+/**
+ * Config for Run API
+ */
+export const RUN_API_CONFIG = {
+    baseUrlInfo: `## Base URL
+\`\`\`
+https://app.dev.xano.com/api:run/<endpoint>
+\`\`\`
+
+**Important:** This is a fixed URL - NOT your Xano instance URL. All Run API requests go to this central endpoint.
+
+Authorization: \`Bearer <your-access-token>\`
+`,
+    toolName: "run_api_docs",
+};
 function formatParameter(param) {
     const required = param.required ? " (required)" : "";
     const defaultVal = param.default !== undefined ? ` [default: ${param.default}]` : "";
@@ -109,7 +127,7 @@ function formatPattern(pattern) {
     }
     return lines.join("\n");
 }
-export function formatDocumentation(doc, detailLevel = "detailed", includeSchemas = true) {
+export function formatDocumentation(doc, detailLevel = "detailed", includeSchemas = true, config = META_API_CONFIG) {
     const sections = [];
     // Header
     sections.push(`# ${doc.title}`);
@@ -124,7 +142,7 @@ export function formatDocumentation(doc, detailLevel = "detailed", includeSchema
     // Include base URL info if topic has endpoints or patterns (workflows)
     if (doc.endpoints?.length || doc.patterns?.length) {
         sections.push("");
-        sections.push(BASE_URL_INFO);
+        sections.push(config.baseUrlInfo);
     }
     // Endpoints
     if (doc.endpoints?.length) {
@@ -165,7 +183,7 @@ export function formatDocumentation(doc, detailLevel = "detailed", includeSchema
     if (doc.related_topics?.length) {
         sections.push("");
         sections.push("## Related Topics");
-        sections.push(`Use \`meta_api_docs\` with topic: ${doc.related_topics.join(", ")}`);
+        sections.push(`Use \`${config.toolName}\` with topic: ${doc.related_topics.join(", ")}`);
     }
     return sections.join("\n");
 }

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

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