LeaveSheet: WH-347 payroll and PTO accrual

leavesheet-mcp

次の2種類の給与計算に対応するMCPサーバー（stdio）です。 LeaveSheet / TableTemplates：

• 米国労働省の認定給与明細フォーム WH-347（改訂版、2025年1月改訂）： 1週間分の作業員について、2列目と5～9列目、各プランへの支給福利厚生費、6B列の照合を計算します。
• 有給休暇の累積：入社日、年間上限、勤続年数に応じた段階制、繰越上限、承認済みおよび申請中の休暇、祝日、半日休暇を考慮して、指定日時点の休暇残高を計算します。

計算処理は、オープンソースの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	作業員ごとの通常／時間外／合計時間（5列目）、6Aの賃金率（時間外＝基本賃金率×1.5）、6Bの福利厚生費控除額、6Cの現金補填額、プロジェクトの総支給額（7A）、全業務の総支給額（7B）、控除額（8）、手取り額（9）、整合性フラグを返します。また、各福利厚生プランの作業員合計と6Bの照合結果も返します。wh347 --json と同じJSONです。
wh347_fringe_reconcile	6B列の合計と4つのプラン（健康・福利厚生、年金、有給休暇／祝日、研修）への支給福利厚生費の合計を照合します。差が0.005未満の場合、reconciles は真になります。
pto_accrual	今年の勤務月数、勤続年数、適用される累積率、累積日数（上限適用後）、繰越日数（上限適用後）、取得済み日数、申請中の日数、残日数、および各申請の勤務日数を返します。

入力

wh347_payroll_lines と wh347_fringe_reconcile は { "workers": [...] } を受け取ります。各エントリは、1つのプロジェクトにおける作業員の1週間分です。フィールド名は 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."
}

月あたり1.25日の累積率（勤続2年後は+0.25日、上限15日、繰越上限5日）のポリシーを使用し、2023-04-03に入社、9日を繰り越し、2026-06-29から2026-07-07までの申請が1件承認済みで、2026年の連邦祝日を指定した場合の、2026-07-31時点の pto_accrual：

{
  "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ツールは、適用賃金率の照会、作業の分類、税金の計算を行いません。賃金率と控除額は入力してください。通常時間と時間外労働時間の内訳も、計算されるのではなく入力します。
• 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。