payrolla-mcp 0.2.1

package/README.md

@@ -0,0 +1,123 @@
+# Payrolla MCP Server
+
+MCP (Model Context Protocol) server for Turkish payroll calculations and budget simulations. Enables LLMs to calculate payroll, simulate budgets, and compare what-if scenarios.
+
+## Installation
+
+```bash
+npm install -g payrolla-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx payrolla-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PAYROLLA_API_KEY` | Yes | API key for Payrolla service |
+| `PAYROLLA_DEBUG` | No | Set to `true` for debug logging |
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "payrolla": {
+      "command": "npx",
+      "args": ["payrolla-mcp"],
+      "env": {
+        "PAYROLLA_API_KEY": "pk_live_xxxxx"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### calculate_payroll
+
+Calculate payroll for a single employee.
+
+**Input:**
+- `name` - Employee name
+- `wage` - Wage amount
+- `calculationType` - 'Gross' or 'Net'
+- `year` - Calculation year
+- `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)
+- `customParams` - Custom global parameters (optional)
+
+### calculate_bulk_payroll
+
+Calculate payroll for multiple employees with shared parameters.
+
+**Input:**
+- `employees` - Array of employee objects
+- `year` - Calculation year
+- `month` - Starting month
+- `periodCount` - Number of months (use 12 for yearly)
+- `customParams` - Shared custom parameters (optional)
+
+### simulate_budget
+
+Simulate budget with what-if scenarios.
+
+**Input:**
+- `employees` - Array of employees
+- `year` - Calculation year
+- `periodCount` - Number of months
+- `scenario` - Scenario configuration:
+  - `salaryRaisePercent` - Salary raise percentage
+  - `minWage` - Custom minimum wage
+  - `taxLimitIncreasePercent` - Tax bracket limit increase
+  - `customTaxBrackets` - Custom tax brackets
+
+### compare_scenarios
+
+Compare multiple budget scenarios side by side.
+
+**Input:**
+- `employees` - Array of employees
+- `year` - Calculation year
+- `periodCount` - Number of months
+- `scenarios` - Array of scenario configurations
+
+### get_default_params
+
+Get default Turkish payroll parameters for a year.
+
+**Input:**
+- `year` - Year to get parameters for
+
+## Available Prompts
+
+### budget_simulation
+
+Interactive prompt for simulating yearly payroll budget.
+
+### salary_raise_analysis
+
+Analyze the cost impact of different salary raise percentages.
+
+### year_planning
+
+Plan yearly payroll considering potential changes.
+
+## Example Conversations
+
+### Budget Simulation
+
+```
+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?

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,766 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PayrollaClient as PayrollaClient2 } from "payrolla";
+import { z as z2 } from "zod";
+
+// src/tools/calculate.ts
+import {
+  SSIType,
+  CalculationType,
+  PaymentPeriodType,
+  PeriodLengthType,
+  PaymentType
+} from "payrolla";
+function mapSSIType(ssiType) {
+  switch (ssiType) {
+    case "S4B":
+      return SSIType.S4B;
+    case "S4C":
+      return SSIType.S4C;
+    case "S4A":
+    default:
+      return SSIType.S4A;
+  }
+}
+function mapCalculationType(calcType) {
+  return calcType === "Gross" ? CalculationType.Gross : CalculationType.Net;
+}
+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,
+    incomeTaxLimits: customParams.incomeTaxLimits
+  };
+}
+async function calculatePayroll(client, input) {
+  const {
+    name,
+    wage,
+    calculationType,
+    ssiType,
+    year,
+    month,
+    periodCount = 1,
+    extraPayments,
+    customParams
+  } = input;
+  const payments = [
+    {
+      paymentAmount: 31,
+      paymentName: "Maas",
+      paymentType: PaymentType.RegularPayment,
+      paymentRef: "1"
+    }
+  ];
+  if (extraPayments && extraPayments.length > 0) {
+    for (let i = 0; i < extraPayments.length; i++) {
+      const extra = extraPayments[i];
+      payments.push({
+        paymentAmount: extra.amount,
+        paymentName: extra.name,
+        paymentType: PaymentType.ExtraPay,
+        paymentRef: `extra_${i + 2}`,
+        calculationType: extra.type === "Net" ? CalculationType.Net : CalculationType.Gross
+      });
+    }
+  }
+  const model = {
+    calcDate: `${year}-${String(month).padStart(2, "0")}-01`,
+    wageAmount: wage,
+    cumulativeIncomeTaxBase: 0,
+    cumulativeMinWageIncomeTaxBase: 0,
+    ssiType: mapSSIType(ssiType),
+    wageCalculationType: mapCalculationType(calculationType),
+    wagePeriodType: PaymentPeriodType.Monthly,
+    periodCount,
+    periodLengthType: PeriodLengthType.Month,
+    payments,
+    calculationParams: {
+      calculateMinWageExemption: true,
+      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) {
+    const pr = payroll.payrollResult;
+    totalCost += payroll.totalCost;
+    totalNet += pr.totalNet;
+    totalGross += pr.totalGross;
+    periods.push({
+      year: payroll.year,
+      month: payroll.month,
+      grossWage: pr.totalGross,
+      netWage: pr.totalNet,
+      employerCost: payroll.totalCost,
+      incomeTax: pr.totalIncomeTax,
+      stampTax: pr.totalStampTax,
+      employeeSSI: pr.totalSSIWorkerPrem,
+      employerSSI: pr.totalSSIEmployerPrem
+    });
+  }
+  return {
+    employee: name,
+    totalCost,
+    totalNet,
+    totalGross,
+    periods
+  };
+}
+async function calculateBulkPayroll(client, input) {
+  const {
+    employees,
+    year,
+    month,
+    periodCount = 1,
+    customParams
+  } = input;
+  const employeeResults = [];
+  let totalYearlyCost = 0;
+  let totalYearlyNet = 0;
+  let totalYearlyGross = 0;
+  for (const emp of employees) {
+    const result = await calculatePayroll(client, {
+      name: emp.name,
+      wage: emp.wage,
+      calculationType: emp.calculationType,
+      ssiType: emp.ssiType,
+      year,
+      month,
+      periodCount,
+      extraPayments: emp.extraPayments,
+      customParams
+    });
+    employeeResults.push({
+      name: result.employee,
+      totalCost: result.totalCost,
+      totalNet: result.totalNet,
+      totalGross: result.totalGross
+    });
+    totalYearlyCost += result.totalCost;
+    totalYearlyNet += result.totalNet;
+    totalYearlyGross += result.totalGross;
+  }
+  return {
+    summary: {
+      totalEmployees: employees.length,
+      totalYearlyCost,
+      totalYearlyNet,
+      totalYearlyGross,
+      averageMonthlyCost: totalYearlyCost / periodCount
+    },
+    employees: employeeResults
+  };
+}
+
+// src/types/index.ts
+var DEFAULT_PARAMS_2025 = {
+  year: 2025,
+  minWage: 26005.5,
+  minWageNet: 22104.67,
+  ssiLowerLimit: 26005.5,
+  ssiUpperLimit: 195041.4,
+  stampTaxRatio: 759e-5,
+  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" }
+  ]
+};
+
+// src/tools/params.ts
+function getDefaultParams(input) {
+  if (input.year === 2025) {
+    return DEFAULT_PARAMS_2025;
+  }
+  return {
+    ...DEFAULT_PARAMS_2025,
+    year: input.year
+  };
+}
+function applyScenario(defaults, scenario) {
+  const result = {};
+  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;
+    result.ssiUpperLimit = defaults.ssiUpperLimit * multiplier;
+  }
+  if (scenario.customTaxBrackets !== void 0) {
+    result.incomeTaxLimits = scenario.customTaxBrackets;
+  } else if (scenario.taxLimitIncreasePercent !== void 0) {
+    const multiplier = 1 + scenario.taxLimitIncreasePercent / 100;
+    result.incomeTaxLimits = defaults.incomeTaxBrackets.map((bracket) => ({
+      limit: bracket.limit === Number.MAX_SAFE_INTEGER ? bracket.limit : Math.round(bracket.limit * multiplier),
+      rate: bracket.rate
+    }));
+  }
+  return result;
+}
+function applyRaise(wage, raisePercent) {
+  if (raisePercent === void 0 || raisePercent === 0) {
+    return wage;
+  }
+  return wage * (1 + raisePercent / 100);
+}
+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 {
+      name: emp.name,
+      originalWage: emp.originalWage,
+      adjustedWage: emp.wage,
+      yearlyCost: empResult.totalCost,
+      yearlyNet: empResult.totalNet,
+      yearlyGross: empResult.totalGross
+    };
+  });
+  const effectiveTaxBrackets = customParams.incomeTaxLimits || defaults.incomeTaxBrackets.map((b) => ({
+    limit: b.limit,
+    rate: b.rate
+  }));
+  return {
+    scenarioApplied: {
+      salaryRaisePercent: scenario.salaryRaisePercent || 0,
+      effectiveMinWage: customParams.minWage || defaults.minWage,
+      effectiveMinWageNet: customParams.minWageNet || defaults.minWageNet,
+      effectiveTaxBrackets
+    },
+    summary: {
+      totalYearlyCost: result.summary.totalYearlyCost,
+      totalYearlyNet: result.summary.totalYearlyNet,
+      totalYearlyGross: result.summary.totalYearlyGross,
+      costPerEmployee: result.summary.totalYearlyCost / employees.length
+    },
+    employees: employeeResults
+  };
+}
+async function compareScenarios(client, input) {
+  const { employees, year, periodCount, scenarios } = input;
+  if (scenarios.length === 0) {
+    throw new Error("At least one scenario is required");
+  }
+  const results = [];
+  for (const scenario of scenarios) {
+    const result = await simulateBudget(client, {
+      employees,
+      year,
+      periodCount,
+      scenario
+    });
+    results.push({
+      name: scenario.name || `Scenario ${results.length + 1}`,
+      totalCost: result.summary.totalYearlyCost
+    });
+  }
+  const baselineCost = results[0].totalCost;
+  const comparison = results.map((r) => ({
+    scenarioName: r.name,
+    totalCost: r.totalCost,
+    costDifference: r.totalCost - baselineCost,
+    percentChange: baselineCost > 0 ? (r.totalCost - baselineCost) / baselineCost * 100 : 0
+  }));
+  const sortedByCoset = [...results].sort((a, b) => a.totalCost - b.totalCost);
+  const cheapestScenario = sortedByCoset[0].name;
+  const mostExpensiveScenario = sortedByCoset[sortedByCoset.length - 1].name;
+  return {
+    baselineCost,
+    comparison,
+    cheapestScenario,
+    mostExpensiveScenario
+  };
+}
+
+// src/resources/index.ts
+function registerResources(server) {
+  server.resource(
+    "2025 Turkish Payroll Defaults",
+    "payrolla://defaults/2025",
+    {
+      description: "Default payroll parameters for Turkey in 2025 including minimum wage, SSI limits, and tax brackets",
+      mimeType: "application/json"
+    },
+    async () => {
+      return {
+        contents: [
+          {
+            uri: "payrolla://defaults/2025",
+            mimeType: "application/json",
+            text: JSON.stringify(DEFAULT_PARAMS_2025, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/index.ts
+import { z } from "zod";
+function getBudgetSimulationPrompt(employeeCount, scenarioType) {
+  const scenarioText = scenarioType || "any type of";
+  return `You are helping calculate a payroll budget simulation for Turkish employees.
+
+The user has ${employeeCount} employees. They want to simulate a ${scenarioText} scenario.
+
+**Your task:**
+
+1. First, ask the user for each employee's details:
+   - Name
+   - Current salary amount
+   - Whether it's Net or Gross salary
+
+2. Ask about the scenario parameters they want to simulate:
+   - Salary raise percentage (e.g., 10% for a 10% raise)
+   - New minimum wage if different from current (current 2025: 26,005.50 TL gross)
+   - Tax bracket changes if any
+
+3. Use the **simulate_budget** tool with the collected data to calculate results.
+
+4. Present a clear summary showing:
+   - Current state vs. scenario comparison
+   - Total yearly cost difference
+   - Per-employee breakdown
+
+**Important:** All monetary values should be in Turkish Lira (TL). Use the 2025 default parameters as baseline unless the user specifies otherwise.`;
+}
+function getSalaryRaiseAnalysisPrompt(raisePercentages) {
+  return `You are analyzing the cost impact of different salary raise scenarios for Turkish employees.
+
+The user wants to compare these raise percentages: ${raisePercentages}
+
+**Your task:**
+
+1. Ask the user for their employee list:
+   - Each employee's name
+   - Current salary (Net or Gross)
+   - Salary type (Net or Gross)
+
+2. Use the **compare_scenarios** tool to calculate all raise scenarios side by side.
+   - Create one scenario for each raise percentage
+   - Use 12 period count for yearly calculation
+
+3. Present results in a clear comparison table:
+   - Scenario name
+   - Total yearly cost
+   - Cost difference from baseline (0% raise)
+   - Percentage change
+
+4. Provide a recommendation on the most cost-effective option.
+
+**Note:** The comparison uses Turkish payroll rules including progressive income tax, SSI contributions, and stamp tax.`;
+}
+function getYearPlanningPrompt(planningYear) {
+  return `You are helping plan the ${planningYear} payroll budget for a Turkish company.
+
+**Your task:**
+
+1. First, use **get_default_params** to show the current ${planningYear} parameters:
+   - Minimum wage (gross and net)
+   - SSI contribution limits
+   - Income tax brackets
+   - Stamp tax ratio
+
+2. Ask the user about their workforce:
+   - Number of employees
+   - Current salaries for each employee
+
+3. Ask about expected changes for ${planningYear}:
+   - Expected minimum wage increase (if any)
+   - Expected tax bracket adjustments
+   - Planned salary raises for employees
+
+4. Use **simulate_budget** to calculate:
+   - Current cost (no changes)
+   - Projected cost with expected changes
+
+5. Provide a comprehensive summary:
+   - Monthly and yearly cost projections
+   - Budget increase/decrease compared to current
+   - Per-employee cost breakdown
+   - Recommendations for budget planning
+
+**Currency:** All values in Turkish Lira (TL)`;
+}
+function registerPrompts(server) {
+  server.prompt(
+    "budget_simulation",
+    "Simulate yearly payroll budget with custom scenarios like salary raises, minimum wage changes, or tax adjustments",
+    {
+      employee_count: z.string().describe("Number of employees to simulate"),
+      scenario_type: z.string().optional().describe("Type of scenario: raise, min_wage_change, tax_change, or combined")
+    },
+    async (args) => {
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: getBudgetSimulationPrompt(
+                args.employee_count || "(unspecified)",
+                args.scenario_type
+              )
+            }
+          }
+        ]
+      };
+    }
+  );
+  server.prompt(
+    "salary_raise_analysis",
+    "Analyze the cost impact of giving different salary raise percentages",
+    {
+      raise_percentages: z.string().describe('Comma-separated raise percentages to compare (e.g., "5,10,15")')
+    },
+    async (args) => {
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: getSalaryRaiseAnalysisPrompt(args.raise_percentages || "5,10,15")
+            }
+          }
+        ]
+      };
+    }
+  );
+  server.prompt(
+    "year_planning",
+    "Plan yearly payroll considering potential minimum wage and tax changes",
+    {
+      planning_year: z.string().describe("Year to plan for (e.g., 2025)")
+    },
+    async (args) => {
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: getYearPlanningPrompt(args.planning_year || "2025")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/server.ts
+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")
+});
+var CustomParamsSchema = z2.object({
+  minWage: z2.number().optional().describe("Custom minimum wage (gross)"),
+  minWageNet: z2.number().optional().describe("Custom minimum wage (net)"),
+  ssiLowerLimit: z2.number().optional().describe("Custom SSI lower limit"),
+  ssiUpperLimit: z2.number().optional().describe("Custom SSI upper limit"),
+  stampTaxRatio: z2.number().optional().describe("Custom stamp tax ratio"),
+  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")
+});
+var EmployeeInputSchema = z2.object({
+  name: z2.string().describe("Employee name"),
+  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")
+});
+var ScenarioConfigSchema = z2.object({
+  name: z2.string().optional().describe("Scenario name for comparison"),
+  salaryRaisePercent: z2.number().optional().describe("Salary raise percentage (e.g., 10 for 10%)"),
+  minWage: z2.number().optional().describe("Custom minimum wage"),
+  minWageNet: z2.number().optional().describe("Custom net minimum wage"),
+  taxLimitIncreasePercent: z2.number().optional().describe("Increase tax bracket limits by percentage"),
+  ssiLimitIncreasePercent: z2.number().optional().describe("Increase SSI limits by percentage"),
+  customTaxBrackets: z2.array(z2.object({
+    limit: z2.number(),
+    rate: z2.number()
+  })).optional().describe("Custom tax brackets")
+});
+function createServer() {
+  const apiKey = process.env.PAYROLLA_API_KEY;
+  if (!apiKey) {
+    console.error("Error: PAYROLLA_API_KEY environment variable is required");
+    process.exit(1);
+  }
+  const payrollaClient = new PayrollaClient2({
+    apiKey,
+    timeout: 3e4
+  });
+  const server = new McpServer({
+    name: "payrolla-mcp",
+    version: "1.0.0"
+  });
+  registerTools(server, payrollaClient);
+  registerResources(server);
+  registerPrompts(server);
+  return server;
+}
+function registerTools(server, client) {
+  server.tool(
+    "calculate_payroll",
+    "Calculate payroll for a single employee including taxes, SSI, and employer cost",
+    {
+      name: z2.string().describe("Employee name"),
+      wage: z2.number().describe("Wage amount"),
+      calculationType: z2.enum(["Gross", "Net"]).describe("Whether the wage is gross or net"),
+      ssiType: z2.enum(["S4A", "S4B", "S4C"]).optional().describe("SSI type (default: S4A for general employees)"),
+      year: z2.number().describe("Calculation year (e.g., 2025)"),
+      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")
+    },
+    async (params) => {
+      try {
+        const result = await calculatePayroll(client, params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "calculate_bulk_payroll",
+    "Calculate payroll for multiple employees with shared parameters",
+    {
+      employees: z2.array(EmployeeInputSchema).describe("Array of employees to calculate"),
+      year: z2.number().describe("Calculation year (e.g., 2025)"),
+      month: z2.number().min(1).max(12).describe("Starting month (1-12)"),
+      periodCount: z2.number().min(1).max(12).optional().describe("Number of months (default: 1, use 12 for yearly)"),
+      customParams: CustomParamsSchema.optional().describe("Custom global parameters shared by all employees")
+    },
+    async (params) => {
+      try {
+        const result = await calculateBulkPayroll(client, params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "simulate_budget",
+    "Simulate budget with what-if scenarios like salary raises or parameter changes",
+    {
+      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")
+      })).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")
+    },
+    async (params) => {
+      try {
+        const result = await simulateBudget(client, params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "compare_scenarios",
+    "Compare multiple budget scenarios side by side",
+    {
+      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")
+      })).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")
+    },
+    async (params) => {
+      try {
+        const result = await compareScenarios(client, params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "get_default_params",
+    "Get default Turkish payroll parameters for a given year",
+    {
+      year: z2.number().describe("Year to get parameters for (e.g., 2025)")
+    },
+    async (params) => {
+      try {
+        const result = getDefaultParams(params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/index.ts
+async function main() {
+  if (!process.env.PAYROLLA_API_KEY) {
+    console.error("Error: PAYROLLA_API_KEY environment variable is required");
+    console.error("");
+    console.error("Set it in your MCP client configuration or run:");
+    console.error("  export PAYROLLA_API_KEY=pk_live_xxxxx");
+    process.exit(1);
+  }
+  const debug = process.env.PAYROLLA_DEBUG === "true";
+  if (debug) {
+    console.error("[payrolla-mcp] Starting in debug mode...");
+  }
+  try {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (debug) {
+      console.error("[payrolla-mcp] Server connected via stdio");
+    }
+    process.on("SIGINT", async () => {
+      if (debug) {
+        console.error("[payrolla-mcp] Shutting down...");
+      }
+      await server.close();
+      process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+      if (debug) {
+        console.error("[payrolla-mcp] Shutting down...");
+      }
+      await server.close();
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  }
+}
+main().catch((error) => {
+  console.error("Unhandled error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "payrolla-mcp",
+  "version": "0.2.1",
+  "description": "MCP server for Payrolla payroll budget simulations - enables LLMs to calculate Turkish payroll and simulate budget scenarios",
+  "author": "Payrolla",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runpayrolla/payrolla-mcp.git"
+  },
+  "homepage": "https://github.com/runpayrolla/payrolla-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/runpayrolla/payrolla-mcp/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "payrolla-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "payrolla",
+    "payroll",
+    "budget",
+    "simulation",
+    "turkish",
+    "turkey",
+    "salary",
+    "tax",
+    "ssi",
+    "llm",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "payrolla": "^0.2.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}