payrolla-mcp 0.2.4 → 0.2.6

package/README.md

@@ -55,15 +55,19 @@ Calculate payroll for a single employee.
 - `month` - Starting month (1-12)
 - `periodCount` - Number of months (optional, default: 1)
 - `ssiType` - SSI type: 'S4A', 'S4B', or 'S4C' (optional, default: 'S4A')
-- `extraPayments` - Array of extra payments (optional)
+- `extraPayments` - Array of extra payments (optional, supports `paymentType` = RegularPayment/Overtime/SocialAid/ExtraPay)
 - `customParams` - Custom global parameters (optional)
+- `cumulativeIncomeTaxBase` - Starting income tax base to carry over
+- `cumulativeMinWageIncomeTaxBase` - Starting minimum wage income tax base to carry over
+- `transferredSSIBase1` - Starting transferred SSI base 1
+- `transferredSSIBase2` - Starting transferred SSI base 2
 
 ### calculate_bulk_payroll
 
 Calculate payroll for multiple employees with shared parameters.
 
 **Input:**
-- `employees` - Array of employee objects
+- `employees` - Array of employee objects (each can include extra payments with `paymentType` and starting cumulative/transfer bases)
 - `year` - Calculation year
 - `month` - Starting month
 - `periodCount` - Number of months (use 12 for yearly)
@@ -120,4 +124,4 @@ Plan yearly payroll considering potential changes.
 
 ```
 User: I have 3 employees: Ali 35k net, Ayse 45k net, Mehmet 60k gross.
-      What's my yearly budget if I give 10% raise and minimum wage becomes 30k?
+      What's my yearly budget if I give 10% raise and minimum wage becomes 30k?

package/dist/index.js

@@ -30,6 +30,23 @@ function mapSSIType(ssiType) {
 function mapCalculationType(calcType) {
   return calcType === "Gross" ? CalculationType.Gross : CalculationType.Net;
 }
+function mapPaymentType(paymentType) {
+  switch (paymentType) {
+    case 1:
+    case "RegularPayment":
+      return PaymentType.RegularPayment;
+    case 2:
+    case "Overtime":
+      return PaymentType.Overtime;
+    case 3:
+    case "SocialAid":
+      return PaymentType.SocialAid;
+    case 4:
+    case "ExtraPay":
+    default:
+      return PaymentType.ExtraPay;
+  }
+}
 function buildCustomGlobalParams(customParams) {
   if (!customParams) return void 0;
   return {
@@ -50,7 +67,11 @@ async function calculatePayroll(client, input) {
     month,
     periodCount = 1,
     extraPayments,
-    customParams
+    customParams,
+    cumulativeIncomeTaxBase = 0,
+    cumulativeMinWageIncomeTaxBase = 0,
+    transferredSSIBase1 = 0,
+    transferredSSIBase2 = 0
   } = input;
   const payments = [
     {
@@ -66,21 +87,17 @@ async function calculatePayroll(client, input) {
       payments.push({
         paymentAmount: extra.amount,
         paymentName: extra.name,
-        paymentType: PaymentType.ExtraPay,
+        paymentType: mapPaymentType(extra.paymentType),
         paymentRef: `extra_${i + 2}`,
         calculationType: extra.type === "Net" ? CalculationType.Net : CalculationType.Gross
       });
     }
   }
-  const model = {
-    calcDate: `${year}-${String(month).padStart(2, "0")}-01`,
+  const baseModel = {
     wageAmount: wage,
-    cumulativeIncomeTaxBase: 0,
-    cumulativeMinWageIncomeTaxBase: 0,
     ssiType: mapSSIType(ssiType),
     wageCalculationType: mapCalculationType(calculationType),
     wagePeriodType: PaymentPeriodType.Monthly,
-    periodCount,
     periodLengthType: PeriodLengthType.Month,
     payments,
     calculationParams: {
@@ -88,16 +105,40 @@ async function calculatePayroll(client, input) {
       customGlobalParams: buildCustomGlobalParams(customParams)
     }
   };
-  const result = await client.calculate(model);
   let totalCost = 0;
   let totalNet = 0;
   let totalGross = 0;
   const periods = [];
-  for (const payroll of result.payrolls) {
+  let incomeTaxBase = cumulativeIncomeTaxBase;
+  let minWageIncomeTaxBase = cumulativeMinWageIncomeTaxBase;
+  let transferredBase1 = transferredSSIBase1;
+  let transferredBase2 = transferredSSIBase2;
+  for (let i = 0; i < periodCount; i++) {
+    const calcDate = new Date(year, month - 1 + i, 1);
+    const calcYear = calcDate.getFullYear();
+    const calcMonth = calcDate.getMonth() + 1;
+    const model = {
+      ...baseModel,
+      calcDate: `${calcYear}-${String(calcMonth).padStart(2, "0")}-01`,
+      cumulativeIncomeTaxBase: incomeTaxBase,
+      cumulativeMinWageIncomeTaxBase: minWageIncomeTaxBase,
+      transferredSSIBase1: transferredBase1,
+      transferredSSIBase2: transferredBase2,
+      periodCount: 1
+    };
+    const result = await client.calculate(model);
+    const payroll = result.payrolls?.[0];
+    if (!payroll) {
+      throw new Error("Payrolla calculation returned no payroll data");
+    }
     const pr = payroll.payrollResult;
     totalCost += payroll.totalCost;
     totalNet += pr.totalNet;
     totalGross += pr.totalGross;
+    const nextIncomeTaxBase = incomeTaxBase + pr.totalIncomeTaxBase;
+    const nextMinWageIncomeTaxBase = pr.totalMinWageIncomeTaxExemptionBase;
+    const nextTransferredBase1 = pr.transferredSSIBase1 ?? transferredBase1;
+    const nextTransferredBase2 = pr.transferredSSIBase2 ?? transferredBase2;
     periods.push({
       year: payroll.year,
       month: payroll.month,
@@ -107,8 +148,16 @@ async function calculatePayroll(client, input) {
       incomeTax: pr.totalIncomeTax,
       stampTax: pr.totalStampTax,
       employeeSSI: pr.totalSSIWorkerPrem,
-      employerSSI: pr.totalSSIEmployerPrem
+      employerSSI: pr.totalSSIEmployerPrem,
+      cumulativeIncomeTaxBase: nextIncomeTaxBase,
+      cumulativeMinWageIncomeTaxBase: nextMinWageIncomeTaxBase,
+      transferredSSIBase1: nextTransferredBase1,
+      transferredSSIBase2: nextTransferredBase2
     });
+    incomeTaxBase = nextIncomeTaxBase;
+    minWageIncomeTaxBase = nextMinWageIncomeTaxBase;
+    transferredBase1 = nextTransferredBase1;
+    transferredBase2 = nextTransferredBase2;
   }
   return {
     employee: name,
@@ -134,7 +183,11 @@ async function calculateBulkPayroll(client, input) {
       month,
       periodCount,
       extraPayments: emp.extraPayments,
-      customParams
+      customParams,
+      cumulativeIncomeTaxBase: emp.cumulativeIncomeTaxBase,
+      cumulativeMinWageIncomeTaxBase: emp.cumulativeMinWageIncomeTaxBase,
+      transferredSSIBase1: emp.transferredSSIBase1,
+      transferredSSIBase2: emp.transferredSSIBase2
     });
     employeeResults.push({
       name: result.employee,
@@ -228,34 +281,68 @@ async function simulateBudget(client, input) {
   const { employees, year, periodCount, scenario } = input;
   const defaults = getDefaultParams({ year });
   const customParams = applyScenario(defaults, scenario);
-  const adjustedEmployees = employees.map((emp) => ({
-    name: emp.name,
-    wage: applyRaise(emp.wage, scenario.salaryRaisePercent),
-    calculationType: emp.calculationType,
-    originalWage: emp.wage
-  }));
-  const result = await calculateBulkPayroll(client, {
-    employees: adjustedEmployees.map((emp) => ({
-      name: emp.name,
-      wage: emp.wage,
-      calculationType: emp.calculationType
-    })),
-    year,
-    month: 1,
-    periodCount,
-    customParams
-  });
-  const employeeResults = adjustedEmployees.map((emp, index) => {
-    const empResult = result.employees[index];
-    return {
+  const employeeResults = [];
+  let totalYearlyCost = 0;
+  let totalYearlyNet = 0;
+  let totalYearlyGross = 0;
+  for (const emp of employees) {
+    const adjustedWage = applyRaise(emp.wage, scenario.salaryRaisePercent);
+    let cumulativeIncomeTaxBase = 0;
+    let cumulativeMinWageIncomeTaxBase = 0;
+    let transferredSSIBase1 = 0;
+    let transferredSSIBase2 = 0;
+    let empTotalCost = 0;
+    let empTotalNet = 0;
+    let empTotalGross = 0;
+    for (let i = 0; i < periodCount; i++) {
+      const calcDate = new Date(year, i, 1);
+      const calcYear = calcDate.getFullYear();
+      const calcMonth = calcDate.getMonth() + 1;
+      const periodPayEvents = (emp.payEvents || []).filter(
+        (pe) => pe.year === calcYear && pe.month === calcMonth
+      );
+      const extraPayments = periodPayEvents.map((pe) => ({
+        name: pe.name,
+        amount: pe.amount,
+        type: pe.type,
+        paymentType: pe.paymentType
+      }));
+      const result = await calculatePayroll(client, {
+        name: emp.name,
+        wage: adjustedWage,
+        calculationType: emp.calculationType,
+        ssiType: emp.ssiType,
+        year: calcYear,
+        month: calcMonth,
+        periodCount: 1,
+        extraPayments: extraPayments.length > 0 ? extraPayments : void 0,
+        customParams,
+        cumulativeIncomeTaxBase,
+        cumulativeMinWageIncomeTaxBase,
+        transferredSSIBase1,
+        transferredSSIBase2
+      });
+      empTotalCost += result.totalCost;
+      empTotalNet += result.totalNet;
+      empTotalGross += result.totalGross;
+      const lastPeriod = result.periods[0];
+      cumulativeIncomeTaxBase = lastPeriod.cumulativeIncomeTaxBase;
+      cumulativeMinWageIncomeTaxBase = lastPeriod.cumulativeMinWageIncomeTaxBase;
+      transferredSSIBase1 = lastPeriod.transferredSSIBase1;
+      transferredSSIBase2 = lastPeriod.transferredSSIBase2;
+    }
+    employeeResults.push({
       name: emp.name,
-      originalWage: emp.originalWage,
-      adjustedWage: emp.wage,
-      yearlyCost: empResult.totalCost,
-      yearlyNet: empResult.totalNet,
-      yearlyGross: empResult.totalGross
-    };
-  });
+      originalWage: emp.wage,
+      adjustedWage,
+      yearlyCost: empTotalCost,
+      yearlyNet: empTotalNet,
+      yearlyGross: empTotalGross
+    });
+    totalYearlyCost += empTotalCost;
+    totalYearlyNet += empTotalNet;
+    totalYearlyGross += empTotalGross;
+  }
   const effectiveTaxBrackets = customParams.incomeTaxLimits || defaults.incomeTaxBrackets.map((b) => ({
     limit: b.limit,
     rate: b.rate
@@ -267,10 +354,10 @@ async function simulateBudget(client, input) {
       effectiveTaxBrackets
     },
     summary: {
-      totalYearlyCost: result.summary.totalYearlyCost,
-      totalYearlyNet: result.summary.totalYearlyNet,
-      totalYearlyGross: result.summary.totalYearlyGross,
-      costPerEmployee: result.summary.totalYearlyCost / employees.length
+      totalYearlyCost,
+      totalYearlyNet,
+      totalYearlyGross,
+      costPerEmployee: totalYearlyCost / employees.length
     },
     employees: employeeResults
   };
@@ -492,7 +579,28 @@ function registerPrompts(server) {
 var ExtraPaymentSchema = z2.object({
   name: z2.string().describe("Name of the extra payment"),
   amount: z2.number().describe("Payment amount"),
-  type: z2.enum(["Net", "Gross"]).describe("Payment type")
+  type: z2.enum(["Net", "Gross"]).describe("Payment type"),
+  paymentType: z2.union([
+    z2.literal(1),
+    z2.literal(2),
+    z2.literal(3),
+    z2.literal(4),
+    z2.enum(["RegularPayment", "Overtime", "SocialAid", "ExtraPay"])
+  ]).optional().describe("Payment type (1: RegularPayment, 2: Overtime, 3: SocialAid, 4: ExtraPay)")
+});
+var PayEventSchema = z2.object({
+  month: z2.number().min(1).max(12).describe("Month when the payment occurs (1-12)"),
+  year: z2.number().describe("Year when the payment occurs"),
+  name: z2.string().describe('Payment name (e.g., "Q2 Bonus")'),
+  amount: z2.number().describe("Payment amount"),
+  type: z2.enum(["Net", "Gross"]).describe("Whether the amount is net or gross"),
+  paymentType: z2.union([
+    z2.literal(1),
+    z2.literal(2),
+    z2.literal(3),
+    z2.literal(4),
+    z2.enum(["RegularPayment", "Overtime", "SocialAid", "ExtraPay"])
+  ]).optional().describe("Payment category: 1/RegularPayment, 2/Overtime, 3/SocialAid, 4/ExtraPay (default: 4)")
 });
 var CustomParamsSchema = z2.object({
   minWage: z2.number().optional().describe("Custom minimum wage (gross)"),
@@ -510,7 +618,11 @@ var EmployeeInputSchema = z2.object({
   wage: z2.number().describe("Wage amount"),
   calculationType: z2.enum(["Gross", "Net"]).describe("Whether wage is gross or net"),
   ssiType: z2.enum(["S4A", "S4B", "S4C"]).optional().describe("SSI type (default: S4A)"),
-  extraPayments: z2.array(ExtraPaymentSchema).optional().describe("Extra payments like bonuses")
+  extraPayments: z2.array(ExtraPaymentSchema).optional().describe("Extra payments like bonuses"),
+  cumulativeIncomeTaxBase: z2.number().optional().describe("Starting cumulative income tax base"),
+  cumulativeMinWageIncomeTaxBase: z2.number().optional().describe("Starting cumulative minimum wage income tax base"),
+  transferredSSIBase1: z2.number().optional().describe("Starting transferred SSI base 1"),
+  transferredSSIBase2: z2.number().optional().describe("Starting transferred SSI base 2")
 });
 var ScenarioConfigSchema = z2.object({
   name: z2.string().optional().describe("Scenario name for comparison"),
@@ -556,7 +668,11 @@ function registerTools(server, client) {
       month: z2.number().min(1).max(12).describe("Starting month (1-12)"),
       periodCount: z2.number().min(1).max(12).optional().describe("Number of months to calculate (default: 1)"),
       extraPayments: z2.array(ExtraPaymentSchema).optional().describe("Extra payments like bonuses"),
-      customParams: CustomParamsSchema.optional().describe("Custom global parameters to override defaults")
+      customParams: CustomParamsSchema.optional().describe("Custom global parameters to override defaults"),
+      cumulativeIncomeTaxBase: z2.number().optional().describe("Starting cumulative income tax base to carry from previous months"),
+      cumulativeMinWageIncomeTaxBase: z2.number().optional().describe("Starting cumulative minimum wage income tax base"),
+      transferredSSIBase1: z2.number().optional().describe("Starting transferred SSI base 1"),
+      transferredSSIBase2: z2.number().optional().describe("Starting transferred SSI base 2")
     },
     async (params) => {
       try {
@@ -623,7 +739,9 @@ function registerTools(server, client) {
       employees: z2.array(z2.object({
         name: z2.string().describe("Employee name"),
         wage: z2.number().describe("Current wage amount"),
-        calculationType: z2.enum(["Gross", "Net"]).describe("Wage type")
+        calculationType: z2.enum(["Gross", "Net"]).describe("Wage type"),
+        ssiType: z2.enum(["S4A", "S4B", "S4C"]).optional().describe("SSI type (default: S4A)"),
+        payEvents: z2.array(PayEventSchema).optional().describe("Extra payments at specific months (e.g., bonuses)")
       })).describe("Array of employees"),
       year: z2.number().describe("Calculation year"),
       periodCount: z2.number().min(1).max(12).describe("Number of months (use 12 for yearly)"),
@@ -660,7 +778,9 @@ function registerTools(server, client) {
       employees: z2.array(z2.object({
         name: z2.string().describe("Employee name"),
         wage: z2.number().describe("Current wage"),
-        calculationType: z2.enum(["Gross", "Net"]).describe("Wage type")
+        calculationType: z2.enum(["Gross", "Net"]).describe("Wage type"),
+        ssiType: z2.enum(["S4A", "S4B", "S4C"]).optional().describe("SSI type (default: S4A)"),
+        payEvents: z2.array(PayEventSchema).optional().describe("Extra payments at specific months (e.g., bonuses)")
       })).describe("Array of employees"),
       year: z2.number().describe("Calculation year"),
       periodCount: z2.number().min(1).max(12).describe("Number of months"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payrolla-mcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "MCP server for Payrolla payroll budget simulations - enables LLMs to calculate Turkish payroll and simulate budget scenarios",
   "author": "Payrolla",
   "license": "MIT",