payrolla-mcp 0.2.3 → 0.2.5

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,11 +30,27 @@ 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 {
     minWage: customParams.minWage,
-    minWageNet: customParams.minWageNet,
     ssi_LowerLimit: customParams.ssiLowerLimit,
     ssi_UpperLimit: customParams.ssiUpperLimit,
     stampTaxRatio: customParams.stampTaxRatio,
@@ -51,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 = [
     {
@@ -67,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: {
@@ -89,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,
@@ -108,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,
@@ -135,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,
@@ -170,9 +222,21 @@ var DEFAULT_PARAMS_2025 = {
   incomeTaxBrackets: [
     { limit: 158e3, rate: 0.15, description: "158,000 TL'ye kadar %15" },
     { limit: 33e4, rate: 0.2, description: "158,000-330,000 TL aras\u0131 %20" },
-    { limit: 12e5, rate: 0.27, description: "330,000-1,200,000 TL aras\u0131 %27" },
-    { limit: 43e5, rate: 0.35, description: "1,200,000-4,300,000 TL aras\u0131 %35" },
-    { limit: Number.MAX_SAFE_INTEGER, rate: 0.4, description: "4,300,000 TL'den fazlas\u0131 %40" }
+    {
+      limit: 12e5,
+      rate: 0.27,
+      description: "330,000-1,200,000 TL aras\u0131 %27"
+    },
+    {
+      limit: 43e5,
+      rate: 0.35,
+      description: "1,200,000-4,300,000 TL aras\u0131 %35"
+    },
+    {
+      limit: Number.MAX_SAFE_INTEGER,
+      rate: 0.4,
+      description: "4,300,000 TL'den fazlas\u0131 %40"
+    }
   ]
 };
 
@@ -191,9 +255,6 @@ function applyScenario(defaults, scenario) {
   if (scenario.minWage !== void 0) {
     result.minWage = scenario.minWage;
   }
-  if (scenario.minWageNet !== void 0) {
-    result.minWageNet = scenario.minWageNet;
-  }
   if (scenario.ssiLimitIncreasePercent !== void 0) {
     const multiplier = 1 + scenario.ssiLimitIncreasePercent / 100;
     result.ssiLowerLimit = defaults.ssiLowerLimit * multiplier;
@@ -256,7 +317,6 @@ async function simulateBudget(client, input) {
     scenarioApplied: {
       salaryRaisePercent: scenario.salaryRaisePercent || 0,
       effectiveMinWage: customParams.minWage || defaults.minWage,
-      effectiveMinWageNet: customParams.minWageNet || defaults.minWageNet,
       effectiveTaxBrackets
     },
     summary: {
@@ -485,7 +545,14 @@ 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 CustomParamsSchema = z2.object({
   minWage: z2.number().optional().describe("Custom minimum wage (gross)"),
@@ -503,7 +570,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"),
@@ -549,7 +620,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payrolla-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "MCP server for Payrolla payroll budget simulations - enables LLMs to calculate Turkish payroll and simulate budget scenarios",
   "author": "Payrolla",
   "license": "MIT",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "payrolla": "^0.2.2",
+    "payrolla": "^0.2.4",
     "zod": "^3.25.0"
   },
   "devDependencies": {