mcp-jp-paid-leave

日本語版 README はこちら

An MCP (Model Context Protocol) server for calculating Japan's statutory annual paid leave ("nenkyu") under the Labor Standards Act: entitlement grants, attendance-rate checks, proportional grants for part-time workers, carryover/prescription, and the 5-day mandatory-use rule. It lets MCP-capable clients such as Claude Desktop invoke these calculations directly.

No network access is used at runtime. All statutory rules are embedded as constants in the code.

Core design principle

• Every number and judgment this server returns is the statutory minimum under the Labor Standards Act.
• Any company policy that grants more than the statutory minimum must be passed explicitly as an argument to apply_company_policy.
• Every tool response includes a basis field:
  • "legal_minimum": the statutory minimum value
  • "company_policy_applied": the value after applying a company policy (only from apply_company_policy)
• If a company policy value is below the statutory minimum, apply_company_policy automatically corrects it to the statutory minimum and returns a warning.
• Resilience to legal amendments: rules that are known to have changed as of a specific effective date (such as the standard grant-days table) are stored as "rule generations with an effective date," and the generation valid at the calculation-target date is selected automatically. Calculating for a past period still uses the rules that were in force at that time. Every tool response includes a meta field with the effective date and source URL of each rule actually used, the date the data was last verified (dataVerifiedOn), and a staleness warning when applicable. See Versioning policy and Maintenance policy below.

Disclaimer

• This tool computes the statutory minimum under the Labor Standards Act. The accuracy of its output is not guaranteed.
• If your work rules (shugyo kisoku) provide more favorable terms to employees, those always take precedence over this tool's output.
• For any important labor/HR decision (including anything touching discipline, dismissal, or payroll), always confirm with a qualified professional (e.g., a licensed Shakai Hoken Roumushi / labor and social security attorney).

Tools (7 total)

1. calculate_entitlement

Give the hire date (hireDate) and which grant occurrence to compute (grantNumber: 1 = the first grant at 6 months of service, 2 = the second grant at 1 year 6 months, etc.).

• referenceDateMethod: "individual" (the statutory default — each employee's own basis date) or "uniform" (a company-wide unified basis date, i.e. "seiitsu-teki toriatsukai")
• uniformBasisMonthDays: required when uniform is used — an array of "MM-DD" candidate basis dates (e.g. ["04-01"] or ["04-01","10-01"])
• weeklyScheduledDays / annualScheduledDays / weeklyScheduledHours: optional, for proportional grants (part-time workers)

For the uniform method, the server correctly computes the recurring chain: once the first front-loaded basis date is found, every subsequent grant recurs on the same month/day each year. Any period shortened by front-loading is returned as shortenedPeriod, with a note that this period must be treated as fully attended for attendance-rate purposes (when calling check_attendance_rate, count it as ordinary worked days in actualWorkedDays etc. rather than as absence — don't carve it out as unattended).

Returns an error if the statutory basis date (statutoryBasisDate, not the hire date) falls before 2001-04-01. The current grant-days table (introduced by Act No. 112 of 1998) took effect for most purposes on 1999-04-01, but a transitional schedule with lower figures for certain tenure brackets applied through 2001-03-31. This tool does not implement that transitional schedule, so 2001-04-01 (once the transition was fully complete) is the verified floor (see Versioning policy and CHANGELOG.md).

This floor applies to each grant's own basis date, not to the hire date. No matter how old the hire date is, a specific grant computes fine as long as that grant's basis date is on or after 2001-04-01. For example, for an employee hired in 1995, computing "the most recent grant as of 2026" (the 31st grant, basis date 2025-10-01) succeeds. Only grants whose own basis date is before 2001-04-01 (e.g. that same employee's 1st grant, basis date 1995-10-01) return an error.

2. check_attendance_rate

Checks the "80% of all working days" requirement for entitlement.

Design principle: deciding whether a given day belongs in the numerator or is excluded from the denominator is exactly the value this tool should provide — and exactly where humans and AI callers are most likely to get it wrong. So the caller does not classify anything. Instead, break the period down into the following 11 day-count fields and pass them as-is (all required except asOfDate — if a category doesn't apply, pass 0 explicitly; omitting a field is an error, not an assumed zero):

scheduledWorkingDays must equal the sum of the other 9 fields (everything except workedOnScheduledDayOffDays). A mismatch is an error — the tool never guesses at a reconciling number.

Based on Labor Standards Act Article 39 paragraph 10 / Article 65, Directive Hakki No. 17 (Sept. 13, 1947), and Directive Kihatsu 0710 No. 3 (July 10, 2013), the tool classifies each field into one of four treatments internally:

• Added to the numerator: actualWorkedDays, paidLeaveTakenDays, workInjuryOrIllnessLeaveDays, maternityLeaveDays, childcareOrFamilyCareLeaveDays
• Ordinary absence (stays in the denominator, not added to the numerator): otherAbsenceDays
• Excluded from total working days (the denominator): employerCausedSuspensionDays, lawfulLaborDisputeDays, forceMajeureSuspensionDays (Kihatsu 0710 No. 3, Section 1-3)
• Not counted at all (never a scheduled working day to begin with): workedOnScheduledDayOffDays (Kihatsu 0710 No. 3, Section 1-1)

The result's breakdown.classification always includes each field's day count, its resulting treatment, and the specific legal basis (statute or directive) for that treatment.

3. list_grant_schedule

Same arguments as calculate_entitlement, plus numberOfYears (how many grant occurrences to list).

For long-tenured employees whose early grants have a basis date before the verified floor (2001-04-01), the call as a whole no longer fails. Those specific grants are returned as supported: false placeholders (no grant-days figure), while every other grant is computed normally with supported: true. Check the supported field on each entry.

4. proportional_entitlement

Computes the proportional grant from weekly scheduled days (1–4) or annual scheduled days. Returns an error if weekly scheduled hours are 30 or more, or weekly scheduled days are 5 or more (such workers use the standard table instead).

5. calculate_carryover

• grants: array of grant records (grantDate, grantedDays)
• usageRecords: array of usage records (date, days)
• asOfDate: the date to evaluate as of

Each grant expires 2 years after its grant date (Labor Standards Act Article 115). Usage is consumed against the oldest grant first (this is common practice, not an explicit statutory rule — follow your work rules if they specify otherwise).

6. check_mandatory_five_days