@promptpartner/bexio-mcp-server 2.0.0

package/dist/transports/http.js

@@ -0,0 +1,203 @@
+/**
+ * HTTP Transport for Bexio MCP Server.
+ * Provides HTTP/REST access for n8n and other remote clients.
+ *
+ * IMPORTANT: All logging uses logger (stderr), stdout reserved for nothing in HTTP mode.
+ */
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import { logger } from "../logger.js";
+import { getAllToolDefinitions, createHandlerRegistry } from "../tools/index.js";
+/**
+ * Creates an HTTP server for the MCP server.
+ * This enables n8n and other HTTP clients to interact with the Bexio API.
+ */
+export async function createHttpServer(client, options) {
+    const { host, port } = options;
+    // Create handler registry
+    const handlerRegistry = createHandlerRegistry(client);
+    const app = Fastify({
+        logger: false, // We use our own logger
+    });
+    // Register CORS for browser/n8n access
+    await app.register(cors, {
+        origin: true,
+    });
+    logger.info("HTTP server initializing...");
+    // Health check endpoint
+    app.get("/", async () => {
+        return {
+            status: "running",
+            server: "bexio-mcp-server",
+            version: "2.0.0",
+            mode: "http",
+        };
+    });
+    // List tools endpoint (GET for simplicity)
+    app.get("/tools", async () => {
+        const tools = getAllToolDefinitions();
+        return { tools, count: tools.length };
+    });
+    // MCP-style JSON-RPC endpoint
+    app.post("/mcp", async (request, reply) => {
+        const body = request.body;
+        // Handle batch requests
+        if (Array.isArray(body)) {
+            const results = await Promise.all(body.map((req) => handleJsonRpcRequest(req, handlerRegistry)));
+            return results;
+        }
+        // Handle single request
+        return handleJsonRpcRequest(body, handlerRegistry);
+    });
+    // Direct tool call endpoint (simpler than JSON-RPC)
+    app.post("/tools/call", async (request, reply) => {
+        const toolName = request.body?.name;
+        try {
+            const { name, arguments: args = {} } = request.body;
+            if (!name) {
+                return reply.code(400).send({ error: "Tool name is required" });
+            }
+            const handler = handlerRegistry.get(name);
+            if (!handler) {
+                return reply.code(404).send({ error: `Unknown tool: ${name}` });
+            }
+            const result = await handler(args);
+            return {
+                success: true,
+                data: result,
+                tool: name,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return reply.code(500).send({
+                success: false,
+                error: errorMessage,
+                tool: toolName || "unknown",
+                timestamp: new Date().toISOString(),
+            });
+        }
+    });
+    // n8n-specific endpoint for easier integration
+    app.post("/n8n/call", async (request, reply) => {
+        try {
+            const { tool, params = {} } = request.body;
+            if (!tool) {
+                return reply.code(400).send({ error: "Tool name is required" });
+            }
+            const handler = handlerRegistry.get(tool);
+            if (!handler) {
+                return reply.code(404).send({ error: `Unknown tool: ${tool}` });
+            }
+            const result = await handler(params);
+            return {
+                success: true,
+                data: result,
+                tool,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return reply.code(500).send({
+                success: false,
+                error: errorMessage,
+                tool: request.body?.tool || "unknown",
+                timestamp: new Date().toISOString(),
+            });
+        }
+    });
+    // Start server
+    try {
+        await app.listen({ host, port });
+        logger.info(`HTTP server listening on ${host}:${port}`);
+        logger.info("Available endpoints:");
+        logger.info("  GET  /          - Health check");
+        logger.info("  GET  /tools     - List all tools");
+        logger.info("  POST /mcp       - JSON-RPC endpoint");
+        logger.info("  POST /tools/call - Direct tool call");
+        logger.info("  POST /n8n/call  - n8n-friendly endpoint");
+    }
+    catch (error) {
+        logger.error("Failed to start HTTP server:", error);
+        throw error;
+    }
+    return app;
+}
+/**
+ * Handle a JSON-RPC request.
+ */
+async function handleJsonRpcRequest(request, handlerRegistry) {
+    const { id, method, params } = request;
+    try {
+        // Handle MCP protocol methods
+        if (method === "initialize") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: { tools: {} },
+                    serverInfo: {
+                        name: "bexio-mcp-server",
+                        version: "2.0.0",
+                    },
+                },
+            };
+        }
+        if (method === "tools/list") {
+            const tools = getAllToolDefinitions();
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: { tools },
+            };
+        }
+        if (method === "tools/call") {
+            const callParams = params;
+            if (!callParams?.name) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: { code: -32602, message: "Invalid params: name is required" },
+                };
+            }
+            const handler = handlerRegistry.get(callParams.name);
+            if (!handler) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: { code: -32601, message: `Unknown tool: ${callParams.name}` },
+                };
+            }
+            const result = await handler(callParams.arguments ?? {});
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                },
+            };
+        }
+        // Unknown method
+        return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32601, message: `Method not found: ${method}` },
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32603, message: errorMessage },
+        };
+    }
+}

package/dist/transports/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Transports barrel export.
+ */
+export { createHttpServer, type HttpServerOptions } from "./http.js";

package/dist/transports/index.js

@@ -0,0 +1,4 @@
+/**
+ * Transports barrel export.
+ */
+export { createHttpServer } from "./http.js";

package/dist/types/common.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Common types shared across all domains.
+ * Keep this file under 50 lines.
+ */
+import { z } from "zod";
+export interface BexioConfig {
+    baseUrl: string;
+    apiToken: string;
+}
+export interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+export interface BexioApiResponse<T = unknown> {
+    data?: T;
+    error?: string;
+    message?: string;
+}
+export declare const SearchCriteriaSchema: z.ZodObject<{
+    field: z.ZodString;
+    value: z.ZodString;
+    criteria: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    value: string;
+    criteria: string;
+}, {
+    field: string;
+    value: string;
+    criteria?: string | undefined;
+}>;
+export type SearchCriteria = z.infer<typeof SearchCriteriaSchema>;

package/dist/types/common.js

@@ -0,0 +1,11 @@
+/**
+ * Common types shared across all domains.
+ * Keep this file under 50 lines.
+ */
+import { z } from "zod";
+// Search criteria for advanced searches
+export const SearchCriteriaSchema = z.object({
+    field: z.string().min(1, "Field is required"),
+    value: z.string().min(1, "Value is required"),
+    criteria: z.string().default("like"),
+});

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Types barrel export.
+ * Single import point for all types in the project.
+ *
+ * Usage:
+ *   import { BexioConfig, ListContactsParamsSchema } from "./types/index.js";
+ */
+export * from "./common.js";
+export * from "./schemas/index.js";

package/dist/types/index.js

@@ -0,0 +1,11 @@
+/**
+ * Types barrel export.
+ * Single import point for all types in the project.
+ *
+ * Usage:
+ *   import { BexioConfig, ListContactsParamsSchema } from "./types/index.js";
+ */
+// Common types and interfaces
+export * from "./common.js";
+// All domain schemas
+export * from "./schemas/index.js";

package/dist/types/schemas/accounting.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Accounting Zod schemas and types.
+ * Domain: Accounting (Accounts, Account Groups, Calendar Years, Business Years, Manual Entries, VAT Periods, Journal)
+ *
+ * Manual entries use flat MCP parameters - handlers transform to nested Bexio API structure.
+ * Bexio validates double-entry rules server-side (debits must equal credits).
+ */
+import { z } from "zod";
+export declare const ListAccountsParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListAccountsParams = z.infer<typeof ListAccountsParamsSchema>;
+export declare const GetAccountParamsSchema: z.ZodObject<{
+    account_id: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    account_id: number;
+}, {
+    account_id: number;
+}>;
+export type GetAccountParams = z.infer<typeof GetAccountParamsSchema>;
+export declare const CreateAccountParamsSchema: z.ZodObject<{
+    account_no: z.ZodNumber;
+    name: z.ZodString;
+    account_group_id: z.ZodNumber;
+    is_active: z.ZodDefault<z.ZodBoolean>;
+    tax_id: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    account_no: number;
+    account_group_id: number;
+    is_active: boolean;
+    tax_id?: number | undefined;
+}, {
+    name: string;
+    account_no: number;
+    account_group_id: number;
+    tax_id?: number | undefined;
+    is_active?: boolean | undefined;
+}>;
+export type CreateAccountParams = z.infer<typeof CreateAccountParamsSchema>;
+export declare const SearchAccountsParamsSchema: z.ZodObject<{
+    search_criteria: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        value: string | number | boolean;
+        criteria?: string | undefined;
+    }, {
+        field: string;
+        value: string | number | boolean;
+        criteria?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    search_criteria: {
+        field: string;
+        value: string | number | boolean;
+        criteria?: string | undefined;
+    }[];
+}, {
+    search_criteria: {
+        field: string;
+        value: string | number | boolean;
+        criteria?: string | undefined;
+    }[];
+}>;
+export type SearchAccountsParams = z.infer<typeof SearchAccountsParamsSchema>;
+export declare const ListAccountGroupsParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListAccountGroupsParams = z.infer<typeof ListAccountGroupsParamsSchema>;
+export declare const ListCalendarYearsParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListCalendarYearsParams = z.infer<typeof ListCalendarYearsParamsSchema>;
+export declare const GetCalendarYearParamsSchema: z.ZodObject<{
+    year_id: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    year_id: number;
+}, {
+    year_id: number;
+}>;
+export type GetCalendarYearParams = z.infer<typeof GetCalendarYearParamsSchema>;
+export declare const ListBusinessYearsParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListBusinessYearsParams = z.infer<typeof ListBusinessYearsParamsSchema>;
+export declare const ListManualEntriesParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListManualEntriesParams = z.infer<typeof ListManualEntriesParamsSchema>;
+export declare const GetManualEntryParamsSchema: z.ZodObject<{
+    entry_id: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    entry_id: number;
+}, {
+    entry_id: number;
+}>;
+export type GetManualEntryParams = z.infer<typeof GetManualEntryParamsSchema>;
+/**
+ * Schema for creating a manual journal entry.
+ * Uses FLAT parameters for MCP interface - handler transforms to nested entries array.
+ * Bexio validates that debits equal credits server-side.
+ */
+export declare const CreateManualEntryParamsSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"manual_single_entry">>;
+    date: z.ZodString;
+    debit_account_id: z.ZodNumber;
+    credit_account_id: z.ZodNumber;
+    amount: z.ZodNumber;
+    description: z.ZodString;
+    reference_nr: z.ZodOptional<z.ZodString>;
+    tax_id: z.ZodOptional<z.ZodNumber>;
+    tax_account_id: z.ZodOptional<z.ZodNumber>;
+    currency_id: z.ZodOptional<z.ZodNumber>;
+    currency_factor: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "manual_single_entry";
+    date: string;
+    amount: number;
+    description: string;
+    debit_account_id: number;
+    credit_account_id: number;
+    currency_factor: number;
+    tax_id?: number | undefined;
+    currency_id?: number | undefined;
+    reference_nr?: string | undefined;
+    tax_account_id?: number | undefined;
+}, {
+    date: string;
+    amount: number;
+    description: string;
+    debit_account_id: number;
+    credit_account_id: number;
+    type?: "manual_single_entry" | undefined;
+    tax_id?: number | undefined;
+    currency_id?: number | undefined;
+    reference_nr?: string | undefined;
+    tax_account_id?: number | undefined;
+    currency_factor?: number | undefined;
+}>;
+export type CreateManualEntryParams = z.infer<typeof CreateManualEntryParamsSchema>;
+export declare const UpdateManualEntryParamsSchema: z.ZodObject<{
+    entry_id: z.ZodNumber;
+    entry_data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    entry_id: number;
+    entry_data: Record<string, unknown>;
+}, {
+    entry_id: number;
+    entry_data: Record<string, unknown>;
+}>;
+export type UpdateManualEntryParams = z.infer<typeof UpdateManualEntryParamsSchema>;
+export declare const DeleteManualEntryParamsSchema: z.ZodObject<{
+    entry_id: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    entry_id: number;
+}, {
+    entry_id: number;
+}>;
+export type DeleteManualEntryParams = z.infer<typeof DeleteManualEntryParamsSchema>;
+export declare const ListVatPeriodsParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type ListVatPeriodsParams = z.infer<typeof ListVatPeriodsParamsSchema>;
+export declare const GetJournalParamsSchema: z.ZodObject<{
+    start_date: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+    start_date?: string | undefined;
+    end_date?: string | undefined;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+    start_date?: string | undefined;
+    end_date?: string | undefined;
+}>;
+export type GetJournalParams = z.infer<typeof GetJournalParamsSchema>;

package/dist/types/schemas/accounting.js

@@ -0,0 +1,96 @@
+/**
+ * Accounting Zod schemas and types.
+ * Domain: Accounting (Accounts, Account Groups, Calendar Years, Business Years, Manual Entries, VAT Periods, Journal)
+ *
+ * Manual entries use flat MCP parameters - handlers transform to nested Bexio API structure.
+ * Bexio validates double-entry rules server-side (debits must equal credits).
+ */
+import { z } from "zod";
+// ===== ACCOUNTS - Chart of Accounts (ACCT-01) =====
+export const ListAccountsParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+export const GetAccountParamsSchema = z.object({
+    account_id: z.number().int().positive(),
+});
+export const CreateAccountParamsSchema = z.object({
+    account_no: z.number().int().positive({ message: "Account number is required and must be positive" }),
+    name: z.string().min(1, "Account name is required"),
+    account_group_id: z.number().int().positive({ message: "Account group ID is required" }),
+    is_active: z.boolean().default(true),
+    tax_id: z.number().int().positive().optional(),
+});
+export const SearchAccountsParamsSchema = z.object({
+    search_criteria: z.array(z.object({
+        field: z.string(),
+        value: z.union([z.string(), z.number(), z.boolean()]),
+        criteria: z.string().optional(),
+    })).min(1, "At least one search criterion is required"),
+});
+// ===== ACCOUNT GROUPS (ACCT-02) =====
+export const ListAccountGroupsParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+// ===== CALENDAR YEARS (ACCT-03) =====
+export const ListCalendarYearsParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+export const GetCalendarYearParamsSchema = z.object({
+    year_id: z.number().int().positive(),
+});
+// ===== BUSINESS YEARS (ACCT-04) =====
+export const ListBusinessYearsParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+// ===== MANUAL ENTRIES (ACCT-05) =====
+export const ListManualEntriesParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+export const GetManualEntryParamsSchema = z.object({
+    entry_id: z.number().int().positive(),
+});
+/**
+ * Schema for creating a manual journal entry.
+ * Uses FLAT parameters for MCP interface - handler transforms to nested entries array.
+ * Bexio validates that debits equal credits server-side.
+ */
+export const CreateManualEntryParamsSchema = z.object({
+    // Entry type - defaults to manual single entry
+    type: z.literal("manual_single_entry").default("manual_single_entry"),
+    // Required fields
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format"),
+    debit_account_id: z.number().int().positive({ message: "Debit account ID is required" }),
+    credit_account_id: z.number().int().positive({ message: "Credit account ID is required" }),
+    amount: z.number().positive({ message: "Amount must be positive" }),
+    description: z.string().min(1, "Description is required"),
+    // Optional fields
+    reference_nr: z.string().optional(),
+    tax_id: z.number().int().positive().optional(),
+    tax_account_id: z.number().int().positive().optional(),
+    currency_id: z.number().int().positive().optional(),
+    currency_factor: z.number().positive().default(1),
+});
+export const UpdateManualEntryParamsSchema = z.object({
+    entry_id: z.number().int().positive(),
+    entry_data: z.record(z.unknown()),
+});
+export const DeleteManualEntryParamsSchema = z.object({
+    entry_id: z.number().int().positive(),
+});
+// ===== VAT PERIODS (ACCT-06) =====
+export const ListVatPeriodsParamsSchema = z.object({
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});
+// ===== ACCOUNTING JOURNAL (ACCT-07) =====
+export const GetJournalParamsSchema = z.object({
+    start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD").optional(),
+    end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD").optional(),
+    limit: z.number().int().positive().default(100),
+    offset: z.number().int().min(0).default(0),
+});