LeaveSheet: WH-347 payroll and PTO accrual

leavesheet-mcp

用于 LeaveSheet / TableTemplates 的两项工资计算 MCP 服务（stdio）： LeaveSheet / TableTemplates：

• 美国劳工部 WH-347 认证工资表，修订版（2025 年 1 月修订）： 适用于一周内一组员工的第 2 列和第 5–9 列、支付给各计划的福利金、第 6B 列对账。
• PTO 累计：指定日期的休假余额，支持入职日期、年度上限、工龄分级、 结转上限、已批准和待处理的申请、节假日及半天假。

这些计算是对开源 Go 包 codeberg.org/tresor2k/tabletemplates-go/wh347、.../pto 和 wh347 命令 （.../cmd/wh347）逐行移植到 JavaScript 的实现。测试套件通过 28 个黄金测试用例逐字节核对输出与 Go 引擎的结果。无需网络访问，不存储数据。

安装

需要 Node.js 22 或更高版本。

{
  "mcpServers": {
    "leavesheet": { "command": "npx", "args": ["-y", "leavesheet-mcp"] }
  }
}

工具

工具	返回内容
wh347_payroll_lines	每名员工：ST/OT/总工时（第 5 列）、6A 工资率（OT = 基本工资率 × 1.5）、6B 福利金抵免额、6C 抵扣现金、7A 项目总工资、7B 所有工作总工资、8 扣款、9 实发工资、合理性标记；各福利计划的组员总计及 6B 对账。与 wh347 --json 返回相同的 JSON。
wh347_fringe_reconcile	第 6B 列总额与支付给四项计划的福利金（健康与福利、养老金、假期/节日、培训）之和；差额小于 0.005 时，reconciles 为 true。
pto_accrual	本年工作月数、服务年限、有效累积率、累计天数（有上限）、结转天数（有上限）、已休天数、待休天数、剩余天数，以及每项申请的工作日数。

输入

wh347_payroll_lines 和 wh347_fringe_reconcile 接受 { "workers": [...] }，每个项目中的每名员工每周对应一个条目。字段名称遵循 wh347 命令的 CSV 列：worker、type（J、RA 或空）、base_rate、fringe_health_welfare、 fringe_pension、fringe_vacation、fringe_training、st_hours 和 ot_hours （最多包含 7 个每日值的数组）、cash_in_lieu_rate、gross_all_work（第 7B 列； 省略时使用 7A）、fica、federal_tax、state_tax、other_deductions。省略的 数值默认为 0；负数将被拒绝。输出中的 csv_line 是该员工在对应 CSV 中所在的行（标题行为第 1 行）。

pto_accrual 接受 policy（period：monthly 或 annual、rate、annual_cap、 carryover_max、可选的 tier1_years/tier1_bonus、tier2_years/tier2_bonus）、 hire_date、as_of、carryover、requests（start、end、start_half、 end_half、status：pending、approved、denied 或 cancelled）、holidays （日期）和 us_federal_holidays_years（为所列年份添加 11 个美国联邦节假日及其调休日期）。日期格式为 YYYY-MM-DD。

示例

wh347_payroll_lines 输入：

{ "workers": [{ "worker": "John Mason", "type": "J", "base_rate": 30,
  "fringe_health_welfare": 4, "fringe_pension": 2,
  "st_hours": [8, 8, 8, 8, 8], "ot_hours": [4], "other_deductions": 310 }] }

输出：

{
  "form": "WH-347 (Rev. January 2025)",
  "lines": [
    {
      "csv_line": 2,
      "worker": "John Mason",
      "worker_type": "J",
      "st_hours": 40,
      "ot_hours": 4,
      "total_hours": 44,
      "rate_6a_st": 30,
      "rate_6a_ot": 45,
      "fringe_6b": 264,
      "cash_in_lieu_6c": 0,
      "gross_project_7a": 1380,
      "gross_all_work_7b": 1380,
      "gross_all_work_7b_entered": false,
      "deductions_8": 310,
      "net_pay_9": 1070,
      "sanity": "ok"
    }
  ],
  "plan_totals": { "health_welfare": 176, "pension": 88, "vacation": 0, "training": 0 },
  "plan_totals_sum": 264,
  "fringe_column_6b_sum": 264,
  "reconciles": true,
  "source": "TableTemplates LeaveSheet WH-347 engine (port of codeberg.org/tresor2k/tabletemplates-go/wh347)",
  "reference_url": "https://tabletemplates.com/certified-payroll-software/",
  "disclaimer": "Calculator output only: not legal or payroll advice, not an official DOL tool."
}

pto_accrual 示例：月度政策，每月累计 1.25 天（工作满 2 年后增加 0.25 天，上限 15 天， 结转上限 5 天）；入职日期为 2023-04-03，结转 9 天，已批准的申请日期为 2026-06-29 至 2026-07-07，并包含 2026 年的联邦节假日；截至日期为 2026-07-31：

{
  "balance": {
    "months_worked": 7,
    "years_of_service": 3.328767123287671,
    "effective_rate": 1.5,
    "accrued": 10.5,
    "carryover": 5,
    "taken": 6,
    "pending": 0,
    "left": 9.5,
    "is_negative": false
  },
  "request_days": [6],
  "source": "TableTemplates LeaveSheet PTO engine (port of codeberg.org/tresor2k/tabletemplates-go/pto)",
  "reference_url": "https://tabletemplates.com/pto-tracking-software/",
  "disclaimer": "Calculator output only: not legal or payroll advice; state paid-leave laws are not encoded."
}

（2026 年 7 月 3 日是独立日的调休日期，因此申请期间的 7 个工作日按 6 天计算。）

限制

• 这不是美国劳工部的官方工具，也不构成法律或工资建议。WH-347 工具不会 查询现行工资率、判定工作类别或计算税款：工资率和扣款须手动输入。ST/OT 工时划分须手动输入，不会自动计算。
• WH-347 金额仅在输出时四舍五入到美分（正好一半时向正无穷方向取整），计算过程中不会舍入。PTO 数值不会舍入。
• PTO：按月累计（入职月份按整月计算），服务年限 = 天数 / 365；每年 1 月 1 日重新开始累计；结转天数使用你输入的值，并受政策上限限制。未编码各州的带薪休假法律；内置节假日仅包括美国联邦节假日。

开发

npm install
npm test                      # parity with the Go engines + stdio smoke test
node scripts/gen-golden.mjs   # regenerate test/golden.json (needs Go 1.24 and the Go sources)

许可证：MIT。