@promptpartner/bexio-mcp-server 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Bexio MCP Server v2 Entry Point
+ *
+ * This is the main entry point for the Bexio MCP server.
+ * It handles:
+ * - Environment variable loading
+ * - Command line argument parsing
+ * - Server initialization and startup
+ * - Dual transport: stdio (Claude Desktop) and http (n8n/remote)
+ *
+ * IMPORTANT: All logging goes to stderr via logger.ts.
+ * stdout is reserved for MCP JSON-RPC protocol messages (stdio mode only).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Bexio MCP Server v2 Entry Point
+ *
+ * This is the main entry point for the Bexio MCP server.
+ * It handles:
+ * - Environment variable loading
+ * - Command line argument parsing
+ * - Server initialization and startup
+ * - Dual transport: stdio (Claude Desktop) and http (n8n/remote)
+ *
+ * IMPORTANT: All logging goes to stderr via logger.ts.
+ * stdout is reserved for MCP JSON-RPC protocol messages (stdio mode only).
+ */
+import { config } from "dotenv";
+import { BexioMcpServer } from "./server.js";
+import { BexioClient } from "./bexio-client.js";
+import { logger } from "./logger.js";
+import { createHttpServer } from "./transports/http.js";
+// Load environment variables from .env file
+config();
+// Configuration from environment
+const BEXIO_API_TOKEN = process.env["BEXIO_API_TOKEN"];
+const BEXIO_BASE_URL = process.env["BEXIO_BASE_URL"] ?? "https://api.bexio.com/2.0";
+function parseArgs() {
+    const args = process.argv.slice(2);
+    // Parse --mode
+    const modeIndex = args.indexOf("--mode");
+    const modeArg = modeIndex !== -1 ? args[modeIndex + 1] : "stdio";
+    const mode = modeArg === "http" ? "http" : "stdio";
+    // Parse --host (for HTTP mode)
+    const hostIndex = args.indexOf("--host");
+    const host = hostIndex !== -1 ? args[hostIndex + 1] ?? "0.0.0.0" : "0.0.0.0";
+    // Parse --port (for HTTP mode)
+    const portIndex = args.indexOf("--port");
+    const portStr = portIndex !== -1 ? args[portIndex + 1] : "8000";
+    const port = parseInt(portStr, 10) || 8000;
+    return { mode, host, port };
+}
+function validateEnvironment() {
+    if (!BEXIO_API_TOKEN) {
+        logger.error("BEXIO_API_TOKEN environment variable is required");
+        logger.error("Set it in your .env file or environment");
+        process.exit(1);
+    }
+    logger.info(`Using Bexio API base URL: ${BEXIO_BASE_URL}`);
+}
+async function main() {
+    const { mode, host, port } = parseArgs();
+    // Validate environment
+    validateEnvironment();
+    // Create Bexio client
+    const client = new BexioClient({
+        baseUrl: BEXIO_BASE_URL,
+        apiToken: BEXIO_API_TOKEN,
+    });
+    if (mode === "stdio") {
+        logger.info("Starting in stdio mode (for Claude Desktop)");
+        // Create and initialize server with client
+        const server = new BexioMcpServer();
+        server.initialize(client);
+        await server.run();
+    }
+    else if (mode === "http") {
+        logger.info(`Starting in HTTP mode on ${host}:${port} (for n8n/remote access)`);
+        // Create HTTP server
+        await createHttpServer(client, { host, port });
+        // Keep the process alive
+        logger.info("HTTP server running. Press Ctrl+C to stop.");
+    }
+    else {
+        logger.error(`Invalid mode: ${mode}. Use 'stdio' or 'http'.`);
+        process.exit(1);
+    }
+}
+// Run the server
+main().catch((error) => {
+    logger.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger module that ONLY writes to stderr.
+ *
+ * CRITICAL: MCP protocol uses stdout for JSON-RPC messages.
+ * Any non-JSON output to stdout corrupts the protocol.
+ * All logging MUST go to stderr via console.error().
+ */
+export declare function debug(message: string, ...args: unknown[]): void;
+export declare function info(message: string, ...args: unknown[]): void;
+export declare function warn(message: string, ...args: unknown[]): void;
+export declare function error(message: string, ...args: unknown[]): void;
+export declare const logger: {
+    debug: typeof debug;
+    info: typeof info;
+    warn: typeof warn;
+    error: typeof error;
+};

package/dist/logger.js

@@ -0,0 +1,28 @@
+/**
+ * Logger module that ONLY writes to stderr.
+ *
+ * CRITICAL: MCP protocol uses stdout for JSON-RPC messages.
+ * Any non-JSON output to stdout corrupts the protocol.
+ * All logging MUST go to stderr via console.error().
+ */
+function formatTimestamp() {
+    return new Date().toISOString();
+}
+export function debug(message, ...args) {
+    console.error(`[DEBUG] ${formatTimestamp()} ${message}`, ...args);
+}
+export function info(message, ...args) {
+    console.error(`[INFO] ${formatTimestamp()} ${message}`, ...args);
+}
+export function warn(message, ...args) {
+    console.error(`[WARN] ${formatTimestamp()} ${message}`, ...args);
+}
+export function error(message, ...args) {
+    console.error(`[ERROR] ${formatTimestamp()} ${message}`, ...args);
+}
+export const logger = {
+    debug,
+    info,
+    warn,
+    error,
+};

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bexio MCP Server v2
+ *
+ * SDK 1.25.2 patterns:
+ * - Import from "@modelcontextprotocol/sdk/server/mcp.js"
+ * - McpServer.tool() for individual tool registration
+ * - Use server.connect(transport) to start
+ */
+import { BexioClient } from "./bexio-client.js";
+export declare class BexioMcpServer {
+    private server;
+    private client;
+    constructor();
+    /** Initialize with Bexio client and register tools */
+    initialize(client: BexioClient): void;
+    private registerTools;
+    run(): Promise<void>;
+}

package/dist/server.js

@@ -0,0 +1,81 @@
+/**
+ * Bexio MCP Server v2
+ *
+ * SDK 1.25.2 patterns:
+ * - Import from "@modelcontextprotocol/sdk/server/mcp.js"
+ * - McpServer.tool() for individual tool registration
+ * - Use server.connect(transport) to start
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { logger } from "./logger.js";
+import { getAllToolDefinitions, getHandler } from "./tools/index.js";
+import { formatSuccessResponse, formatErrorResponse, McpError } from "./shared/index.js";
+import { registerUIResources } from "./ui-resources.js";
+const SERVER_NAME = "bexio-mcp-server";
+const SERVER_VERSION = "2.0.0";
+export class BexioMcpServer {
+    server;
+    client = null;
+    constructor() {
+        this.server = new McpServer({
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+        });
+    }
+    /** Initialize with Bexio client and register tools */
+    initialize(client) {
+        this.client = client;
+        this.registerTools();
+        registerUIResources(this.server, client);
+        logger.info(`Initialized with ${getAllToolDefinitions().length} tools + 3 UI tools`);
+    }
+    registerTools() {
+        // Register ping tool for SDK validation
+        this.server.tool("ping", "Test tool that returns pong - validates SDK integration", {}, async () => {
+            logger.debug("ping tool called");
+            return {
+                content: [{ type: "text", text: "pong" }],
+            };
+        });
+        // Register all domain tools
+        const definitions = getAllToolDefinitions();
+        for (const def of definitions) {
+            const handler = getHandler(def.name);
+            if (!handler) {
+                logger.warn(`No handler found for tool: ${def.name}`);
+                continue;
+            }
+            // SDK 1.25.2 expects a ZodRawShape (plain object with Zod schemas)
+            // Use empty shape and let our handlers do the validation
+            this.server.tool(def.name, def.description || "", {}, async (args) => {
+                if (!this.client) {
+                    return formatErrorResponse(McpError.internal("Bexio client not initialized"));
+                }
+                try {
+                    const result = await handler(this.client, args);
+                    return formatSuccessResponse(def.name, result);
+                }
+                catch (error) {
+                    if (error instanceof McpError) {
+                        return formatErrorResponse(error);
+                    }
+                    if (error instanceof z.ZodError) {
+                        return formatErrorResponse(McpError.validation(error.message, { issues: error.issues }));
+                    }
+                    return formatErrorResponse(error instanceof Error
+                        ? error
+                        : new Error(String(error)));
+                }
+            });
+        }
+        logger.info(`Registered ${definitions.length + 1} tools (including ping)`);
+    }
+    async run() {
+        logger.info(`Starting ${SERVER_NAME} v${SERVER_VERSION}`);
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        logger.info("Server connected to stdio transport");
+    }
+}

package/dist/shared/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * McpError class for standardized error handling.
+ * Error messages include recovery suggestions for LLM self-correction.
+ */
+export type McpErrorCode = "NOT_FOUND" | "VALIDATION_ERROR" | "BEXIO_API_ERROR" | "INTERNAL_ERROR";
+export declare class McpError extends Error {
+    readonly code: McpErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly statusCode?: number;
+    constructor(code: McpErrorCode, message: string, details?: Record<string, unknown>, statusCode?: number);
+    /** Resource not found - suggests listing resources first */
+    static notFound(resource: string, id: string | number): McpError;
+    /** Validation error - includes specific field issues */
+    static validation(message: string, details?: Record<string, unknown>): McpError;
+    /** Bexio API error - includes status and recovery suggestions */
+    static bexioApi(message: string, statusCode?: number, details?: Record<string, unknown>): McpError;
+    /** Internal server error */
+    static internal(message: string, details?: Record<string, unknown>): McpError;
+    /** Convert to plain object for JSON serialization */
+    toJSON(): Record<string, unknown>;
+}

package/dist/shared/errors.js

@@ -0,0 +1,54 @@
+/**
+ * McpError class for standardized error handling.
+ * Error messages include recovery suggestions for LLM self-correction.
+ */
+export class McpError extends Error {
+    code;
+    details;
+    statusCode;
+    constructor(code, message, details, statusCode) {
+        super(message);
+        this.name = "McpError";
+        this.code = code;
+        this.details = details;
+        this.statusCode = statusCode;
+    }
+    /** Resource not found - suggests listing resources first */
+    static notFound(resource, id) {
+        return new McpError("NOT_FOUND", `${resource} with ID ${id} not found. Try listing ${resource.toLowerCase()}s first to find valid IDs.`, { resource, id });
+    }
+    /** Validation error - includes specific field issues */
+    static validation(message, details) {
+        return new McpError("VALIDATION_ERROR", `Validation failed: ${message}. Check the required fields and their formats.`, details);
+    }
+    /** Bexio API error - includes status and recovery suggestions */
+    static bexioApi(message, statusCode, details) {
+        let suggestion = "";
+        if (statusCode === 401) {
+            suggestion = " Check that BEXIO_API_TOKEN is valid and not expired.";
+        }
+        else if (statusCode === 403) {
+            suggestion = " The API token may lack permissions for this operation.";
+        }
+        else if (statusCode === 429) {
+            suggestion = " Rate limit exceeded. Wait a moment before retrying.";
+        }
+        else if (statusCode && statusCode >= 500) {
+            suggestion = " Bexio server error. Retry the request in a few seconds.";
+        }
+        return new McpError("BEXIO_API_ERROR", `Bexio API error: ${message}.${suggestion}`, details, statusCode);
+    }
+    /** Internal server error */
+    static internal(message, details) {
+        return new McpError("INTERNAL_ERROR", `Internal error: ${message}. Please report this issue.`, details);
+    }
+    /** Convert to plain object for JSON serialization */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+            statusCode: this.statusCode,
+        };
+    }
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared utilities barrel export.
+ */
+export * from "./errors.js";
+export * from "./response.js";

package/dist/shared/index.js

@@ -0,0 +1,5 @@
+/**
+ * Shared utilities barrel export.
+ */
+export * from "./errors.js";
+export * from "./response.js";

package/dist/shared/response.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Response formatting utilities for MCP tool responses.
+ * Maintains backward compatibility with v1 format.
+ */
+import { McpError } from "./errors.js";
+interface McpContent {
+    type: "text";
+    text: string;
+    [key: string]: unknown;
+}
+export interface McpResponse {
+    content: McpContent[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Format a successful tool response */
+export declare function formatSuccessResponse(toolName: string, data: unknown, meta?: Record<string, unknown>): McpResponse;
+/** Format an error response */
+export declare function formatErrorResponse(error: McpError | Error): McpResponse;
+/** Format a list response with pagination info */
+export declare function formatListResponse(toolName: string, data: unknown[], hasMore: boolean, meta?: Record<string, unknown>): McpResponse;
+/** Map tool names to response data keys */
+export declare function getDataKey(toolName: string): string;
+export {};

package/dist/shared/response.js

@@ -0,0 +1,92 @@
+/**
+ * Response formatting utilities for MCP tool responses.
+ * Maintains backward compatibility with v1 format.
+ */
+import { McpError } from "./errors.js";
+/** Format a successful tool response */
+export function formatSuccessResponse(toolName, data, meta) {
+    const dataKey = getDataKey(toolName);
+    const responseMeta = {
+        source: "bexio",
+        fetched_at: new Date().toISOString(),
+        tool: toolName,
+        ...meta,
+    };
+    const responseData = {
+        [dataKey]: data,
+        meta: responseMeta,
+    };
+    const completionMarker = "\n\n--- RESPONSE COMPLETE ---";
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(responseData, null, 2) + completionMarker,
+            },
+        ],
+    };
+}
+/** Format an error response */
+export function formatErrorResponse(error) {
+    let errorData;
+    if (error instanceof McpError) {
+        errorData = error.toJSON();
+    }
+    else {
+        errorData = {
+            code: "INTERNAL_ERROR",
+            message: error.message,
+        };
+    }
+    const completionMarker = "\n\n--- RESPONSE COMPLETE ---";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error: ${JSON.stringify(errorData, null, 2)}${completionMarker}`,
+            },
+        ],
+        isError: true,
+    };
+}
+/** Format a list response with pagination info */
+export function formatListResponse(toolName, data, hasMore, meta) {
+    return formatSuccessResponse(toolName, data, {
+        count: data.length,
+        has_more: hasMore,
+        ...meta,
+    });
+}
+/** Map tool names to response data keys */
+export function getDataKey(toolName) {
+    const mapping = {
+        // Contacts
+        list_contacts: "contacts",
+        get_contact: "contact",
+        search_contacts: "contacts",
+        advanced_search_contacts: "contacts",
+        find_contact_by_number: "contact",
+        find_contact_by_name: "contacts",
+        update_contact: "contact",
+        // Invoices
+        list_invoices: "invoices",
+        list_all_invoices: "invoices",
+        get_invoice: "invoice",
+        search_invoices: "invoices",
+        search_invoices_by_customer: "invoices",
+        create_invoice: "invoice",
+        // Orders
+        list_orders: "orders",
+        get_order: "order",
+        create_order: "order",
+        search_orders: "orders",
+        search_orders_by_customer: "orders",
+        // Quotes
+        list_quotes: "quotes",
+        get_quote: "quote",
+        create_quote: "quote",
+        search_quotes: "quotes",
+        search_quotes_by_customer: "quotes",
+    };
+    return mapping[toolName] || "data";
+}

package/dist/tools/accounting/definitions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Accounting tool definitions.
+ * Contains MCP tool metadata for accounting domain.
+ * Includes: Accounts, Account Groups, Calendar Years, Business Years, Manual Entries, VAT Periods, Journal
+ *
+ * 15 tools total covering ACCT-01 through ACCT-07 requirements.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const toolDefinitions: Tool[];