# mcp-jp-paid-leave [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/skypier-jp-works/mcp-jp-paid-leave  
**GitHub Stars:** 0  
**npm Downloads (last month):** 178  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-jp-paid-leave

## Description
MCP server for Japanese statutory annual paid leave (nenkyu) calculations.

## Tools
Capabilities this server exposes over MCP:

- **calculate_entitlement** — Computes the grant date and number of days for a given grant occurrence, from hire date and reference-date method
- **check_attendance_rate** — Checks whether the 80% attendance-rate requirement is met, with a numerator/denominator breakdown
- **list_grant_schedule** — Lists the grant schedule for a given number of years from the hire date
- **proportional_entitlement** — Computes the proportional grant for part-time workers, based on weekly/annual scheduled working days
- **calculate_carryover** — Computes carryover, forfeiture under the 2-year prescription period, and remaining balance
- **check_mandatory_five_days** — Determines whether an employee is subject to the mandatory 5-day rule, and reports compliance status
- **apply_company_policy** — Applies a company policy on top of the statutory minimum, correcting and warning if it falls short

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-jp-paid-leave": {
    "command": "npx",
    "args": ["-y","mcp-jp-paid-leave"]
  }
}
```

## Documentation & README

# mcp-jp-paid-leave

[日本語版 README はこちら](https://github.com/skypier-jp-works/mcp-jp-paid-leave/blob/HEAD/README.ja.md)

An [MCP](https://modelcontextprotocol.io) (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](#versioning-policy) and [Maintenance policy](#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)

| Tool | Description |
| --- | --- |
| `calculate_entitlement` | Computes the grant date and number of days for a given grant occurrence, from hire date and reference-date method |
| `check_attendance_rate` | Checks whether the 80% attendance-rate requirement is met, with a numerator/denominator breakdown |
| `list_grant_schedule` | Lists the grant schedule for a given number of years from the hire date |
| `proportional_entitlement` | Computes the proportional grant for part-time workers, based on weekly/annual scheduled working days |
| `calculate_carryover` | Computes carryover, forfeiture under the 2-year prescription period, and remaining balance |
| `check_mandatory_five_days` | Determines whether an employee is subject to the mandatory 5-day rule, and reports compliance status |
| `apply_company_policy` | Applies a company policy on top of the statutory minimum, correcting and warning if it falls short |

### 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](#versioning-policy) and
[CHANGELOG.md](https://github.com/skypier-jp-works/mcp-jp-paid-leave/blob/HEAD/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):

| Argument | Meaning |
| --- | --- |
| `scheduledWorkingDays` | Total scheduled working days for the period (days with a work obligation; excludes scheduled days off) |
| `actualWorkedDays` | Days actually worked |
| `paidLeaveTakenDays` | Days of annual paid leave taken |
| `workInjuryOrIllnessLeaveDays` | Days on leave for a work-related injury or illness |
| `maternityLeaveDays` | Days of maternity leave (Labor Standards Act Article 65) |
| `childcareOrFamilyCareLeaveDays` | Days of childcare or family-care leave |
| `employerCausedSuspensionDays` | Days suspended for reasons attributable to the employer (including employer-caused management/operational-obstacle suspension) |
| `lawfulLaborDisputeDays` | Days with no work provided due to a lawful strike/labor dispute |
| `forceMajeureSuspensionDays` | Days suspended due to force majeure |
| `workedOnScheduledDayOffDays` | Days worked on what was originally a scheduled day off — **not** included in `scheduledWorkingDays` |
| `otherAbsenceDays` | Ordinary absence not covered by any category above (unauthorized absence, personal illness, etc.) |

`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

For employees granted 10 or more days of annual paid leave, determines compliance with the employer's
obligation to have the employee use 5 days within 1 year of the grant date (Labor Standards Act Article
39, paragraphs 7–8). Days taken at the employee's own request, or via a planned-leave scheme, count
against the 5-day requirement.

This obligation itself was introduced by an amendment that took effect on **April 1, 2019**. If the grant
date (`grantDate`) is earlier than that, the tool reports the employee as not subject to the rule
regardless of the number of days granted, since the obligation did not yet exist.

### 7. apply_company_policy

Pass `legalMinimumDays` (the statutory minimum computed by another tool) and `companyPolicyDays`
(optional — your company's policy value). If the company policy falls short of the statutory minimum, the
result is automatically corrected to the statutory minimum, with a `warning`.

## The `meta` field on every response

Every tool response includes a `meta` block, separate from the statutory calculation itself:

```json
"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`: the date this server's data was last checked against primary sources.
- `rulesUsed`: the rules actually used to compute this response, with their effective date (only when
  verified) and source URL.
- `staleWarning`: a bilingual (Japanese/English) warning message when either of the following applies
  (otherwise `null`):
  - more than 6 months have passed since `dataVerifiedOn` (compared against the actual current time), or
  - the calculation-target date is more than 2 years past the verification date (a legal amendment may
    have occurred by then).

## Versioning policy

- **Any update to statutory data** (grant-days tables, proportional-grant table, eligibility requirements,
  etc.) **bumps the minor version** (e.g. 1.1.0 → 1.2.0). Patch versions are reserved for bug fixes and
  documentation.
- **Any breaking change to a tool's arguments** (adding/removing/changing the meaning of a parameter such
  that existing callers break) **bumps the major version** (e.g. 1.3.0 → 2.0.0).
- Statutory data and spec changes are recorded in [CHANGELOG.md](https://github.com/skypier-jp-works/mcp-jp-paid-leave/blob/HEAD/CHANGELOG.md), noting when and which
  amendment or change was addressed.
- Past legal amendments accumulate as "rule generations with an effective date." Existing generations are
  never rewritten — a new generation is added instead, so past-period results remain unaffected.

## Maintenance policy

- The maintainer intends to update `src/leaveRules.ts` whenever the Labor Standards Act, its enforcement
  regulations, or related MHLW notices/directives are amended. Since this server never makes network calls
  at runtime, **reflecting an amendment requires a manual update**.
- If you are aware of a legal amendment (its effective date and what changed), please report it via GitHub
  Issues: https://github.com/skypier-jp-works/mcp-jp-paid-leave/issues
- Before making an important labor/HR decision, check `meta.dataVerifiedOn` and `meta.staleWarning`, and
  consult the latest law or a qualified professional as needed.

## Sources (primary references)

The statutory rules were implemented after actually retrieving and checking the following primary sources
— not from memory (last checked: 2026-07-28). If these figures change due to a legal amendment,
`src/leaveRules.ts` must be updated manually (this server never makes network calls at runtime).

- Labor Standards Act, current text (Article 39 paragraphs 1, 2, 3, 7, 8, 10; Article 13; Article 115;
  Article 120): e-Gov Japanese Law Search
  https://laws.e-gov.go.jp/law/322AC0000000049
- Introduction, effective date (1999-04-01), and transitional schedule (through 2001-03-31) of the
  standard grant-days table: Act to Partially Amend the Labor Standards Act (Act No. 112 of 1998),
  Supplementary Provisions Articles 1 and 135
  https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/h143112.htm
- Proportional grant requirements and table (Appended Table 1): Ordinance for Enforcement of the Labor
  Standards Act, Article 24-3
  https://laws.e-gov.go.jp/law/322M40000100023
- Deemed-attendance treatment of days of paid leave taken: Directive Hakki No. 17, September 13, 1947
  https://www.mhlw.go.jp/web/t_doc?dataId=00tb1896&dataType=1&pageNo=1
- Days excluded from total working days: Directive Kihatsu 0710 No. 3, July 10, 2013
  https://www.mhlw.go.jp/web/t_doc?dataId=00tb9536&dataType=1&pageNo=1
- Requirements for the uniform basis-date practice ("seiitsu-teki toriatsukai") / split grants: Directive
  Kihatsu No. 1, January 4, 1994
  https://www.mhlw.go.jp/web/t_doc?dataId=00tb1911&dataType=1&pageNo=1
- Introduction and effective date (2019-04-01) of the mandatory 5-day rule: Act on Arrangement of Related
  Acts to Promote Work Style Reform (Act No. 71 of 2018), Supplementary Provisions Articles 1 and 4
  https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/19620180706071.htm
  (MHLW's explanatory leaflet is also provided for reference)
  https://www.mhlw.go.jp/content/001140963.pdf

### Unverified items (honest disclosure)

- **When the proportional grant table took its current form** has not been confirmed. Its values match
  the current e-Gov text, but no effective date is asserted (see `PROPORTIONAL_GRANT_TABLE` in
  `src/leaveRules.ts`).
- **Whether the 80% attendance threshold or the 2-year prescription period have ever changed** since
  enactment has not been checked — only that they match the current statutory text.
- **The 2-year prescription period (Labor Standards Act Article 115) does not name "annual paid leave"**
  in its text. It is a general rule ("claims other than wage claims: 2 years"); that paid-leave claims fall
  under it rests on administrative interpretation and established practice, not an explicit statutory
  reference.
- **The exact grant-days figures that applied before 2001-04-01** (including during the 1999–2001
  transitional period) have not been verified. Calculations for that period return an error.

## Setup

### 1. Requirements

- [Node.js](https://nodejs.org/) (LTS recommended)

```bash
node --version
```

### 2. Install dependencies

```bash
npm install
```

### 3. Build

```bash
npm run build
```

This produces `build/index.js`.

## Using it from Claude Desktop

Add the following to your Claude Desktop config file (`claude_desktop_config.json`):

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

Config file location:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Restart Claude Desktop afterward to make tools like `calculate_entitlement` available.

## Running tests

38 automated tests cover all functionality:

```bash
npm test
```

All lines should show `✔` (pass).

## Project structure

```
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
```

## Related tools

Other MCP servers by the same author:

- [mcp-jp-calendar](https://github.com/skypier-jp-works/mcp-jp-calendar) — calculates Japanese business days, national holidays, gotobi settlement days, and fiscal quarters
- [mcp-jp-corporate-id](https://github.com/skypier-jp-works/mcp-jp-corporate-id) — validates and normalizes Japanese corporate numbers and qualified invoice registration numbers

## License

[MIT](https://github.com/skypier-jp-works/mcp-jp-paid-leave/blob/HEAD/LICENSE)