payrolla-mcp 0.2.6 → 0.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Payrolla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -57,6 +57,10 @@ function buildCustomGlobalParams(customParams) {
     incomeTaxLimits: customParams.incomeTaxLimits
   };
 }
+function buildSSICutDefList(customParams) {
+  if (!customParams?.ssiCutDefList) return void 0;
+  return customParams.ssiCutDefList;
+}
 async function calculatePayroll(client, input) {
   const {
     name,
@@ -102,7 +106,8 @@ async function calculatePayroll(client, input) {
     payments,
     calculationParams: {
       calculateMinWageExemption: true,
-      customGlobalParams: buildCustomGlobalParams(customParams)
+      customGlobalParams: buildCustomGlobalParams(customParams),
+      ssiCutDefList: buildSSICutDefList(customParams)
     }
   };
   let totalCost = 0;
@@ -214,6 +219,7 @@ async function calculateBulkPayroll(client, input) {
 // src/types/index.ts
 var DEFAULT_PARAMS_2025 = {
   year: 2025,
+  month: 1,
   minWage: 26005.5,
   minWageNet: 22104.67,
   ssiLowerLimit: 26005.5,
@@ -241,14 +247,46 @@ var DEFAULT_PARAMS_2025 = {
 };
 
 // src/tools/params.ts
-function getDefaultParams(input) {
-  if (input.year === 2025) {
-    return DEFAULT_PARAMS_2025;
+function getFallbackParams(year, month = 1) {
+  if (year === 2025) {
+    return { ...DEFAULT_PARAMS_2025, month };
+  }
+  return { ...DEFAULT_PARAMS_2025, year, month };
+}
+async function getDefaultParams(client, input) {
+  const month = input.month || 1;
+  try {
+    const response = await client.payroll.getParams(input.year, month);
+    if (response.isSuccess && response.data) {
+      const gp = response.data.globalParams;
+      const ssiCutDefs = response.data.ssiCutDefs;
+      return {
+        year: response.data.year,
+        month: response.data.month,
+        minWage: gp.minWage,
+        minWageNet: gp.minWageNet,
+        ssiLowerLimit: gp.ssi_LowerLimit,
+        ssiUpperLimit: gp.ssi_UpperLimit,
+        stampTaxRatio: gp.stampTaxRatio,
+        incomeTaxBrackets: (gp.incomeTaxLimits || []).map((b, i) => ({
+          limit: b.limit,
+          rate: b.rate,
+          description: `Bracket ${i + 1}`
+        })),
+        ssiCutDefList: ssiCutDefs ? ssiCutDefs.map((def) => ({
+          nr: def.nr,
+          name: def.name,
+          employerRatio: def.employerRatio,
+          employeeRatio: def.employeeRatio
+        })) : void 0
+      };
+    }
+    console.warn(`Failed to fetch params: ${response.message}`);
+    return getFallbackParams(input.year, month);
+  } catch (error) {
+    console.error("Error fetching params from server:", error);
+    return getFallbackParams(input.year, month);
   }
-  return {
-    ...DEFAULT_PARAMS_2025,
-    year: input.year
-  };
 }
 function applyScenario(defaults, scenario) {
   const result = {};
@@ -277,9 +315,29 @@ function applyRaise(wage, raisePercent) {
   }
   return wage * (1 + raisePercent / 100);
 }
+function getActiveParameters(baseParams, events, currentYear, currentMonth) {
+  const activeEvents = events.filter(
+    (e) => e.year < currentYear || e.year === currentYear && e.month <= currentMonth
+  ).sort((a, b) => a.year - b.year || a.month - b.month);
+  let result = { ...baseParams };
+  for (const event of activeEvents) {
+    if (event.minWage !== void 0) result.minWage = event.minWage;
+    if (event.ssiLowerLimit !== void 0)
+      result.ssiLowerLimit = event.ssiLowerLimit;
+    if (event.ssiUpperLimit !== void 0)
+      result.ssiUpperLimit = event.ssiUpperLimit;
+    if (event.stampTaxRatio !== void 0)
+      result.stampTaxRatio = event.stampTaxRatio;
+    if (event.incomeTaxLimits !== void 0)
+      result.incomeTaxLimits = event.incomeTaxLimits;
+    if (event.ssiCutDefList !== void 0)
+      result.ssiCutDefList = event.ssiCutDefList;
+  }
+  return result;
+}
 async function simulateBudget(client, input) {
-  const { employees, year, periodCount, scenario } = input;
-  const defaults = getDefaultParams({ year });
+  const { employees, year, periodCount, scenario, parameterEvents } = input;
+  const defaults = await getDefaultParams(client, { year });
   const customParams = applyScenario(defaults, scenario);
   const employeeResults = [];
   let totalYearlyCost = 0;
@@ -294,6 +352,7 @@ async function simulateBudget(client, input) {
     let empTotalCost = 0;
     let empTotalNet = 0;
     let empTotalGross = 0;
+    const empPeriods = [];
     for (let i = 0; i < periodCount; i++) {
       const calcDate = new Date(year, i, 1);
       const calcYear = calcDate.getFullYear();
@@ -307,6 +366,12 @@ async function simulateBudget(client, input) {
         type: pe.type,
         paymentType: pe.paymentType
       }));
+      const effectiveParams = getActiveParameters(
+        customParams,
+        parameterEvents || [],
+        calcYear,
+        calcMonth
+      );
       const result = await calculatePayroll(client, {
         name: emp.name,
         wage: adjustedWage,
@@ -316,7 +381,7 @@ async function simulateBudget(client, input) {
         month: calcMonth,
         periodCount: 1,
         extraPayments: extraPayments.length > 0 ? extraPayments : void 0,
-        customParams,
+        customParams: effectiveParams,
         cumulativeIncomeTaxBase,
         cumulativeMinWageIncomeTaxBase,
         transferredSSIBase1,
@@ -326,6 +391,7 @@ async function simulateBudget(client, input) {
       empTotalNet += result.totalNet;
       empTotalGross += result.totalGross;
       const lastPeriod = result.periods[0];
+      empPeriods.push(lastPeriod);
       cumulativeIncomeTaxBase = lastPeriod.cumulativeIncomeTaxBase;
       cumulativeMinWageIncomeTaxBase = lastPeriod.cumulativeMinWageIncomeTaxBase;
       transferredSSIBase1 = lastPeriod.transferredSSIBase1;
@@ -337,7 +403,8 @@ async function simulateBudget(client, input) {
       adjustedWage,
       yearlyCost: empTotalCost,
       yearlyNet: empTotalNet,
-      yearlyGross: empTotalGross
+      yearlyGross: empTotalGross,
+      periods: empPeriods
     });
     totalYearlyCost += empTotalCost;
     totalYearlyNet += empTotalNet;
@@ -363,7 +430,7 @@ async function simulateBudget(client, input) {
   };
 }
 async function compareScenarios(client, input) {
-  const { employees, year, periodCount, scenarios } = input;
+  const { employees, year, periodCount, scenarios, parameterEvents } = input;
   if (scenarios.length === 0) {
     throw new Error("At least one scenario is required");
   }
@@ -373,7 +440,8 @@ async function compareScenarios(client, input) {
       employees,
       year,
       periodCount,
-      scenario
+      scenario,
+      parameterEvents
     });
     results.push({
       name: scenario.name || `Scenario ${results.length + 1}`,
@@ -602,6 +670,26 @@ var PayEventSchema = z2.object({
     z2.enum(["RegularPayment", "Overtime", "SocialAid", "ExtraPay"])
   ]).optional().describe("Payment category: 1/RegularPayment, 2/Overtime, 3/SocialAid, 4/ExtraPay (default: 4)")
 });
+var SSICutDefSchema = z2.object({
+  nr: z2.number().describe("Order number for the cut"),
+  name: z2.string().describe("Name of the SSI cut"),
+  employerRatio: z2.number().describe("Employer contribution ratio (e.g., 0.02 for 2%)"),
+  employeeRatio: z2.number().describe("Employee contribution ratio (e.g., 0.03 for 3%)")
+});
+var ParameterEventSchema = z2.object({
+  month: z2.number().min(1).max(12).describe("Month when parameter change takes effect (1-12)"),
+  year: z2.number().describe("Year when parameter change takes effect"),
+  name: z2.string().optional().describe("Description of the parameter change"),
+  minWage: z2.number().optional().describe("New minimum wage"),
+  ssiLowerLimit: z2.number().optional().describe("New SSI lower limit"),
+  ssiUpperLimit: z2.number().optional().describe("New SSI upper limit"),
+  stampTaxRatio: z2.number().optional().describe("New stamp tax ratio"),
+  incomeTaxLimits: z2.array(z2.object({
+    limit: z2.number(),
+    rate: z2.number()
+  })).optional().describe("New income tax brackets"),
+  ssiCutDefList: z2.array(SSICutDefSchema).optional().describe("Custom SSI cut definitions (replaces defaults from this month onwards)")
+});
 var CustomParamsSchema = z2.object({
   minWage: z2.number().optional().describe("Custom minimum wage (gross)"),
   minWageNet: z2.number().optional().describe("Custom minimum wage (net)"),
@@ -611,7 +699,8 @@ var CustomParamsSchema = z2.object({
   incomeTaxLimits: z2.array(z2.object({
     limit: z2.number().describe("Upper limit for this bracket"),
     rate: z2.number().describe("Tax rate (e.g., 0.15 for 15%)")
-  })).optional().describe("Custom income tax brackets")
+  })).optional().describe("Custom income tax brackets"),
+  ssiCutDefList: z2.array(SSICutDefSchema).optional().describe("Custom SSI cut definitions")
 });
 var EmployeeInputSchema = z2.object({
   name: z2.string().describe("Employee name"),
@@ -745,7 +834,8 @@ function registerTools(server, client) {
       })).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)"),
-      scenario: ScenarioConfigSchema.describe("Scenario configuration with changes to apply")
+      scenario: ScenarioConfigSchema.describe("Scenario configuration with changes to apply"),
+      parameterEvents: z2.array(ParameterEventSchema).optional().describe("Parameter changes that take effect from a specific month onwards (applies to all employees). Unlike payEvents, these persist for subsequent months.")
     },
     async (params) => {
       try {
@@ -784,7 +874,8 @@ function registerTools(server, client) {
       })).describe("Array of employees"),
       year: z2.number().describe("Calculation year"),
       periodCount: z2.number().min(1).max(12).describe("Number of months"),
-      scenarios: z2.array(ScenarioConfigSchema).min(1).describe("Array of scenarios to compare")
+      scenarios: z2.array(ScenarioConfigSchema).min(1).describe("Array of scenarios to compare"),
+      parameterEvents: z2.array(ParameterEventSchema).optional().describe("Parameter changes that take effect from a specific month onwards (applies to all employees)")
     },
     async (params) => {
       try {
@@ -812,13 +903,14 @@ function registerTools(server, client) {
   );
   server.tool(
     "get_default_params",
-    "Get default Turkish payroll parameters for a given year",
+    "Get default Turkish payroll parameters for a given year and month",
     {
-      year: z2.number().describe("Year to get parameters for (e.g., 2025)")
+      year: z2.number().describe("Year to get parameters for (e.g., 2025)"),
+      month: z2.number().min(1).max(12).optional().describe("Month to get parameters for (1-12, default: 1)")
     },
     async (params) => {
       try {
-        const result = getDefaultParams(params);
+        const result = await getDefaultParams(client, params);
         return {
           content: [
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payrolla-mcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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.4",
+    "payrolla": "^0.2.6",
     "zod": "^3.25.0"
   },
   "devDependencies": {