mcpField
日
日本の給与・社会保険・労働法

日本の給与・社会保険・労働法

リモート
github.com/kishida-devil金融データ28 週間前に更新
リポジトリ

日本の給与・社会保険・労働法 について

日本の給与・労務担当者やソフトウェア開発者向けの、給与計算APIとMCPサーバーです。都道府県別の控除額や法定額を計算し、根拠となる条文や通知も返します。

主な機能

  1. 01給与・社会保険料の計算
  2. 02源泉税・賞与税の計算
  3. 03標準報酬の決定・改定
  4. 04休業免除・最低賃金データ
  5. 05営業日・祝日の計算
  6. 06根拠条文と本文の提示

活用シーン

  1. 01従業員の手取り額と控除額の算出
  2. 02都道府県別の保険料率の確認
  3. 03源泉税や休業免除月の判定
  4. 04引用された条文に基づく計算結果の確認

MCP 対応

AIアシスタント向けに、給与、税、保険、休業、法令検索など30種類のツールを提供します。リモート接続またはnpxで実行でき、HTTP APIと同じ結果を返します。

設定

リモートサーバーはインストール不要です。クライアントを選んで設定をコピーするか、ワンクリックで導入できます。

エンドポイントhttps://japan-payroll-api.tsumugi.workers.dev/mcp
インストールコマンドをコピー
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

コマンドはターミナルで実行し、JSON は各クライアントの MCP 設定に貼り付けて再起動します。認可が必要なサーバーは初回接続時にログインを求めます。

パッケージ
npmjp-payroll-mcp0.4.5

ツール

30
パラメーター型必須説明
agenumberいいえ年齢(歳)。この項目または birth_date が必須です。介護保険は40~64歳にのみ適用されるため、年齢がないと保険料を確定できません。birth_date の指定を推奨します。
as_ofstringいいえ保険料の対象月:被保険者が加入している月内の ISO 日付であり、給与支給日ではありません。雇用主は当月の給与から前月分の保険料を控除する場合があります(健康保険法第167条)。翌月控除の場合は、給与支給日の前月の日付を指定してください。年齢到達日を判定し、料率表を選択します。公表期間外の日付を指定すると、現行の料率表ではなく 422 が返されます。
columnenumいいえ従業員が扶養控除等申告書を提出している場合は 甲(通常はこちら)、提出していない場合は 乙を指定します。デフォルトは 甲です。kou | otsu
birth_datestringいいえ生年月日(YYYY-MM-DD)。`age` よりこちらを強く推奨します。「年齢計算ニ関スル法律」では、年齢に達する日は誕生日の前日とされるため、月の1日生まれの人は前月に年齢の境界を越え、単純計算より1か月早く保険料が変わります。
dependantsnumberいいえ源泉控除対象親族の人数。デフォルトは 0 です。
income_taxbooleanいいえfalse に設定すると源泉徴収税を省略します。デフォルトは true です。
prefecturestringはい雇用主の適用事業所が所在する都道府県。英語("Tokyo")、日本語("東京" または "東京都")、または JIS コード 1-47 を指定できます。健康保険料率は都道府県によって異なりますが、年金保険料率は異なりません。
resident_taxnumberいいえ控除する住民税額(円)。住民税は市区町村が前年の所得に対して課税するもので、このツールでは算出しません。特別徴収税額通知書に記載された金額を指定してください。
business_typeenumいいえ雇用保険料率の区分。デフォルトは general です。general | agriculture_forestry_fishery_sake | construction
commuting_farenumberいいえ自動車または自転車通勤で、通勤手当に加えて支払う妥当な運賃または通行料。commuting_distance_km を指定すると、上限額は距離区分の金額にこの額を加えたものとなり、最大 150,000 です。
monthly_salarynumberはい控除前の月額給与(円)。
employment_typeenumいいえ役員は雇用保険の被保険者ではありません(雇用保険法第4条)。会社役員の場合は "director" を指定してください。指定しないと保険料が高くなりすぎます。デフォルトは employee です。employee | director | director_employee
commuting_parkingnumberいいえ自動車または自転車通勤のために従業員が負担する月極駐車料金(円)。距離区分の金額に加算され、月額上限は 5,000 です。commuting_distance_km が必要です。電車のみで通勤する場合、加算先となる距離区分はありません。
workers_comp_typestringいいえ労災保険の事業の種類の番号。卸売/小売/飲食店/ホテルの場合は "98" などを指定します。労災保険料は全額雇用主負担です。料率は 2.5/1000~88/1000 と幅があり、安全なデフォルト値がないため、この項目を指定しない限り計算に含めません。料率表は list_workers_compensation_rates にあります。
commuting_allowancenumberいいえ月額通勤手当(円)。社会保険では全額が報酬として扱われますが、所得税では上限まで非課税です。公共交通機関の場合、月額上限は 150,000 です。monthly_salary に含めないでください。含めると課税され、含めずにこの項目にも指定しないと保険料が過少になります。内訳は earnings.items に返されます。
commuting_distance_kmnumberいいえ自動車または自転車通勤の片道距離。非課税限度額は公共交通機関の 150,000 ではなく、距離表(国税庁 No.2585)に基づきます。2 km 未満の場合、非課税額はありません。
standard_remunerationnumberいいえ算定基礎届または月額変更届で決定された標準報酬月額。分かっている場合は必ず指定してください。指定しない場合、等級は入力された給与から再計算されますが、残業がある月は誤った結果になります。月給 300,000 円の人が繁忙月に 369,469 円を得た場合、8,445 円多く控除されます。正しい金額は decide_regular_determination が返します。

詳細

jp-payroll-mcp

日本の給与計算・社会保険・労務を、表を引くのではなく計算して返すAPIとMCPサーバーです。 47都道府県の保険料率、源泉所得税、標準報酬月額の決定と改定、休業中の保険料免除、 割増賃金、年次有給休暇、最低賃金、営業日計算、令和8年分の年末調整、住民税の見込み額まで。答えには根拠の条文または通知が付きます。

公表されている料額表・税額表と1セルずつ突き合わせ、変更のたびに 4,689件 の検証を実行します。

使いかたは2通り

MCPサーバー — AIアシスタントに日本語で聞く。30ツール、無料、APIキー不要。 URL を貼るだけ(remote MCP)か、npx で入れるか:

claude mcp add --transport http jp-payroll https://japan-payroll-api.tsumugi.workers.dev/mcp
claude mcp add jp-payroll -- npx -y jp-payroll-mcp

Claude.ai のカスタムコネクタ、ChatGPT、Cursor には https://japan-payroll-api.tsumugi.workers.dev/mcp を貼ります。

HTTP API — ソフトウェアに組み込む。45エンドポイント、OpenAPI 3.0、一括処理:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&birth_date=1986-04-01"

MCPサーバーはAPIの薄い層なので、どちらも同じ答えを返します。 人が聞くのか、プログラムが聞くのかの違いです。

なぜ要るのか

自前で書くと、もっともらしく見えて間違っている数字が出ます。3月31日退職と3月30日退職では 1か月分の社会保険料が動きます(東京・40歳・月給30万円で労使合計95,130円)。4月1日生まれの人は 3月31日に40歳になるので介護保険料が1か月早く始まります。随時改定の「2等級以上」は健康保険法に 書いておらず、昭和36年保発第4号にあります。

以下は英語の詳細仕様です。


Japanese payroll, social insurance and labour law, computed rather than looked up — premiums for all 47 prefectures, withholding tax, standard remuneration decisions and revisions, leave exemptions, minimum wage — with the statute or ministerial notice each answer rests on.

Verified against the published tables cell by cell: 4,689 assertions on every change.

Two ways in

As an MCP server, for asking questions through an AI assistant. 30 tools, free, no key. Remote (paste a URL) or local (npx):

claude mcp add --transport http jp-payroll https://japan-payroll-api.tsumugi.workers.dev/mcp
claude mcp add jp-payroll -- npx -y jp-payroll-mcp

For Claude.ai custom connectors, ChatGPT and Cursor, the URL is https://japan-payroll-api.tsumugi.workers.dev/mcp.

As an HTTP API, for building it into software. 45 endpoints, OpenAPI 3.0, batch:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&birth_date=1986-04-01"

The MCP server is a thin layer over the API, so both give the same answers. Which you want depends on whether a person or a program is asking.

  • MCP server source and its own README: mcp/ · English
  • Live API: https://japan-payroll-api.tsumugi.workers.dev
  • OpenAPI spec: /openapi.json

Related tools

Japanese statutory MCP servers mostly retrieve — they hand you the text of a law and leave the reasoning to you. This one computes, and returns the provision it relied on. They fit together rather than compete:

"What does the law say?""So what do I pay?"
labor-law-mcp45 labour and social insurance laws, MHLW and JAISH notices—
tax-law-mcp24 tax laws, 17 NTA circulars, tribunal decisions—
hourei-mcp-serverAny Japanese law, via e-Gov—
jp-payroll-mcpThe 28 provisions it cites, in fullPremiums, withholding tax, grade revisions, exemptions

If you already run one of those, add this alongside it. An assistant with both picks the right one per question.

Why this exists

  • No consolidated API exists. Developers assemble this from 協会けんぽ, 厚生労働省 and each prefectural labour bureau separately.
  • The rules are fiddly. Premiums are computed on the standard monthly remuneration (a 50-grade step function), not on actual salary — except employment insurance, which uses actual salary. Pension caps at grade 32. Long-term care applies only to ages 40–64. The employee share rounds half down (≤ 0.50 yen truncates). Getting one of these wrong produces numbers that look plausible and are wrong.

MCP サーバー

ソースは mcp/ にあり、専用の README(日本語)・ English があります。npm run mcp:test でテストできます。このテストでは、実際の MCP クライアントを使って実際の stdio トランスポートを動作させます。ハンドラーに不具合があるツールでも一覧には問題なく表示され、呼び出されたときに初めて失敗するためです。

MCP サーバーは無料で、今後もずっと無料です。収益源ではなく、配布チャネルとして提供しています。npm から収益は得られず、MCP に独自の課金機能もありません。これは意図的なものです。問題は課金ではなく、すでに RapidAPI が対応しています。問題は発見されることです。そして、日本の法令データへのトラフィックが実際にある場所が MCP なのです。

エンドポイント

EndpointDescription
GET /API info and endpoint list
Payroll and insurance
GET /v1/prefecturesAll 47 prefectures with JIS codes
GET /v1/insurance-rates?prefecture=TokyoHealth, long-term care, pension, child-support rates
GET /v1/standard-remuneration?remuneration=350000Grade lookup for a monthly amount
GET /v1/standard-remuneration/tableFull 50-grade table
GET /v1/employment-insurance?business_type=generalEmployment insurance rates
GET /v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40Full deduction breakdown
Minimum wage
GET /v1/minimum-wage?prefecture=Tokyo&date=2020-01-01Rate in effect on a date
GET /v1/minimum-wage/history?prefecture=TokyoFull history since FY2002
Calendar
GET /v1/holidays?year=2026Public holidays (or from=/to= for a range)
GET /v1/holidays/check?date=2026-01-01Holiday / weekend / business-day flags
GET /v1/business-days?from=&to=Count business days in a range
GET /v1/business-days/shift?date=&days=1Move N business days forward or back
Tax
GET /v1/consumption-tax?date=&amount=&reduced=Rate in force, optionally applied to an amount
GET /v1/consumption-tax/historyEvery rate change since 1989
Identifiers
GET /v1/corporate-number/validate?number=8700110005901法人番号 check digit (Peppol ICD 0188)
GET /v1/corporate-number/check-digit?base=700110005901Check digit for a 12-digit base number
GET /v1/invoice-number/validate?number=T8700110005901Qualified invoice registration number
Withholding tax
GET /v1/withholding-tax?taxable_amount=300000&dependants=2Monthly withholding income tax (月額表)
GET /v1/withholding-tax/daily?taxable_amount=12000&column=heiDaily table (日額表), including the 丙 column
GET /v1/withholding-tax/computer?taxable_amount=400000Same, by the formula method (電算機計算の特例)
Bonuses
GET /v1/bonus-tax?bonus=500000&previous_month_pay=350000Withholding on a bonus (賞与の算出率表)
GET /v1/bonus-insurance?prefecture=Tokyo&bonus=800000&age=40Social insurance on a bonus, with both caps
Standard remuneration decisions
GET /v1/standard-remuneration/regular?months=350000:30,352000:31,349000:30定時決定 (算定基礎) from April–June
GET /v1/standard-remuneration/revision?current_remuneration=&months=&fixed_pay_change=Is a 随時改定 (月額変更) due?
GET /v1/standard-remuneration/leave-end?kind=childcare&current_remuneration=&months=Revision on returning from leave
POST /v1/standard-remuneration/annual-average年間平均による保険者算定, for seasonal work
Year-end adjustment
POST /v1/year-end-adjustment年末調整 (令和8年分): every box of the 源泉徴収簿 from ⑦ to ㉗, plus an "if filed" estimate for medical/donation/casualty deductions
Resident tax
POST /v1/resident-tax住民税の見込み額 from last year's income and the municipality: income and per-capita levies, adjustment credit, ふるさと納税, exemptions, every prefecture's surtax
Eligibility and leave
GET /v1/eligibility?month=2026-03&left_on=2026-03-30Is a premium due in a joining or leaving month?
GET /v1/leave-exemption?kind=childcare&start=&end=Which months a maternity or childcare leave exempts
GET /v1/age-milestones?birth_date=1986-04-01When 40, 65, 70 and 75 are reached, and what changes
Batch
POST /v1/payroll/batchUp to 500 payslips in one call, with run totals
Statutes
GET /v1/statute?ref=健康保険法第43条Full text of a provision this API cites
GET /v1/statute/indexEvery provision available, with its law
include=statute_textAdd to any endpoint to attach the text of whatever it cited
Meta
GET /v1/enumsEvery accepted enum value and error code
GET /v1/data-freshnessWhat each dataset covers and when it changes next

prefecture accepts an English name (Tokyo, case-insensitive), Japanese (東京 or 東京都), or a JIS code (13).

The one call that matters

Running payroll for one employee is a single request:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40&dependants=2"
gross                    350,000
social insurance          -55,750
                       ----------
after social insurance   294,250   <- the base withholding tax is charged on
withholding income tax    -4,480
                       ----------
net pay                  289,770

That middle line is the point. Income tax is charged on pay after social insurance, not on gross pay, and deriving it by hand is the mistake this endpoint exists to stop. The response also carries the grade that was resolved, every premium split into employee and employer shares, and which bracket produced the tax — so the arithmetic can be audited rather than trusted.

Resident tax (住民税) is assessed by the municipality and notified to the employer; no API can compute it. Pass resident_tax= and it will be subtracted from net pay.

Pass income_tax=false to get social insurance only.

Before you integrate
  • GET /v1/enums lists every accepted value — business_type, column, calendar — and every error code, so they can be read at build time instead of discovered from a 400.
  • Errors carry a stable code. invalid_request and missing_parameter mean fix the call; out_of_coverage means the input was valid but falls outside what is published, which needs a different branch. Do not match on the English prose — it will change.
  • GET /v1/data-freshness tells you how current each dataset is.

Data

DatasetCoverageSource
Social insurance rates47 prefectures, FY2026 (令和8年度), effective 2026-03協会けんぽ 保険料額表
Standard remuneration table50 health grades / 32 pension gradessame
Employment insurance3 business types, FY2026, effective 2026-04-01厚生労働省
Minimum wage47 prefectures × 24 years (FY2002–FY2025)厚生労働省 地域別最低賃金
Public holidays1,067 days, 1955–2027内閣府 国民の祝日について
Consumption tax4 rate periods since 1989, with reduced rate国税庁 No.6303
Corporate number check digitalgorithm, no dataset国税庁 チェックデジットの計算
Withholding tax (monthly)231 brackets + 9 high-income anchors, 令和8年分国税庁 源泉徴収税額表
Withholding tax (formula)4 statutory tables, 令和8年分以降電算機計算の特例

All figures are extracted programmatically from the official spreadsheets — not transcribed by hand. See scripts/ for the extractors.

Why not the statute

Income tax figures come from the National Tax Agency's published tables rather than from 所得税法 via the e-Gov law API, because the statutory version omits the 2.1% reconstruction surtax. At 105,000–107,000 yen the 乙 column is 3,700 yen in 別表第二 and 3,800 yen in practice; below 105,000 yen it is 3% rather than 3.063%. The statute is the wrong source for payroll.

Above 740,000 yen the table stops being a table: it becomes anchor points with a marginal rate. Those anchors are not collinear — rounding is baked into each — so the published anchor values are carried rather than recomputed. The 乙 column has only two anchors (740,000 and 1,710,000) where 甲 has nine, and measuring the 乙 excess from a 甲 anchor silently under-charges. That was a real bug here, caught by the cell-by-cell comparison.

引用箇所を本文に解決

法律の名称を挙げて、読者に条文を探してもらうだけでは、回答として不十分です。この API が引用する規定はすべて同梱されているため、健康保険法第43条を同じ往復で実際の条文に変換できます。

curl 'https://japan-payroll-api.tsumugi.workers.dev/v1/statute?ref=健康保険法第43条'
curl '…/v1/standard-remuneration/revision?…&include=statute_text'

実務では引用の表記方法がさまざまで、いずれも解決できます。健保法43条、厚年法81条の2、徴収法11条、第の省略、項単位の参照、全角数字に対応しています。e-Gov の略称は実務で使われるものとは異なるため(e-Gov では厚生年金法と呼びますが、一般には厚年法と表記します)、どちらも受け付けます。

テキストはリクエスト時ではなく、ビルド時に e-Gov 法令API から取得します。リクエストのたびに e-Gov に問い合わせる方式では、先方がダウンしたときにこの API も停止してしまうためです。

scripts/extract-statutes.pyには規定のリストが一元管理されており、テストスイートでは、コードが出力するすべての引用が解決できることを確認します。裏付けとなる規定を追加せずに引用を追加した場合、何も返さずに済ませるのではなく、ビルドが失敗します。

既知の不足
  • 年末調整は令和8年分のみ対象です。2026-08-31公開の国税庁の冊子に基づいています(給与所得控除の最低額740,000円、基礎控除は最大1,040,000円、新設の特定親族特別控除、23歳未満の生命保険料控除のルール)。医療費控除、寄附金控除、雑損控除は法律上、年末調整の対象外です。別途「従業員が確定申告した場合」の試算を得るには、tax_returnとして渡してください。

  • **2026年度の最低賃金はまだ含まれていません。**2026-09-02時点で、47都道府県のうち46都道府県が答申を出しており、沖縄県は未発表です。最も早い適用開始日は2026-10-01です。この API が提供するのは現在適用中の2025年度の金額で、最初の改定日以降の日付については、前年の金額を返すのではなくout_of_coverageを返します。47都道府県すべての金額が公表され次第、厚生労働省の一覧に基づいて更新します。

  • **二以上事業所勤務の従業員は按分されません。**保険料は各事業所の報酬に応じて按分されますが、他の勤務先の金額を入力する欄がないため、この API は1つの事業所で勤務しているものとして計算します。

  • **雇用保険の履歴は2026年度分のみです。**それ以前の年度は一次資料に照らして検証していないため、推測で補わず省略しています。

  • **住民税は対象外です。**前年の所得と自治体によって異なり、雇用主ではなく自治体が課税するため、/v1/payrollは渡された金額を控除するだけで、金額を算出することはありません。

  • **判定エンドポイントは届出が必要かどうかを判断するものであり、届出そのものではありません。**季節的な変動が「業務の性質上例年発生することが見込まれる」かどうか、手当が実費弁償かどうか、従業員が同意したかどうかなど、API では把握できない事実によって結論が変わる規則が複数あります。これらは入力値として指定し、レスポンスにそのまま返されますが、保険者算定により保険者が異なる結論を出す場合もあります。

  • **標準報酬の決定方法のすべてを網羅しているわけではありません。**資格取得時決定では決定が有効となる期間を返しますが、初回の報酬月額は計算しません(健保法42条1項には4つの方法があり、そのうち3つでは他の従業員に関する数値が必要です)。二以上事業所勤務(複数の勤務先からの報酬を合算し、保険料を各勤務先に按分する方法)も実装されていません。また、3か月の期間内に固定給が2回変わった場合に行われる基準の再設定にも対応していません。

  • 一次資料で確認できなかった実務上のポイントがいくつかあり、断定するのではなく、レスポンスのguidance.fixed_pay.unverifiedとして記載しています。家族手当が固定給に当たるかどうか、有給休暇を支払基礎日数にどう算入するか、年俸制をどう扱うかの3点です。二次資料ではいずれも一致していますが、各省庁は文書で明示していないようです。

検証

test/verify.mjs は、稼働中のサーバーに対して4,689件のアサーションを実行します。その中心となるのは、APIが計算した保険料を、250通りの組み合わせ(5都道府県 × 50等級)について、公式の協会けんぽの workbook に印刷された金額と比較することです。数式を再実装したものではなく、公表されている本人負担額を比較します。また、以下も確認します。

  • 等級の境界に隙間がないこと、および境界の1円が上位の等級に属すること
  • 厚生年金の等級1および32での上限・下限処理
  • 介護保険料が40歳で適用され、65歳で適用されなくなること
  • その他の保険料は等級を使う一方、雇用保険料は実際の給与に対して課されること
  • 適用日の前日を含めた、時点ごとの最低賃金
  • 4種類すべての入力形式で都道府県を特定できること
  • 47都道府県すべてが有効な給与計算レスポンスを返すこと
  • 独立して算出した基準値との営業日数の照合
  • 2026-09-22の国民の休日(他の2つの祝日に挟まれている場合にのみ休日となる日)
  • 大喪の礼、即位礼正殿の儀、結婚の儀という、個別に設けられた皇室関連の祝日
  • 国税庁PDFの計算例と法人番号のチェックデジットを照合し、同じ基礎番号ではそれ以外のチェックデジットがすべて拒否されること
  • 源泉徴収税額表の公表されている全セル(231区分 × 甲欄8列に乙欄を加えた2,079個の数値)を、国税庁独自の workbook と照合すること
  • 適格請求書発行事業者のチェックデジットに合格しても、法人であるとは判断できないこと。個人事業主も同じ規則を満たすため、番号から保有者を推定することはできません
  • 日本年金機構が公表している、1等級のみ変動する随時改定の全8ケース(健康保険4ケース、厚生年金4ケース)で、実際の等級と実装で使う拡張等級の両方が、表に記載された標準報酬に一致すること
  • 健康保険と厚生年金が独立して判定されること。厚生年金の上限を超える昇給では、健康保険の等級は6段階上がり、厚生年金の等級はまったく変わりません
  • 短時間就労者に対して15日間の定時決定の代替処理が実行され、他の対象者には実行されないこと。また、随時改定ではどの時点でも実行されないこと
  • 値の集合が定められているすべての項目が /v1/enums に含まれること。これにより、新しい列挙型が、インテグレーターが型を生成するエンドポイントに反映されずにリリースされることはありません
npx wrangler dev --port 8799
node test/verify.mjs

# or against production
BASE=https://japan-payroll-api.tsumugi.workers.dev node test/verify.mjs

開発/デプロイ

npm install
npx wrangler dev
npx wrangler deploy

データはバンドルに埋め込まれているため(gzip圧縮で約40 KB)、データベースもKVも不要で、コールドスタートもありません。

レスポンスには Cache-Control: public, max-age=3600, stale-while-revalidate=86400 が設定されています。保険料率は適用日が決まっており、訂正があれば同日中に呼び出し元へ反映されるよう、1日ではなく1時間にしています。stale-while-revalidate によって、バックグラウンドで更新している間もレスポンスを即座に返せます。workers.dev のレスポンスは、Cloudflare 独自のエッジではキャッシュされません。リクエストごとに Worker が実行されます。必要になれば、カスタムドメインを設定してエッジキャッシュを有効にできます。

デプロイ済み Worker に対して日本から測定した結果は、往復時間が中央値65 ms、最大83 msです。gzip圧縮により、50等級のテーブルは6,841バイトから1,041バイトになります。

メンテナンス

法定数値は決まった日に変更されます。改訂を反映できていない API は応答を続けますが、その数値はすでに正しくありません。それを防ぐため、2 つの仕組みを設けています。

API が自身のデータの古さを報告します。 GET /v1/data-freshness は各データセットの対象期間と次回の変更予定日を示し、主要なデータレスポンスには freshness マーカーが含まれます。監視に失敗した場合でも、呼び出し側は古い数値を見分けられます。

週次ジョブで情報源を監視します。

npm run watch          # fingerprints each source, alerts Discord on change
npm run watch:dry      # same, without notifying

見落としを防ぐため、独立した 2 つの項目を確認します。どちらか一方だけでは不十分です。情報源ファイルのハッシュと Last-Modified(通知なしの再公開を検出)と、カレンダー(省庁が改訂版を 新しい URL で公開し、古い URL をそのままにするケースを検出)です。

アラートには、このページを参照させるのではなく、そのデータセットに必要なコマンドが正確に記載されます。アラートを数か月後に読むのは、たいていこのリポジトリの構成を忘れてしまった人だからです。

必要になる前に、抽出処理をリハーサルします。 最低賃金の抽出ツールは --check を受け付けます。完全な抽出を実行し、何も書き込まずに、現在提供中のデータと比較します。

curl -L -A "Mozilla/5.0" -o mw.xlsx https://www.mhlw.go.jp/content/11200000/001571219.xlsx
python scripts/extract-minimum-wage.py --check

出力が一致すると表示されるはずです。会計年度が変わっていないのに一致しない場合は、抽出ツールと提供中のデータにずれが生じています。新しい数値が公開された当日に、スクリプトの出力を何でもそのまま公開してしまいたくなる前に、8 月の時点で把握しておく価値があります。

週次で実行するよう登録します。

powershell -ExecutionPolicy Bypass -File scripts
egister_watch_task.ps1
有料プランの経路を検証する

テストスイートでは、RapidAPI の有料プランで最大サイズのバッチが取得できるか確認できません。確認には RapidAPI が発行するプロキシシークレットが必要ですが、テスト内に置かれたシークレットはシークレットではないためです。テストで確認するのは、収益に関わるもう半分、つまりシークレットを持たない呼び出し側がヘッダーを設定して有料プランを装えないことです。

エンタイトルメントを変更した後は、ログで残り半分を確認します。

npx wrangler tail --format json

RapidAPI のプレイグラウンドから任意のエンドポイントを呼び出し、リクエスト行を確認します。サブスクリプション名が含まれているはずです。

{"channel":"rapidapi","path":"/","status":200,"plan":"BASIC"}

plan が設定されていれば、プロキシシークレットは一致しています。rapidapi リクエストの plan: null は一致していないことを意味します。その場合、料金を請求されているすべての有料顧客に、無料プランの上限が適用されています。この問題は外部からは分からないため、苦情を待つのではなく、意図的に確認する価値があります。

重要な日付
時期変更内容
3 月協会けんぽの都道府県別保険料率。3 月の給与月から適用
4 月雇用保険料率、税額表
8 月下旬~10 月最低賃金。都道府県ごとに発表され、10 月から適用
2 月内閣府が翌年の祝日を発表

いずれかのデータセットを更新した後は、src/data/freshness.json を更新し、npm run rapidapi:prepare を実行して、ライブ API の再検証と OpenAPI 仕様の再生成を行います。

公開パイプライン

各 API は recipes/<slug>/recipe.py にレシピとして定義されています。エンドポイントはここで一度だけ宣言し、そこから OpenAPI 仕様と RapidAPI の掲載文の両方を生成します。

npm run rapidapi:prepare

このコマンドは、すべてのレシピに対して次の処理を行います。

  1. レシピを検証します。
  2. ライブ API 上の宣言済みエンドポイントをすべて呼び出し、解析可能な JSON を伴う 200 が返ることを確認します。また、必須パラメーターのあるエンドポイントでは、それらを省略した場合に 400 が返ることを確認します。これにより recipe.py と src/index.ts のずれを検出できます。
  3. build/openapi/<slug>.openapi.json を書き出します。
  4. 掲載 URL、仕様ファイルのパス、貼り付ける正確な値を含む Discord 通知を送信します。

掲載の手続き自体は手動です。https://rapidapi.com/provider/<id>/new の API 追加フォームは reCAPTCHA v3 で保護されているため、最後の送信は人が行います。入力するのは 3 つの項目で、「Specify using: OpenAPI」を選択して、生成した仕様ファイルをアップロードします。API 1 件あたり約 2 分で、週に 1~2 件のペースならボトルネックにはなりません。

通知を実際に受け取るには、.env(.env.example を参照)で DISCORD_WEBHOOK_URL を設定してください。設定しない場合、メッセージはコンソールに表示されるだけです。

ブラウザーセッション

npm run rapidapi:login を実行すると、実際の Chrome ウィンドウが開き、ご自身でサインインできます。このスクリプトがパスワードを参照することはありません。セッションは rapidapi_profile/(Git で無視されます)に保持されます。セッションの有効期限が切れたら、再度実行してください。

運用上の安全性
  • state/pipeline.halt.json があると、人が削除するまで処理がすべて停止します。セッションが切れたときに set_halt() が呼び出され、再ログインに成功すると clear_halt() が呼び出されます。
  • pipeline/rapidapi/config.py の MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH により、人間らしいペースが保たれます。

ライセンスと帰属表示

基礎データは日本政府のオープンデータであり、商用利用と帰属表示付きの再配布を認める公共データ利用規約(第1.0版)に基づいています。すべてのレスポンスに、出典を示す attribution ブロックが含まれます。

このサービスは、日本政府のいかなる機関からも推奨されていません。 法定書類の提出に利用する前に、必ず公式情報をご確認ください。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。