taiwan-payroll 是一个开源的台湾劳健保劳退法定费用计算引擎，定位为「计算引擎」而非「法遵保证」。它根据输入的薪资与身份，计算劳保（含就保）、健保、劳退、职灾与二代健保补充保费的各方负担，并涵盖薪资所得扣缴、月中到职／离职破月、健保补充保费申报媒体档，以及劳保老年给付试算。
主要能力方面，引擎内置民国113至115（2024至2026）年度官方参数，级距表与费率逐级取自主管机关公告，计算结果对官方范例黄金向量逐位元验证。TS 与 Python 读取同一份 data/、运行同一套 testdata/，结果逐位元相同。core 不携带任何 runtime 套件，Python 版为纯 stdlib。
使用方式提供三种接口：TypeScript（npm）、Python（PyPI，pip install taiwan-payroll）以及 MCP server（供 AI 助理呼叫）。MCP server 提供远端免安装端点 https://taiwan-payroll.simoko.workers.dev/mcp （Streamable HTTP），或本地 npx taiwan-payroll-mcp （stdio）。另有线上试算网页 https://taiwan-payroll.vercel.app ，免安装，浏览器直接算。API 详见文件站 /docs/api。
具体功能包括：健保破月采「月底归属原则」，以月底所属投保单位计收整月——到职当月计整月、离职当月不计；由申报资料产生健保署「补充保险费明细申报档」（CSV／Big5），涵盖6类所得：奖金(62)、兼职薪资(63)、执行业务(65)、股利(66)、利息(67)、租金(68)，每个产生器皆以健保署官方范例逐位元验证；股利因含股票股利／雇主扣除等情形，逐列保费由呼叫端提供（另附便利函数 calcDividendPremium）；Big5 编码在 TS 由呼叫端编码，Python 提供 to_big5_bytes()。劳保老年给付试算涵盖三种：老年年金（择优两式，提前/延后 claimOffsetMonths，±4%/年、上限±5年）、老年一次金（年资每满1年发1个月，逾60岁后年资最多5年）、一次请领（基数制，前15年每年1基数、超过部分每年2基数、前60上限45、合并上限50，平均采退保前36个月）。
适用场景为台湾薪资计算、劳健保劳退费用试算、补充保费申报档产生及老年给付试算等。限制方面：试算仅供参考，实际以劳保局核定为准；本套件不构成法律或会计建议；实际应缴金额以劳保局、健保署核发之缴款单为准。目前内建民国113／114／115三个年度，可用年度由 getAvailableYears() 取得，以 createPayrollEngine({ year }) 指定。
