mcp-jp-paid-leave

mcp-jp-paid-leave

点击此处查看日语版 README

一个用于依据《劳动基准法》计算日本法定年休（「年休」）的 MCP（Model Context Protocol）服务：包括休假权利授予、出勤率检查、兼职员工的按比例授予、结转／时效，以及强制休假 5 天的规定。 它允许 Claude Desktop 等支持 MCP 的客户端直接调用这些计算功能。

运行时不使用网络。所有法定规则均以常量形式嵌入代码中。

核心设计原则

• 此服务返回的所有数值和判断均为《劳动基准法》规定的法定最低标准。
• 任何高于法定最低标准的公司政策，都必须作为参数显式传递给 apply_company_policy。
• 每个工具响应都包含一个 basis 字段：
  • "legal_minimum"：法定最低标准值
  • "company_policy_applied"：应用公司政策后的值（仅来自 apply_company_policy）
• 如果公司政策值低于法定最低标准，apply_company_policy 会自动将其调整至法定最低标准，并返回 warning。
• 适应法律修订：已知在特定生效日期发生变更的规则（例如标准授予天数表），会按「带有生效日期的规则版本」存储，并自动选择在计算目标日期有效的版本。计算过去期间时，仍使用当时生效的规则。每个工具响应都包含一个 meta 字段，其中列出实际使用的每条规则的生效日期和来源 URL、数据上次核验日期（dataVerifiedOn），以及适用时的过时警告。请参阅下文的版本管理政策和维护政策。

免责声明

• 此工具根据《劳动基准法》计算法定最低标准。无法保证其输出准确。
• 如果贵公司的工作规则（就业规则）为员工规定了更优厚的待遇，应始终以这些规则为准，而非此工具的输出。
• 对于任何重要的劳动／人力资源决策（包括涉及纪律处分、解雇或薪资的事项），务必向合格的专业人士确认（例如持证的社会保险劳务士／劳动与社会保障律师）。

工具（共 7 个）

工具	说明
calculate_entitlement	根据入职日期和基准日期计算方式，计算指定授予批次的授予日期和天数
check_attendance_rate	检查是否满足 80% 的出勤率要求，并列出分子／分母明细
list_grant_schedule	列出从入职日期起指定年数内的授予计划
proportional_entitlement	根据每周／每年的计划工作天数，计算兼职员工的按比例授予天数
calculate_carryover	计算结转、两年时效下的失效天数，以及剩余余额
check_mandatory_five_days	判断员工是否适用强制休假 5 天的规定，并报告合规状态
apply_company_policy	在法定最低标准基础上应用公司政策；若低于最低标准则进行调整并发出警告

1. calculate_entitlement

提供入职日期（hireDate）以及要计算的授予次数（grantNumber：1 = 入职满 6 个月时的首次授予，2 = 入职满 1 年 6 个月时的第二次授予，以此类推）。

• referenceDateMethod："individual"（法定默认方式——以每位员工各自的基准日期为准）或 "uniform"（公司统一的基准日期，即「统一处理」）
• uniformBasisMonthDays：使用 uniform 时必填——一组 "MM-DD" 格式的候选基准日期 （例如 ["04-01"] 或 ["04-01","10-01"]）
• weeklyScheduledDays / annualScheduledDays / weeklyScheduledHours：可选，用于按比例授予 （兼职员工）

对于 uniform 方式，服务会正确计算后续的循环日期：找到首次提前授予的基准日期后，之后的每次授予都会在每年的同一月日进行。因提前授予而缩短的任何期间都会以 shortenedPeriod 返回，并附有说明，指出在计算出勤率时必须将此期间视为全勤（调用 check_attendance_rate 时，将其作为正常工作日计入 actualWorkedDays 等字段，而不是算作缺勤——不要将其排除在出勤时间之外）。

如果法定基准日期（statutoryBasisDate，而非入职日期）早于 2001-04-01，则返回错误。当前的授予天数表（由 Act No. 112 of 1998 引入）在大多数方面于 1999-04-01 生效，但某些工龄区间在 2001-03-31 前适用较低数值的过渡安排。本工具未实现该过渡安排，因此 2001-04-01（过渡期完全结束后的日期）是经验证的下限（参见版本管理政策和CHANGELOG.md）。

**此下限适用于每次授予各自的基准日期，而非入职日期。**无论入职日期有多早，只要某次授予的基准日期在 2001-04-01 当天或之后，该次计算就能成功。例如，对于一名于 1995 年入职的员工，计算「截至 2026 年最近一次的授予」（第 31 次授予，基准日期为 2025-10-01）会成功。只有该次授予自身的基准日期早于 2001-04-01 时（例如同一员工的第 1 次授予，基准日期为 1995-10-01），才会返回错误。

2. check_attendance_rate

检查是否满足“所有工作日的 80%”这一权益条件。

设计原则：判断某一天应计入分子还是应从分母中排除，正是此工具应该提供的价值，也是人工调用者和 AI 调用者最容易出错的地方。因此，调用者无需进行分类。请将期间拆分为以下 11 个天数类别，并按原样传入（除 asOfDate 外，所有参数均为必填；如果某个类别不适用，请明确传入 0；省略字段会报错，不会被视为零值）：

参数	含义
scheduledWorkingDays	期间内计划工作日总数（有工作义务的日子；不包括计划休息日）
actualWorkedDays	实际工作的天数
paidLeaveTakenDays	已休带薪年假的天数
workInjuryOrIllnessLeaveDays	因工伤或职业病休假的天数
maternityLeaveDays	产假天数（《劳动基准法》第 65 条）
childcareOrFamilyCareLeaveDays	育儿或家庭护理休假的天数
employerCausedSuspensionDays	因雇主责任而停工的天数（包括雇主造成的管理或运营障碍导致的停工）
lawfulLaborDisputeDays	因合法罢工或劳动争议而未提供工作的天数
forceMajeureSuspensionDays	因不可抗力而停工的天数
workedOnScheduledDayOffDays	在原定休息日工作的天数——不计入 scheduledWorkingDays
otherAbsenceDays	不属于上述任何类别的一般缺勤（擅自缺勤、个人疾病等）

scheduledWorkingDays 必须等于其他 9 个字段的总和（不包括 workedOnScheduledDayOffDays）。如果不匹配，则会报错——此工具不会猜测用于调平差额的数值。

根据《劳动基准法》第 39 条第 10 款和第 65 条、1947 年 9 月 13 日第 17 号函释，以及 2013 年 7 月 10 日第 0710 号第 3 号函释，此工具会在内部将每个字段归入以下四种处理方式之一：

• 计入分子：actualWorkedDays、paidLeaveTakenDays、workInjuryOrIllnessLeaveDays、maternityLeaveDays、childcareOrFamilyCareLeaveDays
• 一般缺勤（保留在分母中，不计入分子）：otherAbsenceDays
• 从总工作日数（分母）中排除：employerCausedSuspensionDays、lawfulLaborDisputeDays、forceMajeureSuspensionDays（第 0710 号第 3 号函释，第 1-3 节）
• 完全不计入（本来就不是计划工作日）：workedOnScheduledDayOffDays（第 0710 号第 3 号函释，第 1-1 节）

结果中的 breakdown.classification 始终包含每个字段的天数、相应的处理方式，以及该处理方式的具体法律依据（法规或函释）。

3. list_grant_schedule

参数与 calculate_entitlement 相同，另加 numberOfYears（要列出的授予次数）。

对于任职时间较长、早期授予的基准日期早于经核实的下限（2001-04-01）的员工，整个调用不再失败。对于这些特定授予，会返回 supported: false 占位项（不提供授予天数）；其他授予则照常计算，并返回 supported: true。请检查每项的 supported 字段。

4. proportional_entitlement

根据每周计划工作天数（1–4 天）或每年计划工作天数计算按比例授予的权益。如果每周计划工作时数达到或超过 30 小时，或每周计划工作天数达到或超过 5 天，则返回错误（此类员工应使用标准表格）。

5. calculate_carryover

• grants：授权记录数组（grantDate、grantedDays）
• usageRecords：使用记录数组（date、days）
• asOfDate：评估基准日期

每笔授权会在授权日期 2 年后到期（《劳动基准法》第 115 条）。使用天数会优先从最早的授权中扣除（这是常见做法，并非明确的法定规则；如果工作规则另有规定，请遵循工作规则）。

6. check_mandatory_five_days

对于获授 10 天或以上带薪年假的员工，判断雇主是否履行了在授权日期起 1 年内让员工休满 5 天的义务（《劳动基准法》第 39 条第 7～8 款）。员工自行申请休假或通过计划休假制度安排休假的天数，均计入这 5 天的要求。

这项义务本身由一项于 2019 年 4 月 1 日生效的修正案引入。如果授权日期（grantDate）早于该日期，则无论获授天数是多少，工具都会报告该员工不适用此规则，因为当时这项义务尚不存在。

7. apply_company_policy

传入 legalMinimumDays（由另一个工具计算出的法定最低天数）和 companyPolicyDays（可选，即贵公司的政策值）。如果公司政策低于法定最低天数，结果会自动调整至法定最低天数，并附带 warning。

每个响应中的 meta 字段

每个工具响应都包含一个 meta 区块，与法定计算本身分开：

"meta": {
  "dataVerifiedOn": "2026-07-28",
  "rulesUsed": [
    {
      "rule": "Standard grant-days table (Labor Standards Act Article 39)",
      "effectiveFrom": "2001-04-01",
      "sources": [{ "label": "...", "url": "https://..." }]
    }
  ],
  "staleWarning": null
}

• dataVerifiedOn：上次根据一手资料核对本服务端数据的日期。
• rulesUsed：计算此响应时实际使用的规则，以及其生效日期（仅在已核实时提供）和来源 URL。
• staleWarning：在以下任一情况出现时显示双语（日语／英语）警告消息（否则为 null）：
  • 距离 dataVerifiedOn 已超过 6 个月（以实际当前时间为准），或
  • 计算目标日期比核实日期晚超过 2 年（届时可能已发生法律修正）。

版本控制政策

• 任何法定数据更新（授权天数表、按比例授权表、资格要求等）都会提升次版本号（例如 1.1.0 → 1.2.0）。补丁版本仅用于错误修复和文档更新。
• 任何对工具参数的破坏性更改（添加、移除或更改参数含义，导致现有调用方无法继续使用）都会提升主版本号（例如 1.3.0 → 2.0.0）。
• 法定数据和规范变更会记录在 CHANGELOG.md 中，并注明涉及的修正案或变更及其处理时间。
• 过去的法律修正案会作为“带生效日期的规则代次”累积。现有代次永不重写，而是添加新的代次，以免影响过去时段的计算结果。

维护政策

• 维护者计划在《劳动基准法》、其实施条例或厚生劳动省相关通知／指令修订时更新 src/leaveRules.ts。由于本服务端在运行时不会发起网络请求，要反映修正内容，必须手动更新。
• 如果您了解到法律修正（其生效日期及变更内容），请通过 GitHub Issues 报告：https://github.com/skypier-jp-works/mcp-jp-paid-leave/issues
• 在作出重要的劳动／人力资源决策前，请检查 meta.dataVerifiedOn 和 meta.staleWarning，并酌情查阅最新法律或咨询合格专业人士。

来源（主要参考资料）

法规规则是在实际检索并核对以下主要来源后实现的 ——并非凭记忆（最后核对时间：2026-07-28）。如果这些数据因法律修订而发生变化， 必须手动更新 src/leaveRules.ts（此服务不会在运行时发起网络请求）。

• 《劳动基准法》现行文本（第 39 条第 1、2、3、7、8、10 款；第 13 条；第 115 条； 第 120 条）：e-Gov 日本法律检索 https://laws.e-gov.go.jp/law/322AC0000000049
• 标准授予天数表的引入、生效日期（1999-04-01）和过渡安排（截至 2001-03-31）：《部分修订〈劳动基准法〉的法律》（1998 年第 112 号法律）， 附则第 1 条和第 135 条 https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/h143112.htm
• 按比例授予的要求和表格（附表 1）：《劳动基准法实施规则》第 24-3 条 https://laws.e-gov.go.jp/law/322M40000100023
• 带薪休假天数的出勤日认定：指令 Hakki No. 17，1947 年 9 月 13 日 https://www.mhlw.go.jp/web/t_doc?dataId=00tb1896&dataType=1&pageNo=1
• 不计入总工作天数的日期：指令 Kihatsu 0710 No. 3，2013 年 7 月 10 日 https://www.mhlw.go.jp/web/t_doc?dataId=00tb9536&dataType=1&pageNo=1
• 统一基准日期做法（「seiitsu-teki toriatsukai」）/分段授予的要求：指令 Kihatsu No. 1，1994 年 1 月 4 日 https://www.mhlw.go.jp/web/t_doc?dataId=00tb1911&dataType=1&pageNo=1
• 强制休假 5 天规则的引入和生效日期（2019-04-01）：《促进工作方式改革相关法律整备法》（2018 年第 71 号法律），附则第 1 条和第 4 条 https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/19620180706071.htm （另提供 MHLW 的说明手册供参考） https://www.mhlw.go.jp/content/001140963.pdf

未经核实的事项（如实披露）

• 按比例授予表何时采用现行形式尚未确认。其数值与当前 e-Gov 文本一致，但未断言其生效日期（参见 src/leaveRules.ts 中的 PROPORTIONAL_GRANT_TABLE）。
• 80% 出勤率门槛或 2 年时效期是否曾发生变化尚未核查——仅确认其与现行法条文本一致。
• 2 年时效期（《劳动基准法》第 115 条）并未在文本中提及「带薪年假」。这是一项一般规则（「工资请求权以外的请求权：2 年」）；带薪休假请求权适用该规则，是基于行政解释和既有惯例，而非明确的法条规定。
• 2001-04-01 之前适用的确切授予天数（包括 1999–2001 年过渡期内）尚未核实。该时期的计算会返回错误。

设置

1. 要求

• Node.js（建议使用 LTS 版本）

node --version

2. 安装依赖项

npm install

3. 构建

npm run build

此操作会生成 build/index.js。

在 Claude Desktop 中使用

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "jp-paid-leave": {
      "command": "node",
      "args": ["/absolute/path/mcp-jp-paid-leave/build/index.js"]
    }
  }
}

配置文件位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

之后重启 Claude Desktop，即可使用 calculate_entitlement 等工具。

运行测试

38 项自动化测试覆盖了所有功能：

npm test

所有行都应显示 ✔（通过）。

项目结构

mcp-jp-paid-leave/
├── src/
│   ├── leaveRules.ts  … statutory rule constants (generations with effective dates), source citations
│   ├── dataMeta.ts    … rule-generation selection + staleness-warning infrastructure
│   ├── errors.ts      … shared validation error class
│   ├── dateUtil.ts    … shared date-arithmetic utilities
│   ├── leaveCalc.ts   … core calculation logic (entitlement, attendance rate, carryover, etc.)
│   └── index.ts       … the MCP server itself (exposes the 7 tools)
├── tests/
│   ├── leaveCalc.test.ts … automated tests
│   └── dataMeta.test.ts  … tests for rule-generation selection and staleness warnings
├── package.json
├── tsconfig.json
├── CHANGELOG.md       … record of statutory-data updates and spec changes
├── LICENSE
├── README.md          … this file
└── README.ja.md        … Japanese version

相关工具

同一作者开发的其他 MCP 服务：

• mcp-jp-calendar — 计算日本营业日、法定节假日、五十日结算日和财务季度
• mcp-jp-corporate-id — 验证并规范化日本法人编号和合格发票注册编号

许可证

MIT