@promptpartner/bexio-mcp-server 2.0.0

package/dist/tools/banking/definitions.js

@@ -0,0 +1,349 @@
+/**
+ * Banking tool definitions.
+ * Contains MCP tool metadata for banking domain.
+ *
+ * Swiss Standards:
+ * - IBAN payments: Swiss ISO 20022 payment standards
+ * - QR payments: SIX Group QR-bill specification v2.3
+ * - Addresses: Structured format only (type S) - required from Nov 2025
+ */
+export const toolDefinitions = [
+    // ===== BANK ACCOUNTS (Read-Only) =====
+    {
+        name: "list_bank_accounts",
+        description: "List all configured bank accounts in Bexio. Returns account details including IBAN, bank name, and currency. Use this to get valid bank_account_id values before creating payments.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of accounts to return (default: 100)",
+                    default: 100,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of accounts to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "get_bank_account",
+        description: "Get details of a specific bank account by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "integer",
+                    description: "The ID of the bank account to retrieve",
+                },
+            },
+            required: ["account_id"],
+        },
+    },
+    // ===== CURRENCIES =====
+    {
+        name: "list_currencies",
+        description: "List all currencies configured in Bexio. Returns currency codes (CHF, EUR, USD, etc.) with their rounding factors for invoicing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of currencies to return (default: 100)",
+                    default: 100,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of currencies to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "get_currency",
+        description: "Get details of a specific currency by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                currency_id: {
+                    type: "integer",
+                    description: "The ID of the currency to retrieve",
+                },
+            },
+            required: ["currency_id"],
+        },
+    },
+    {
+        name: "create_currency",
+        description: "Create a new currency in Bexio. Swiss default: round_factor 0.05 (5 rappen). Common currencies: CHF, EUR, USD, GBP.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Currency code (e.g., 'CHF', 'EUR', 'USD'). Max 10 characters.",
+                },
+                round_factor: {
+                    type: "number",
+                    description: "Rounding factor for amounts (default: 0.05 for Swiss 5 rappen)",
+                    default: 0.05,
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "update_currency",
+        description: "Update an existing currency's settings",
+        inputSchema: {
+            type: "object",
+            properties: {
+                currency_id: {
+                    type: "integer",
+                    description: "The ID of the currency to update",
+                },
+                currency_data: {
+                    type: "object",
+                    description: "Currency fields to update (e.g., round_factor)",
+                },
+            },
+            required: ["currency_id", "currency_data"],
+        },
+    },
+    {
+        name: "delete_currency",
+        description: "Delete a currency by ID. Cannot delete currencies in use by documents.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                currency_id: {
+                    type: "integer",
+                    description: "The ID of the currency to delete",
+                },
+            },
+            required: ["currency_id"],
+        },
+    },
+    // ===== IBAN PAYMENTS (Swiss ISO 20022) =====
+    {
+        name: "create_iban_payment",
+        description: "Create an IBAN payment (Swiss ISO 20022 standard). First use list_bank_accounts to get a valid bank_account_id. Only CHF and EUR currencies are supported. Recipient address must use structured format (street, house_number, zip, city, country_code).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                bank_account_id: {
+                    type: "integer",
+                    description: "ID of the bank account to pay from (use list_bank_accounts to find)",
+                },
+                iban: {
+                    type: "string",
+                    description: "Recipient IBAN (15-34 characters)",
+                },
+                currency: {
+                    type: "string",
+                    enum: ["CHF", "EUR"],
+                    description: "Payment currency (CHF or EUR only)",
+                },
+                amount: {
+                    type: "number",
+                    description: "Payment amount (positive number)",
+                },
+                recipient_name: {
+                    type: "string",
+                    description: "Recipient name (max 70 characters)",
+                },
+                recipient_street: {
+                    type: "string",
+                    description: "Street name (max 70 characters, optional)",
+                },
+                recipient_house_number: {
+                    type: "string",
+                    description: "House/building number (max 16 characters, optional)",
+                },
+                recipient_zip: {
+                    type: "string",
+                    description: "Postal/ZIP code (max 10 characters)",
+                },
+                recipient_city: {
+                    type: "string",
+                    description: "City name (max 35 characters)",
+                },
+                recipient_country_code: {
+                    type: "string",
+                    description: "ISO 3166-1 alpha-2 country code (default: CH)",
+                    default: "CH",
+                },
+                execution_date: {
+                    type: "string",
+                    description: "Payment execution date (YYYY-MM-DD format)",
+                },
+                message: {
+                    type: "string",
+                    description: "Payment message/reference (max 140 characters, optional)",
+                },
+                is_salary_payment: {
+                    type: "boolean",
+                    description: "Mark as salary payment (default: false)",
+                    default: false,
+                },
+                allowance_type: {
+                    type: "string",
+                    enum: ["no_fee", "our", "ben", "sha"],
+                    description: "Fee allocation: no_fee, our (sender pays), ben (beneficiary pays), sha (shared). Default: no_fee",
+                    default: "no_fee",
+                },
+            },
+            required: [
+                "bank_account_id",
+                "iban",
+                "currency",
+                "amount",
+                "recipient_name",
+                "recipient_zip",
+                "recipient_city",
+                "execution_date",
+            ],
+        },
+    },
+    {
+        name: "get_iban_payment",
+        description: "Get details of an IBAN payment by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payment_id: {
+                    type: "integer",
+                    description: "The ID of the IBAN payment to retrieve",
+                },
+            },
+            required: ["payment_id"],
+        },
+    },
+    {
+        name: "update_iban_payment",
+        description: "Update a pending IBAN payment. Only pending payments can be modified.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payment_id: {
+                    type: "integer",
+                    description: "The ID of the IBAN payment to update",
+                },
+                payment_data: {
+                    type: "object",
+                    description: "Payment fields to update",
+                },
+            },
+            required: ["payment_id", "payment_data"],
+        },
+    },
+    // ===== QR PAYMENTS (Swiss QR-invoice standard) =====
+    {
+        name: "create_qr_payment",
+        description: "Create a QR payment (Swiss QR-invoice standard per SIX Group spec v2.3). First use list_bank_accounts to get a valid bank_account_id. Only CHF and EUR currencies are supported. QR reference must be exactly 27 digits if provided. Recipient address must use structured format.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                bank_account_id: {
+                    type: "integer",
+                    description: "ID of the bank account to pay from (use list_bank_accounts to find)",
+                },
+                iban: {
+                    type: "string",
+                    description: "Recipient QR-IBAN (15-34 characters)",
+                },
+                currency: {
+                    type: "string",
+                    enum: ["CHF", "EUR"],
+                    description: "Payment currency (CHF or EUR only)",
+                },
+                amount: {
+                    type: "number",
+                    description: "Payment amount (positive, max 999999999.99)",
+                },
+                recipient_name: {
+                    type: "string",
+                    description: "Recipient name (max 70 characters)",
+                },
+                recipient_street: {
+                    type: "string",
+                    description: "Street name (max 70 characters, optional)",
+                },
+                recipient_house_number: {
+                    type: "string",
+                    description: "House/building number (max 16 characters, optional)",
+                },
+                recipient_zip: {
+                    type: "string",
+                    description: "Postal/ZIP code (max 10 characters)",
+                },
+                recipient_city: {
+                    type: "string",
+                    description: "City name (max 35 characters)",
+                },
+                recipient_country_code: {
+                    type: "string",
+                    description: "ISO 3166-1 alpha-2 country code (default: CH)",
+                    default: "CH",
+                },
+                execution_date: {
+                    type: "string",
+                    description: "Payment execution date (YYYY-MM-DD format)",
+                },
+                qr_reference_nr: {
+                    type: "string",
+                    description: "QR reference number (exactly 27 digits, optional)",
+                },
+                additional_information: {
+                    type: "string",
+                    description: "Additional payment information (max 140 characters, optional)",
+                },
+            },
+            required: [
+                "bank_account_id",
+                "iban",
+                "currency",
+                "amount",
+                "recipient_name",
+                "recipient_zip",
+                "recipient_city",
+                "execution_date",
+            ],
+        },
+    },
+    {
+        name: "get_qr_payment",
+        description: "Get details of a QR payment by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payment_id: {
+                    type: "integer",
+                    description: "The ID of the QR payment to retrieve",
+                },
+            },
+            required: ["payment_id"],
+        },
+    },
+    {
+        name: "update_qr_payment",
+        description: "Update a pending QR payment. Only pending payments can be modified.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payment_id: {
+                    type: "integer",
+                    description: "The ID of the QR payment to update",
+                },
+                payment_data: {
+                    type: "object",
+                    description: "Payment fields to update",
+                },
+            },
+            required: ["payment_id", "payment_data"],
+        },
+    },
+];

package/dist/tools/banking/handlers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Banking tool handlers.
+ * Implements the logic for each banking tool.
+ *
+ * Payment handlers transform flat MCP params to nested Bexio API structure.
+ */
+import { BexioClient } from "../../bexio-client.js";
+export type HandlerFn = (client: BexioClient, args: unknown) => Promise<unknown>;
+export declare const handlers: Record<string, HandlerFn>;

package/dist/tools/banking/handlers.js

@@ -0,0 +1,123 @@
+/**
+ * Banking tool handlers.
+ * Implements the logic for each banking tool.
+ *
+ * Payment handlers transform flat MCP params to nested Bexio API structure.
+ */
+import { McpError } from "../../shared/errors.js";
+import { ListBankAccountsParamsSchema, GetBankAccountParamsSchema, ListCurrenciesParamsSchema, GetCurrencyParamsSchema, CreateCurrencyParamsSchema, UpdateCurrencyParamsSchema, DeleteCurrencyParamsSchema, CreateIbanPaymentParamsSchema, GetIbanPaymentParamsSchema, UpdateIbanPaymentParamsSchema, CreateQrPaymentParamsSchema, GetQrPaymentParamsSchema, UpdateQrPaymentParamsSchema, } from "../../types/index.js";
+export const handlers = {
+    // ===== BANK ACCOUNTS (Read-Only) =====
+    list_bank_accounts: async (client, args) => {
+        const params = ListBankAccountsParamsSchema.parse(args);
+        return client.listBankAccounts(params);
+    },
+    get_bank_account: async (client, args) => {
+        const { account_id } = GetBankAccountParamsSchema.parse(args);
+        const account = await client.getBankAccount(account_id);
+        if (!account) {
+            throw McpError.notFound("Bank account", account_id);
+        }
+        return account;
+    },
+    // ===== CURRENCIES =====
+    list_currencies: async (client, args) => {
+        const params = ListCurrenciesParamsSchema.parse(args);
+        return client.listCurrencies(params);
+    },
+    get_currency: async (client, args) => {
+        const { currency_id } = GetCurrencyParamsSchema.parse(args);
+        const currency = await client.getCurrency(currency_id);
+        if (!currency) {
+            throw McpError.notFound("Currency", currency_id);
+        }
+        return currency;
+    },
+    create_currency: async (client, args) => {
+        const params = CreateCurrencyParamsSchema.parse(args);
+        return client.createCurrency(params);
+    },
+    update_currency: async (client, args) => {
+        const { currency_id, currency_data } = UpdateCurrencyParamsSchema.parse(args);
+        return client.updateCurrency(currency_id, currency_data);
+    },
+    delete_currency: async (client, args) => {
+        const { currency_id } = DeleteCurrencyParamsSchema.parse(args);
+        return client.deleteCurrency(currency_id);
+    },
+    // ===== IBAN PAYMENTS (Swiss ISO 20022) =====
+    create_iban_payment: async (client, args) => {
+        const params = CreateIbanPaymentParamsSchema.parse(args);
+        // Transform flat params to Bexio API nested structure
+        const paymentData = {
+            bank_account_id: params.bank_account_id,
+            iban: params.iban,
+            instructed_amount: {
+                currency: params.currency,
+                amount: params.amount,
+            },
+            recipient: {
+                name: params.recipient_name,
+                street: params.recipient_street,
+                house_number: params.recipient_house_number,
+                zip: params.recipient_zip,
+                city: params.recipient_city,
+                country_code: params.recipient_country_code,
+            },
+            execution_date: params.execution_date,
+            message: params.message,
+            is_salary_payment: params.is_salary_payment,
+            allowance_type: params.allowance_type,
+        };
+        return client.createIbanPayment(paymentData);
+    },
+    get_iban_payment: async (client, args) => {
+        const { payment_id } = GetIbanPaymentParamsSchema.parse(args);
+        const payment = await client.getIbanPayment(payment_id);
+        if (!payment) {
+            throw McpError.notFound("IBAN payment", payment_id);
+        }
+        return payment;
+    },
+    update_iban_payment: async (client, args) => {
+        const { payment_id, payment_data } = UpdateIbanPaymentParamsSchema.parse(args);
+        return client.updateIbanPayment(payment_id, payment_data);
+    },
+    // ===== QR PAYMENTS (Swiss QR-invoice standard) =====
+    create_qr_payment: async (client, args) => {
+        const params = CreateQrPaymentParamsSchema.parse(args);
+        // Transform flat params to Bexio API nested structure
+        const paymentData = {
+            bank_account_id: params.bank_account_id,
+            iban: params.iban,
+            instructed_amount: {
+                currency: params.currency,
+                amount: params.amount,
+            },
+            recipient: {
+                name: params.recipient_name,
+                street: params.recipient_street,
+                house_number: params.recipient_house_number,
+                zip: params.recipient_zip,
+                city: params.recipient_city,
+                country_code: params.recipient_country_code,
+            },
+            execution_date: params.execution_date,
+            qr_reference_nr: params.qr_reference_nr,
+            additional_information: params.additional_information,
+        };
+        return client.createQrPayment(paymentData);
+    },
+    get_qr_payment: async (client, args) => {
+        const { payment_id } = GetQrPaymentParamsSchema.parse(args);
+        const payment = await client.getQrPayment(payment_id);
+        if (!payment) {
+            throw McpError.notFound("QR payment", payment_id);
+        }
+        return payment;
+    },
+    update_qr_payment: async (client, args) => {
+        const { payment_id, payment_data } = UpdateQrPaymentParamsSchema.parse(args);
+        return client.updateQrPayment(payment_id, payment_data);
+    },
+};

package/dist/tools/banking/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Banking domain barrel export.
+ * Exports tool definitions and handlers for banking operations.
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

package/dist/tools/banking/index.js

@@ -0,0 +1,6 @@
+/**
+ * Banking domain barrel export.
+ * Exports tool definitions and handlers for banking operations.
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

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

@@ -0,0 +1,7 @@
+/**
+ * Company and payments config tool definitions.
+ * Contains MCP tool metadata for company domain.
+ * Includes: Company Profile, Permissions, Payment Types
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const toolDefinitions: Tool[];

package/dist/tools/company/definitions.js

@@ -0,0 +1,87 @@
+/**
+ * Company and payments config tool definitions.
+ * Contains MCP tool metadata for company domain.
+ * Includes: Company Profile, Permissions, Payment Types
+ */
+export const toolDefinitions = [
+    // ===== COMPANY PROFILE (REFDATA-09) =====
+    {
+        name: "get_company_profile",
+        description: "Get the company profile including name, address, and settings",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "update_company_profile",
+        description: "Update company profile settings",
+        inputSchema: {
+            type: "object",
+            properties: {
+                profile_data: {
+                    type: "object",
+                    description: "Profile fields to update",
+                },
+            },
+            required: ["profile_data"],
+        },
+    },
+    // ===== PERMISSIONS (REFDATA-10) =====
+    {
+        name: "list_permissions",
+        description: "List all available user permissions in the Bexio account",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    // ===== PAYMENT TYPES (REFDATA-08) =====
+    {
+        name: "list_payment_types",
+        description: "List all payment types available for invoices and payments",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of results to return (default: 100)",
+                    default: 100,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of results to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "get_payment_type",
+        description: "Get a specific payment type by ID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payment_type_id: {
+                    type: "integer",
+                    description: "The ID of the payment type to retrieve",
+                },
+            },
+            required: ["payment_type_id"],
+        },
+    },
+    {
+        name: "create_payment_type",
+        description: "Create a new payment type for invoices and payments",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "The name of the payment type (e.g., 'Bank Transfer', 'Cash', 'Credit Card')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+];

package/dist/tools/company/handlers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Company and payments config tool handlers.
+ * Implements the logic for each company domain tool.
+ */
+import { BexioClient } from "../../bexio-client.js";
+export type HandlerFn = (client: BexioClient, args: unknown) => Promise<unknown>;
+export declare const handlers: Record<string, HandlerFn>;

package/dist/tools/company/handlers.js

@@ -0,0 +1,31 @@
+/**
+ * Company and payments config tool handlers.
+ * Implements the logic for each company domain tool.
+ */
+import { GetCompanyProfileParamsSchema, UpdateCompanyProfileParamsSchema, ListPermissionsParamsSchema, ListPaymentTypesParamsSchema, GetPaymentTypeParamsSchema, CreatePaymentTypeParamsSchema, } from "../../types/index.js";
+export const handlers = {
+    get_company_profile: async (client, args) => {
+        GetCompanyProfileParamsSchema.parse(args);
+        return client.getCompanyProfile();
+    },
+    update_company_profile: async (client, args) => {
+        const { profile_data } = UpdateCompanyProfileParamsSchema.parse(args);
+        return client.updateCompanyProfile(profile_data);
+    },
+    list_permissions: async (client, args) => {
+        ListPermissionsParamsSchema.parse(args);
+        return client.listPermissions();
+    },
+    list_payment_types: async (client, args) => {
+        const params = ListPaymentTypesParamsSchema.parse(args);
+        return client.listPaymentTypes(params);
+    },
+    get_payment_type: async (client, args) => {
+        const { payment_type_id } = GetPaymentTypeParamsSchema.parse(args);
+        return client.getPaymentType(payment_type_id);
+    },
+    create_payment_type: async (client, args) => {
+        const { name } = CreatePaymentTypeParamsSchema.parse(args);
+        return client.createPaymentType({ name });
+    },
+};

package/dist/tools/company/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Company domain barrel export.
+ * Re-exports tool definitions and handlers for company domain.
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

package/dist/tools/company/index.js

@@ -0,0 +1,6 @@
+/**
+ * Company domain barrel export.
+ * Re-exports tool definitions and handlers for company domain.
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

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

@@ -0,0 +1,6 @@
+/**
+ * Contact tool definitions.
+ * Contains MCP tool metadata for contacts domain.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const toolDefinitions: Tool[];