@promptpartner/bexio-mcp-server 2.0.0

package/dist/tools/payroll/definitions.js

@@ -0,0 +1,239 @@
+/**
+ * Payroll tool definitions.
+ * Contains MCP tool metadata for payroll domain.
+ *
+ * IMPORTANT: Payroll module requires a Bexio subscription with payroll features.
+ * All tools check module availability on first call and cache the result.
+ * When unavailable, tools return a friendly error explaining how to enable payroll.
+ *
+ * 10 tools total:
+ * - Employees: 4 tools (list, get, create, update)
+ * - Absences: 5 tools (list, get, create, update, delete)
+ * - Payroll Documents: 1 tool (list)
+ */
+export const toolDefinitions = [
+    // ===== EMPLOYEES (PAY-01) =====
+    {
+        name: "list_employees",
+        description: "List employees in the payroll system. Requires Bexio Payroll module subscription. Use to get employee IDs for timesheets and absences.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of results to return (default: 50)",
+                    default: 50,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of results to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "get_employee",
+        description: "Get a specific employee by ID. Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                employee_id: {
+                    type: "integer",
+                    description: "The ID of the employee to retrieve",
+                },
+            },
+            required: ["employee_id"],
+        },
+    },
+    {
+        name: "create_employee",
+        description: "Create a new employee in the payroll system. Requires Bexio Payroll module subscription. Links a Bexio user to payroll.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                user_id: {
+                    type: "integer",
+                    description: "The ID of the Bexio user to create as an employee",
+                },
+                first_name: {
+                    type: "string",
+                    description: "Employee's first name",
+                },
+                last_name: {
+                    type: "string",
+                    description: "Employee's last name",
+                },
+                email: {
+                    type: "string",
+                    description: "Employee's email address",
+                },
+                hourly_rate: {
+                    type: "number",
+                    description: "Hourly rate for the employee",
+                },
+                start_date: {
+                    type: "string",
+                    description: "Employment start date in YYYY-MM-DD format",
+                },
+                end_date: {
+                    type: "string",
+                    description: "Employment end date in YYYY-MM-DD format (for terminations)",
+                },
+            },
+            required: ["user_id"],
+        },
+    },
+    {
+        name: "update_employee",
+        description: "Update an existing employee. Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                employee_id: {
+                    type: "integer",
+                    description: "The ID of the employee to update",
+                },
+                employee_data: {
+                    type: "object",
+                    description: "The data to update on the employee (e.g., hourly_rate, end_date)",
+                },
+            },
+            required: ["employee_id", "employee_data"],
+        },
+    },
+    // ===== ABSENCES (PAY-02) =====
+    {
+        name: "list_absences",
+        description: "List employee absences (vacation, sick leave, etc.). Requires Bexio Payroll module subscription. Optional year filter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                year: {
+                    type: "integer",
+                    description: "Filter absences by year (e.g., 2024)",
+                },
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of results to return (default: 50)",
+                    default: 50,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of results to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "get_absence",
+        description: "Get a specific absence record by ID. Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                absence_id: {
+                    type: "integer",
+                    description: "The ID of the absence to retrieve",
+                },
+            },
+            required: ["absence_id"],
+        },
+    },
+    {
+        name: "create_absence",
+        description: "Create a new absence record (vacation, sick leave, etc.). Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                user_id: {
+                    type: "integer",
+                    description: "The ID of the user/employee for this absence",
+                },
+                absence_type_id: {
+                    type: "integer",
+                    description: "The type of absence (vacation, sick, etc.) - use list_absences to find types",
+                },
+                start_date: {
+                    type: "string",
+                    description: "Absence start date in YYYY-MM-DD format",
+                },
+                end_date: {
+                    type: "string",
+                    description: "Absence end date in YYYY-MM-DD format",
+                },
+                half_day_start: {
+                    type: "boolean",
+                    description: "True if absence starts at midday (default: false)",
+                    default: false,
+                },
+                half_day_end: {
+                    type: "boolean",
+                    description: "True if absence ends at midday (default: false)",
+                    default: false,
+                },
+                note: {
+                    type: "string",
+                    description: "Optional note for this absence",
+                },
+            },
+            required: ["user_id", "absence_type_id", "start_date", "end_date"],
+        },
+    },
+    {
+        name: "update_absence",
+        description: "Update an existing absence record. Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                absence_id: {
+                    type: "integer",
+                    description: "The ID of the absence to update",
+                },
+                absence_data: {
+                    type: "object",
+                    description: "The data to update (e.g., end_date, note)",
+                },
+            },
+            required: ["absence_id", "absence_data"],
+        },
+    },
+    {
+        name: "delete_absence",
+        description: "Delete an absence record. Requires Bexio Payroll module subscription.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                absence_id: {
+                    type: "integer",
+                    description: "The ID of the absence to delete",
+                },
+            },
+            required: ["absence_id"],
+        },
+    },
+    // ===== PAYROLL DOCUMENTS (PAY-03) =====
+    {
+        name: "list_payroll_documents",
+        description: "List payroll documents (payslips, etc.). Requires Bexio Payroll module subscription. Optional employee filter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                employee_id: {
+                    type: "integer",
+                    description: "Filter by employee ID to see only their documents",
+                },
+                limit: {
+                    type: "integer",
+                    description: "Maximum number of results to return (default: 50)",
+                    default: 50,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Number of results to skip (default: 0)",
+                    default: 0,
+                },
+            },
+        },
+    },
+];

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

@@ -0,0 +1,14 @@
+/**
+ * Payroll tool handlers.
+ * Implements the logic for each payroll tool with module detection.
+ *
+ * IMPORTANT: Payroll module is conditional - not all Bexio subscriptions include it.
+ * Uses probe-on-first-call pattern: attempts listEmployees(limit=1) to detect availability.
+ * Result is cached for the session to avoid repeated probes.
+ *
+ * When module is unavailable (403/404), returns a friendly error message explaining
+ * what the payroll module provides and how to enable it in Bexio settings.
+ */
+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/payroll/handlers.js

@@ -0,0 +1,152 @@
+/**
+ * Payroll tool handlers.
+ * Implements the logic for each payroll tool with module detection.
+ *
+ * IMPORTANT: Payroll module is conditional - not all Bexio subscriptions include it.
+ * Uses probe-on-first-call pattern: attempts listEmployees(limit=1) to detect availability.
+ * Result is cached for the session to avoid repeated probes.
+ *
+ * When module is unavailable (403/404), returns a friendly error message explaining
+ * what the payroll module provides and how to enable it in Bexio settings.
+ */
+import { McpError } from "../../shared/errors.js";
+import { 
+// Employees
+ListEmployeesParamsSchema, GetEmployeeParamsSchema, CreateEmployeeParamsSchema, UpdateEmployeeParamsSchema, 
+// Absences
+ListAbsencesParamsSchema, GetAbsenceParamsSchema, CreateAbsenceParamsSchema, UpdateAbsenceParamsSchema, DeleteAbsenceParamsSchema, 
+// Payroll Documents
+ListPayrollDocumentsParamsSchema, } from "../../types/index.js";
+import { logger } from "../../logger.js";
+// ===== MODULE AVAILABILITY DETECTION =====
+/**
+ * Cached result of payroll module availability check.
+ * null = not yet checked, true = available, false = unavailable
+ */
+let payrollModuleAvailable = null;
+/**
+ * Check if the Bexio Payroll module is available.
+ * Uses probe-on-first-call pattern: attempts a minimal API call to detect access.
+ * Result is cached for the session to avoid repeated probes.
+ */
+async function checkPayrollModule(client) {
+    // Return cached result if already checked
+    if (payrollModuleAvailable !== null) {
+        return payrollModuleAvailable;
+    }
+    try {
+        // Probe with a minimal request - just fetch 1 employee
+        await client.listEmployees({ limit: 1, offset: 0 });
+        logger.debug("Payroll module is available");
+        payrollModuleAvailable = true;
+        return true;
+    }
+    catch (error) {
+        // Check if the error indicates the module is unavailable
+        if (error instanceof McpError) {
+            const status = error.statusCode;
+            // 403 Forbidden or 404 Not Found typically mean module not enabled
+            if (status === 403 || status === 404) {
+                logger.debug("Payroll module is not available", { status });
+                payrollModuleAvailable = false;
+                return false;
+            }
+        }
+        // For other errors (network, 500, etc.), don't cache - let them propagate
+        throw error;
+    }
+}
+/**
+ * Create a user-friendly error for when the payroll module is not available.
+ * Explains what the module provides and how to enable it.
+ */
+function payrollUnavailableError() {
+    return new McpError("BEXIO_API_ERROR", `Payroll module is not enabled for your Bexio account.
+
+The Payroll module provides:
+- Employee management (work contracts, hourly rates)
+- Absence tracking (vacation, sick leave, etc.)
+- Payroll documents (payslips, tax statements)
+
+To enable the Payroll module:
+1. Go to Bexio Settings > Subscriptions
+2. Select a plan that includes Payroll features
+3. Contact Bexio support if you need help choosing the right plan
+
+Note: Payroll features are typically available in Bexio Pro and Enterprise plans.
+Visit https://www.bexio.com/en/pricing for plan details.`, { module: "payroll", available: false });
+}
+/**
+ * Ensure payroll module is available before executing an operation.
+ * Throws a friendly error if the module is not enabled.
+ */
+async function ensurePayrollAvailable(client) {
+    const available = await checkPayrollModule(client);
+    if (!available) {
+        throw payrollUnavailableError();
+    }
+}
+// ===== HANDLERS =====
+export const handlers = {
+    // ===== EMPLOYEES (PAY-01) =====
+    list_employees: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const params = ListEmployeesParamsSchema.parse(args);
+        return client.listEmployees(params);
+    },
+    get_employee: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const { employee_id } = GetEmployeeParamsSchema.parse(args);
+        const employee = await client.getEmployee(employee_id);
+        if (!employee) {
+            throw McpError.notFound("Employee", employee_id);
+        }
+        return employee;
+    },
+    create_employee: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const params = CreateEmployeeParamsSchema.parse(args);
+        return client.createEmployee(params);
+    },
+    update_employee: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const { employee_id, employee_data } = UpdateEmployeeParamsSchema.parse(args);
+        return client.updateEmployee(employee_id, employee_data);
+    },
+    // ===== ABSENCES (PAY-02) =====
+    list_absences: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const params = ListAbsencesParamsSchema.parse(args);
+        return client.listAbsences(params);
+    },
+    get_absence: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const { absence_id } = GetAbsenceParamsSchema.parse(args);
+        const absence = await client.getAbsence(absence_id);
+        if (!absence) {
+            throw McpError.notFound("Absence", absence_id);
+        }
+        return absence;
+    },
+    create_absence: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const params = CreateAbsenceParamsSchema.parse(args);
+        return client.createAbsence(params);
+    },
+    update_absence: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const { absence_id, absence_data } = UpdateAbsenceParamsSchema.parse(args);
+        return client.updateAbsence(absence_id, absence_data);
+    },
+    delete_absence: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const { absence_id } = DeleteAbsenceParamsSchema.parse(args);
+        return client.deleteAbsence(absence_id);
+    },
+    // ===== PAYROLL DOCUMENTS (PAY-03) =====
+    list_payroll_documents: async (client, args) => {
+        await ensurePayrollAvailable(client);
+        const params = ListPayrollDocumentsParamsSchema.parse(args);
+        return client.listPayrollDocuments(params);
+    },
+};

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

@@ -0,0 +1,16 @@
+/**
+ * Payroll domain module.
+ * Exports tool definitions and handlers for payroll operations.
+ *
+ * CONDITIONAL MODULE: Payroll requires a Bexio subscription with payroll features.
+ * All handlers check module availability on first call using probe pattern.
+ * When unavailable, returns friendly error with upgrade instructions.
+ *
+ * PAY-01: Employees - 4 tools (list, get, create, update)
+ * PAY-02: Absences - 5 tools (list, get, create, update, delete)
+ * PAY-03: Payroll Documents - 1 tool (list)
+ *
+ * Total: 10 tools
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

package/dist/tools/payroll/index.js

@@ -0,0 +1,16 @@
+/**
+ * Payroll domain module.
+ * Exports tool definitions and handlers for payroll operations.
+ *
+ * CONDITIONAL MODULE: Payroll requires a Bexio subscription with payroll features.
+ * All handlers check module availability on first call using probe pattern.
+ * When unavailable, returns friendly error with upgrade instructions.
+ *
+ * PAY-01: Employees - 4 tools (list, get, create, update)
+ * PAY-02: Absences - 5 tools (list, get, create, update, delete)
+ * PAY-03: Payroll Documents - 1 tool (list)
+ *
+ * Total: 10 tools
+ */
+export { toolDefinitions } from "./definitions.js";
+export { handlers } from "./handlers.js";

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

@@ -0,0 +1,7 @@
+/**
+ * Projects tool definitions.
+ * Contains MCP tool metadata for projects domain.
+ * Includes: Projects (CRUD, archive, search), Project Types, Project Statuses, Milestones, Work Packages
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const toolDefinitions: Tool[];