mycal

マレーシアのカレンダー API

マレーシアで最も充実したカレンダー API — 祝日、学校カレンダー、試験日程、AI ツール向け MCP サーバーを提供します。

データソース：政府の公式官報（JPM BKPP）、JAKIM、KPM、MPM。第三者のウェブサイトからスクレイピングしたデータではありません。

リンク

• ウェブサイト＋デモ：https://mycal-web.pages.dev
• 開発者向けドキュメント：https://mycal-web.pages.dev/docs
• API ベース URL：https://mycal-api.huijun00100101.workers.dev/v1
• GitHub：https://github.com/Junhui20/malaysia-calendar-api

パッケージ

@catlabtech スコープで npm に公開されています。

パッケージ	用途	インストール
@catlabtech/mycal-core	共通の型、Zod スキーマ、カレンダー／営業日のロジック	npm install @catlabtech/mycal-core
@catlabtech/mycal-sdk	REST API 用の TypeScript クライアント SDK	npm install @catlabtech/mycal-sdk
@catlabtech/mycal-mcp-server	AI エージェント向けに 13 個のカレンダーツールを提供する MCP サーバー	npm install @catlabtech/mycal-mcp-server

機能

• 2026 年の祝日 50 日分を公式官報（Warta Kerajaan）から収録 — 連邦および州固有の祝日
• 13 州＋3 連邦直轄領に別名を設定（KL、JB、Penang など）
• 週末に対応 — Kedah／Kelantan／Terengganu は金曜～土曜（Kumpulan A）、その他の州は土曜～日曜（Kumpulan B）を週末とし、Johor の過去の変更履歴も記録
• 州ごとの週末設定に基づき**振替休日（cuti ganti）**を自動計算
• 営業日計算 — 州ごとに祝日を考慮
• 学校カレンダー — 学期、休暇、KPM の祝祭日休暇（Lampiran A/B/C）
• 試験日程 — SPM、STPM、MUET、PT3
• iCal 購読フィード — 州ごとの .ics フィード
• AI エージェント向け MCP サーバー — Claude、ChatGPT、その他のアシスタント向けに 13 個のツールを提供
• 型付きレスポンスを備えた TypeScript SDK（@catlabtech/mycal-sdk）
• OpenAPI 3.1 仕様＋インタラクティブなドキュメント
• 3 言語対応 — Bahasa Melayu、英語、中国語名（三语支持）

クイックスタート

# Clone and install
git clone https://github.com/Junhui20/malaysia-calendar-api.git
cd malaysia-calendar-api
pnpm install

# Build shared packages
pnpm --filter @catlabtech/mycal-core build
pnpm --filter @catlabtech/mycal-sdk build

# Run API locally (http://localhost:8787)
cd packages/api && npx wrangler dev

# Run web site locally (http://localhost:4321)
pnpm --filter @mycal/web dev

# Validate data
pnpm validate

# Run tests
pnpm test

API の例

ベース URL：https://mycal-api.huijun00100101.workers.dev/v1

祝日の一覧

# All holidays for Selangor in 2026
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=selangor"

# Islamic holidays only
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&type=islamic"

# March holidays for KL
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays?year=2026&state=KL&month=3"

日付を確認

# Is March 21 a holiday/weekend/working day?
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays/check?date=2026-03-21&state=KL"

レスポンス：

{
  "data": {
    "date": "2026-03-21",
    "dayOfWeek": "Saturday",
    "isHoliday": true,
    "isWeekend": true,
    "isWorkingDay": false,
    "isSchoolDay": false,
    "holidays": [
      {
        "id": "2026-hari-raya-aidilfitri-1",
        "name": { "ms": "Hari Raya Aidilfitri", "en": "Eid al-Fitr", "zh": "开斋节" },
        "type": "islamic",
        "status": "confirmed"
      }
    ]
  }
}

営業日

# Count working days in March for Selangor
curl "https://mycal-api.huijun00100101.workers.dev/v1/business-days?start=2026-03-01&end=2026-03-31&state=selangor"

# Add 10 business days to a date
curl "https://mycal-api.huijun00100101.workers.dev/v1/business-days/add?date=2026-03-01&days=10&state=selangor"

学校カレンダー

# Is this a school day?
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/is-school-day?date=2026-03-21&state=selangor"

# School holidays for Kumpulan B
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/holidays?year=2026&group=B"

# Exam schedule
curl "https://mycal-api.huijun00100101.workers.dev/v1/school/exams?year=2026&type=spm"

次の祝日

# Next holiday for Penang
curl "https://mycal-api.huijun00100101.workers.dev/v1/holidays/next?state=penang"

州の特定

# Resolve alias
curl "https://mycal-api.huijun00100101.workers.dev/v1/states/resolve?q=kl"
# -> { "data": { "canonical": "kuala-lumpur", "group": "B" } }

API リファレンス全文

エンドポイント	説明
GET /v1/holidays	祝日一覧（年、州、種類、ステータス、月で絞り込み）
GET /v1/holidays/check	この日付は祝日／週末／営業日／登校日ですか？
GET /v1/holidays/today	今日の祝日ステータス
GET /v1/holidays/next	次に来る祝日
GET /v1/holidays/between	指定した日付範囲の祝日
GET /v1/holidays/leave-optimizer	最長の連休を得るために取得する年次休暇の日数を提案
GET /v1/business-days	日付間の営業日数を数える
GET /v1/business-days/add	日付に N 営業日を加算
GET /v1/states	週末設定を含む、全 13 州と 3 連邦直轄地
GET /v1/states/resolve	エイリアス（KL、penang、jb）を正規コードに解決
GET /v1/school/terms	学期の日付と日数
GET /v1/school/holidays	学校休暇と KPM の cuti perayaan
GET /v1/school/exams	SPM、STPM、MUET、PT3 の日程
GET /v1/school/is-school-day	登校日ですか？
GET /v1/feed/ical/:state	iCal サブスクリプションフィード
GET /v1/feed/csv/:state	祝日の CSV／スプレッドシート形式のエクスポート
GET /v1/data/*	キャッシュ可能なオープンデータの生スナップショット — manifest、states、holidays/:year、all（API キー不要）
GET /v1/prayer-times/:zone	ゾーンの JAKIM 礼拝時刻（MYT 形式）。GET /v1/prayer-times/zones でゾーン一覧を取得
POST /v1/keys	API キーを発行（現時点では管理者限定。GET /v1/keys/whoami で呼び出し元のティアを確認）

リクエスト／レスポンスのスキーマについては、完全な OpenAPI 3.1 仕様を参照してください。

SDK の使用方法

import { MyCalClient } from "@catlabtech/mycal-sdk";

const cal = new MyCalClient();

// Check if a date is a working day
const result = await cal.check("2026-03-21", "selangor");
console.log(result.isWorkingDay); // false

// List holidays
const holidays = await cal.holidays({ year: 2026, state: "KL" });

// Business days
const workDays = await cal.businessDays("2026-03-01", "2026-03-31", "selangor");
console.log(workDays.businessDays); // 22

// School calendar
const terms = await cal.school.terms({ year: 2026, group: "B" });
const exams = await cal.school.exams({ year: 2026, type: "spm" });
const isSchool = await cal.school.isSchoolDay("2026-03-21", "selangor");

MCP サーバー

Malaysia Calendar API を Claude、ChatGPT、または MCP 互換の AI アシスタントに接続します。

Claude Desktop／Claude Code でのセットアップ

MCP の設定に追加します。

{
  "mcpServers": {
    "malaysia-calendar": {
      "command": "npx",
      "args": ["@catlabtech/mycal-mcp-server"]
    }
  }
}

利用可能なツール（13）

ツール	説明
get_malaysia_holidays	祝日を取得（年、州、種類で絞り込み）
check_malaysia_holiday	日付が祝日または営業日かどうかを確認
next_malaysia_holiday	次に来る祝日を検索
malaysia_business_days	2 つの日付間の営業日数を数える
malaysia_long_weekends	連休（3 日以上）を検索
malaysia_leave_optimizer	連続休暇日数を最大化できる、最も効率的な休暇取得日を検索
list_malaysia_states	週末設定とともに全州を一覧表示
resolve_malaysia_state	エイリアス（KL、JB）を正規コードに解決
malaysia_holiday_changes	最近のデータ変更
malaysia_school_terms	学期の日付と日数
malaysia_school_holidays	学校休暇（cuti penggal、cuti perayaan）
malaysia_exams	SPM、STPM、MUET、PT3 の試験日程
malaysia_is_school_day	日付が登校日かどうかを確認

州コード

コード	エイリアス	グループ	週末
johor	jhr, jb	B	土～日（2014～2024 年は金～土）
kedah	kd, kdh	A	金～土
kelantan	kel, kb	A	金～土
terengganu	trg, kt	A	金～土
perak	prk, ipoh	B	土～日
pulau-pinang	penang, pg	B	土～日
selangor	sel, sgr	B	土～日
negeri-sembilan	ns, n9	B	土～日
melaka	mlk, malacca	B	土～日
pahang	phg, kuantan	B	土～日
perlis	pls, kangar	B	土～日
sabah	sbh, kk	B	土～日
sarawak	swk, kuching	B	土～日
kuala-lumpur	kl	B	土～日
wp-putrajaya	putrajaya, pjy	B	土～日
wp-labuan	labuan, lbn	B	土～日

州のエイリアスでは大文字と小文字が区別されません。GET /v1/states/resolve?q=kl を使うと、任意のエイリアスを正規コードに解決できます。

プロジェクト構成

malaysia-calendar-api/
├── data/                        # JSON data files (source of truth / 数据源)
│   ├── holidays/
│   │   ├── 2024.json            # Holiday data per year
│   │   ├── 2025.json
│   │   └── 2026.json
│   ├── school/
│   │   ├── terms-2026.json      # School terms (Kumpulan A + B)
│   │   ├── holidays-2026.json   # School holidays + KPM cuti perayaan
│   │   └── exams-2026.json      # SPM, STPM, MUET, PT3 schedules
│   ├── states.json              # 13 states + 3 FT, aliases, weekend history
│   └── known-fixed-holidays.json
├── packages/
│   ├── core/                    # Shared business logic (types, schemas, utils)
│   │   └── src/
│   │       ├── types.ts         # Holiday, State, SchoolTerm, Exam interfaces
│   │       ├── schemas.ts       # Zod validation schemas
│   │       ├── filter.ts        # Query filtering logic
│   │       ├── replacement.ts   # Cuti ganti calculation
│   │       ├── state-resolver.ts
│   │       ├── business-days.ts
│   │       └── school.ts        # School term/holiday/exam logic
│   ├── api/                     # Hono API on Cloudflare Workers
│   ├── mcp-server/              # MCP Server (13 tools)
│   ├── sdk/                     # TypeScript client SDK (@catlabtech/mycal-sdk)
│   └── web/                     # Astro + Starlight — marketing site, demos, docs
├── scripts/
│   ├── validate-data.ts         # 5-layer data validation pipeline
│   └── sync-to-kv.ts           # JSON -> Cloudflare KV denormalization
├── openapi.yaml                 # OpenAPI 3.1 spec (spec-first)
├── pnpm-workspace.yaml
└── turbo.json

データソース

すべてのデータは、マレーシア政府の公式刊行物から取得しています。

ソース	データ	URL
JPM BKPP	官報／Warta Kerajaan（祝日）	kabinet.gov.my
JAKIM	タクウィーム・ヒジュリ・ミラディ（イスラム暦）	e-solat.gov.my
KPM	学年度カレンダー／学校カレンダー（Lampiran A/B/C）	moe.gov.my
MPM	STPM および MUET の試験日程	mpm.edu.my
州ポータル	各州の祝日（13 州）	*.gov.my

祝日データには、追跡可能性を確保するため、官報の参照情報（例：P.U.(B) 305/2025）が含まれています。

デプロイ

2 つの部分はそれぞれ独立してデプロイします。

API → Cloudflare Workers

pnpm --filter @catlabtech/mycal-core build
cd packages/api && npx wrangler deploy

ウェブサイト → Cloudflare Pages

pnpm --filter @catlabtech/mycal-core build
pnpm --filter @catlabtech/mycal-sdk build
pnpm --filter @mycal/web build

# Direct upload via wrangler (requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)
cd packages/web
npx wrangler pages deploy dist --project-name=mycal-web

初回の Pages 設定：

1. Cloudflare ダッシュボードで mycal-web という名前の Pages プロジェクトを作成します。
2. GitHub リポジトリを接続して自動ビルドするか、GitHub Actions ワークフロー（.github/workflows/deploy.yml）から wrangler pages deploy を実行します。
3. 必要な GitHub シークレット：CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID。

CI/CD

GitHub Actions は以下を処理します。

1. PR ゲート — すべての PR での Zod スキーマ検証とソース間チェック
2. デプロイ — main へのマージ時に、API を Workers に、ウェブサイトを Pages に並行してビルドおよびデプロイ
3. 毎日のスクレイピング — 更新情報を確認するための政府ポータル監視
4. Rukyah モニター — イスラム暦の日付確認の追跡

貢献

以下の方法については、CONTRIBUTING.md を参照してください。

• 祝日または cuti peristiwa の不足を報告する
• データの誤りを修正する
• 新機能を追加する

ライセンス

MIT