# jp-dates MCP Server 🗾📅

[![CI](https://github.com/h-kazuki-pixel/jp-dates-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/h-kazuki-pixel/jp-dates-mcp-server/actions/workflows/ci.yml)

日本の祝日・和暦・日付情報を Claude に提供する MCP (Model Context Protocol) サーバーです。

An MCP server that gives Claude accurate knowledge of Japanese national holidays, wareki (era) conversion, and date info. Works fully offline — no API keys required.

## ✨ できること / Features

Claude にこんな質問が正確に即答できるようになります:

- 「来月の祝日はいつ?」
- 「次の連休まであと何日?」
- 「令和6年って西暦何年?」「1989年1月7日は昭和?平成?」
- 「2026年のシルバーウィークはいつ?」

| ツール | 説明 |
|---|---|
| `jp_list_holidays` | 指定年(月)の祝日一覧。振替休日・国民の休日も含む |
| `jp_date_info` | 日付の曜日・祝日判定・和暦表記 |
| `jp_convert_era` | 和暦⇔西暦の相互変換(明治〜令和) |
| `jp_next_holiday` | 次の祝日と残り日数 |

- ✅ **APIキー不要・完全オフライン**(祝日はアルゴリズムで算出)
- ✅ 振替休日・国民の休日・2020/2021年の五輪特例に対応
- ✅ 対応範囲: 祝日 2020〜2099年 / 和暦 1868年(明治)以降

## 🚀 セットアップ / Setup

### 1. インストール

**Node.js 18 以上**が必要です。

```bash
git clone https://github.com/h-kazuki-pixel/jp-dates-mcp-server.git
cd jp-dates-mcp-server
npm install
npm run build
```

`npm install` の時点で `prepare` スクリプトによりビルドが実行されます。`npm run build` を省いても `dist/` は生成されますが、明示的に実行しても問題ありません。

### 2. Claude Desktop に登録

`claude_desktop_config.json` に以下を追加します。

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

```json
{
  "mcpServers": {
    "jp-dates": {
      "command": "node",
      "args": ["/absolute/path/to/jp-dates-mcp-server/dist/index.js"]
    }
  }
}
```

Claude Desktop を再起動すると、🔌アイコンからツールが確認できます。

### 3. 使ってみる

Claude にそのまま話しかけるだけです:

> 「今年の残りの祝日を教えて」
> 「昭和58年は西暦何年?」

## 🧪 テスト / Tests

```bash
npm test
```

テスト30件。追加の依存はありません(Node標準の `node --test` のみ)。

**祝日の正しさは、内閣府の公表データそのものと突き合わせて検証しています。**

- 照合元: 内閣府「国民の祝日について」の公表CSV(`test/fixtures/syukujitsu.csv` として同梱。文字コードのみ Shift_JIS → UTF-8 に変換し、内容は無改変)
  https://www8.cao.go.jp/chosei/shukujitsu/syukujitsu.csv
- CSVと本サーバーの対応範囲が重なる **2020年〜CSV最終年を全件・日付と名称の両方**で照合します
- CSVは振替休日と国民の休日をどちらも「休日」と記載するため、その1点のみ名称を読み替えて比較します
- 加えて境界ケースを個別に検証: 五輪特例(2020・2021の海の日/スポーツの日/山の日の移動)、日曜が祝日の場合の振替、翌日も祝日の場合の繰り下がり、国民の休日(敬老の日と秋分の日に挟まれた平日)、春分・秋分の変動、改元境界の和暦変換(1989-01-07/08、2019-04-30/05-01)

CSVが更新されたら差し替えるだけで、対象年が自動的に広がります。

MCP Inspector で対話的に試すこともできます:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## 📝 祝日計算について / Notes

- 祝日は法律(国民の祝日に関する法律)のルールに基づきアルゴリズムで算出しています
- 春分・秋分は天文計算の近似式を使用(1980〜2099年で有効)
- **対応範囲は 2020〜2099年**です。範囲外の年を指定した場合はエラーを返します(誤った値を返しません)
- 将来の法改正には追従が必要です。誤りを見つけたら Issue で教えてください!

## 🤝 コントリビュート / Contributing

Issue・Pull Request 歓迎です! 機能要望(六曜、旧暦、営業日計算など)もお待ちしています。

## 📄 License

MIT