Malaysia Calendar API

马来西亚日历API

马来西亚最完整的日历API-公共假期，学校日历，考试时间表，以及用于人工智能工具的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

特性

• 49公众假期 2026年官方公报（Warta Kerajaan）-联邦+州特定
• 16个州+3个联邦直辖区 别名（KL、JB、Penang等）
• 周末意识 --吉打州/吉兰丹州/登嘉楼州使用星期五至星期六（Kumpulan A），所有其他州使用星期六至星期日（KumpulanB），并跟踪柔佛州的历史转变
• 可爱的甘蒂 （替换假期）根据州周末配置自动计算
• 工作日计算器 --每个州，有假期意识
• 校历 — 条款， 假期， 节假日 （附件A/B/C）
• 考试时间表 --SPM、STPM、MUET、PT3
• iCal订阅源 --每个州 .ics 动态
• MCP服务器 用于AI代理的12个工具，适用于Claude、ChatGPT和其他助手
• TypeScript SDK (@catlabtech/mycal-sdk)带打字回复
• OpenAPI 3.1规范 +交互式文档
• 三种语言 --Bahasa Melayu，英文，中文名字（三语支持）

快速开始

# Clone and install
git clone https://github.com/Junhui20/malaysia-calendar-api.git
cd MalaysiaCalanderApi
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完整参考

查看完整 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服务器

将马来西亚日历API连接到Claude、ChatGPT或任何兼容MCP的AI助手。

使用克劳德桌面/Claude代码进行设置

添加到MCP配置中：

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

可用工具（12）

州代码

州别名不区分大小写。使用 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              # 16 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 (12 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
├── parsers/                     # Year-specific PDF layout adapters
├── openapi.yaml                 # OpenAPI 3.1 spec (spec-first)
├── pnpm-workspace.yaml
└── turbo.json

数据源

所有数据均来自马来西亚政府官方出版物：

假日数据包括公报参考（例如。， P.U.(B) 305/2025)为了可追溯性。

部署

两个部分独立部署：

API → Cloudflare 边缘计算平台

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

网站→ Cloudflare页面

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

首次页面设置：

1. 创建一个名为的Pages项目 mycal-web 在Cloudflare仪表板中。
2. 要么连接GitHub仓库进行自动构建，要么依赖GitHub Actions工作流(.github/workflows/deploy.yml)通过推送 wrangler pages deploy.
3. 所需的GitHub机密： CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.

CI/CD

GitHub操作处理：

1. PR门 --Zod模式验证+对每个PR进行跨源检查
2. 部署 --合并到 main：并行构建和部署API到Workers+Web到Pages
3. 每日刮刮 --政府门户网站监控更新
4. Rukyah监视器 --伊斯兰日期确认跟踪

贡献

看 贡献.md 如何：

• 报告缺失的假期或cuti peristiwa
• 修复数据错误
• 添加新功能

许可证

麻省理工学院