{"_id":"@aaronzara/ph-holidays-mcp","name":"@aaronzara/ph-holidays-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aaronzara/ph-holidays-mcp","version":"1.0.0","private":false,"description":"MCP server providing Philippine national holiday data to AI agents. Data sourced from official presidential proclamations.","author":{"name":"Aaron Zara","email":"aaron.zara@godmode.ph"},"homepage":"https://godmode.ph","repository":{"type":"git","url":"git+https://github.com/GodModeArch/ph-holidays-mcp.git"},"license":"MIT","keywords":["mcp","philippines","holidays","philippine-holidays","cloudflare-workers"],"scripts":{"deploy":"wrangler deploy","dev":"wrangler dev","start":"wrangler dev","cf-typegen":"wrangler types","type-check":"tsc --noEmit","test":"tsx --test tests/*.test.ts","seed":"tsx scripts/seed.ts","validate":"tsx scripts/validate.ts","rollover":"tsx scripts/rollover.ts","patch-eid":"tsx scripts/patch-eid.ts","patch-holiday":"tsx scripts/patch-holiday.ts"},"dependencies":{"agents":"^0.5.0","zod":"^4.3.6"},"devDependencies":{"tsx":"^4.19.0","typescript":"5.9.3","wrangler":"^4.67.0"},"_id":"@aaronzara/ph-holidays-mcp@1.0.0","gitHead":"53df91842044d9af08997c18e357a30de584767e","bugs":{"url":"https://github.com/GodModeArch/ph-holidays-mcp/issues"},"_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-96JMydOrBTngmmtqo+PP2EfNTjEBjawhDbAZ4RTv7Xvvnq36b1vKatuqpG+ffWT2z9vtg/L4eDBCQ+1K8PBBdQ==","shasum":"7c496fc2531c81b75bbeb5624eab28cb44e9fff9","tarball":"https://registry.npmjs.org/@aaronzara/ph-holidays-mcp/-/ph-holidays-mcp-1.0.0.tgz","fileCount":3,"unpackedSize":11250,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGx2G+GGoUbUd+HceRK3aUj3TJ3rt0VRHJk7yEDjLZmxAiEAtxSzSxTYlCRtdd04Hb2yM63Hu3NP2DZkRyHe0rmtRaI="}]},"_npmUser":{"name":"aaronzara","email":"aaron.zara@godmode.ph"},"directories":{},"maintainers":[{"name":"aaronzara","email":"aaron.zara@godmode.ph"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ph-holidays-mcp_1.0.0_1773278728375_0.2643931643458819"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-12T01:25:28.309Z","1.0.0":"2026-03-12T01:25:28.528Z","modified":"2026-03-12T01:25:28.769Z"},"maintainers":[{"name":"aaronzara","email":"aaron.zara@godmode.ph"}],"description":"MCP server providing Philippine national holiday data to AI agents. Data sourced from official presidential proclamations.","homepage":"https://godmode.ph","keywords":["mcp","philippines","holidays","philippine-holidays","cloudflare-workers"],"repository":{"type":"git","url":"git+https://github.com/GodModeArch/ph-holidays-mcp.git"},"author":{"name":"Aaron Zara","email":"aaron.zara@godmode.ph"},"bugs":{"url":"https://github.com/GodModeArch/ph-holidays-mcp/issues"},"license":"MIT","readme":"# PH Holidays MCP Server\n\n![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020?logo=cloudflare&logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)\n![License: MIT](https://img.shields.io/badge/License-MIT-green)\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that provides Philippine national holiday data to LLMs. Built on Cloudflare Workers with KV storage.\n\nPublic, read-only, no authentication required. Data sourced from official presidential proclamations published in the [Official Gazette](https://www.officialgazette.gov.ph/nationwide-holidays/). Cached in Cloudflare KV for reliability and low-latency global access.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_holidays` | Get all holidays for a given year, optionally filtered by type |\n| `get_holiday_by_date` | Look up whether a specific date is a holiday |\n| `get_upcoming_holidays` | Get the next N holidays from a given date |\n| `is_working_day` | Check if a specific date is a working day per proclamation data |\n| `get_long_weekends` | Get all long weekend windows for a year |\n\n### Holiday Types\n\n| Type | Value | Pay Behavior |\n|------|-------|--------------|\n| Regular Holiday | `regular` | 200% if worked, 260% on rest day |\n| Special Non-Working | `special_non_working` | No work, no pay. 130% if worked |\n| Special Working | `special_working` | Ordinary working day. No premium |\n| Islamic Holiday | `islamic` | Same rules as regular. Separate proclamation. |\n\nPay rules are informational metadata only. This server does not compute pay.\n\n## Response Format\n\nAll data responses are wrapped in a standard envelope:\n\n```json\n{\n  \"_meta\": {\n    \"year\": 2026,\n    \"tier\": \"current\",\n    \"proclamation\": \"No. 1006\",\n    \"eid_fitr_status\": \"pending\",\n    \"eid_adha_status\": \"pending\",\n    \"last_updated\": \"2026-03-08\",\n    \"source\": \"Official Gazette of the Republic of the Philippines\"\n  },\n  \"data\": { ... }\n}\n```\n\nError responses (`isError: true`) are returned as plain text without wrapping.\n\n### Holiday Record\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `date` | `string` | ISO 8601 date: `YYYY-MM-DD` |\n| `name` | `string` | Official holiday name |\n| `type` | `string` | `regular`, `special_non_working`, `special_working`, `islamic` |\n| `day_of_week` | `string` | Full day name (e.g. \"Thursday\") |\n| `movable` | `boolean` | Whether the date is defined by a day-of-week rule |\n| `double_holiday` | `boolean` | Whether two holidays share this date |\n| `double_holiday_names` | `string[] \\| null` | Names of both holidays when double |\n| `long_weekend` | `object` | Long weekend window info (see below) |\n| `source` | `object` | Proclamation reference |\n| `notes` | `string \\| null` | Additional context |\n\nAll fields are always present. Fields without data are `null`, never omitted.\n\n### Islamic Holiday Record\n\nIslamic holidays include additional fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `eid_confirmed` | `boolean` | Whether the date has been confirmed by NCMF |\n| `estimated_date` | `string` | Astronomical estimate before confirmation |\n| `confirmed_date` | `string \\| null` | Actual proclaimed date after confirmation |\n| `proclamation_ref` | `string \\| null` | Separate proclamation number |\n\n### Long Weekend Window\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `is_part_of` | `boolean` | Whether this holiday is part of a long weekend |\n| `window_start` | `string \\| null` | First date of the window |\n| `window_end` | `string \\| null` | Last date of the window |\n| `days` | `number` | Total days in the window |\n| `leave_days_needed` | `number` | Bridge leave days required (0 = natural) |\n| `dates` | `string[]` | All dates in the window |\n\n### `is_working_day` Response\n\n```json\n{\n  \"_meta\": { ... },\n  \"data\": {\n    \"date\": \"2026-02-25\",\n    \"is_working_day\": true,\n    \"reason\": \"Special Working Day: EDSA People Power Revolution Anniversary\",\n    \"holiday_type\": \"special_working\"\n  }\n}\n```\n\n## Connect\n\nAdd to your MCP client configuration:\n```json\n{\n  \"mcpServers\": {\n    \"ph-holidays\": {\n      \"url\": \"https://ph-holidays.godmode.ph/mcp\"\n    }\n  }\n}\n```\n\n### Quick test\n```bash\ncurl -X POST https://ph-holidays.godmode.ph/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"get_upcoming_holidays\",\n      \"arguments\": { \"limit\": 3 }\n    }\n  }'\n```\n\n## Quirks\n\n1. **Islamic holidays have a 2-phase lifecycle.** Eid'l Fitr and Eid'l Adha appear in the main proclamation as \"to be proclaimed.\" Dates are confirmed later via separate proclamations after NCMF recommendation. The `eid_fitr_status` and `eid_adha_status` fields in `_meta` signal `\"pending\"` or `\"confirmed\"`. When pending, `estimated_date` is included but is not authoritative.\n\n2. **Special working days are counterintuitive.** The EDSA People Power Anniversary (Feb 25, 2026) appears in the proclamation but is a *working* day with no premium. `is_working_day` returns `true`. `holiday_type` returns `\"special_working\"`. Example:\n   ```\n   is_working_day(\"2026-02-25\") -> true, reason: \"Special Working Day: EDSA...\"\n   ```\n\n3. **`is_working_day` does not account for weekends.** Checks proclamation data only. Saturday/Sunday handling is the caller's responsibility. Rest day schedules vary by employer and are outside this server's scope.\n\n4. **Double holidays are rare but flagged.** When 2 holidays fall on the same date, `double_holiday: true` is set on the record. Pay stacking rules apply but computation is not handled by this server.\n\n5. **Pending Eid dates should not be used for hard scheduling.** When `eid_confirmed` is `false`, `estimated_date` is based on astronomical estimates. The actual proclaimed date may differ by 1 day.\n\n6. **Local holidays are out of scope.** City-level holidays (Quezon City Day, Manila Day, Cebu City Charter Day, etc.) are not included. Reserved for v2 integration via psgc-mcp cross-reference.\n\n7. **`next` year data may not be available.** The index only includes next year after the proclamation drops (typically October). `get_upcoming_holidays` crossing into the next year will stop at Dec 31 if next year is not yet loaded.\n\n## Data Sources\n\n| Source | Used For |\n|--------|----------|\n| [Official Gazette](https://www.officialgazette.gov.ph/nationwide-holidays/) | Authoritative proclamation text |\n| Presidential Proclamations (Malacanan) | Annual holiday list |\n| DOLE Labor Advisories | Pay rule reference (informational) |\n| NCMF | Eid date confirmations |\n\nCurrent year: 2026 (Proclamation No. 1006, signed September 3, 2025).\n\n## Year Coverage\n\n| Tier | Years | Notes |\n|------|-------|-------|\n| `current` | 2026 | Actively maintained. Eid patched when confirmed. |\n| `next` | -- | Loaded in October when proclamation drops. |\n\nAt any given time, KV holds at most 2 years. No historical data.\n\n## Data Pipeline\n\n```\nscripts/\n  data/\n    2026/  proclamation-source.json\n  seed.ts          -- full KV load for a given year\n  rollover.ts      -- promote next to current, drop old current\n  patch-eid.ts     -- targeted Eid date update\n  patch-holiday.ts -- ad hoc single holiday patch\n  validate.ts      -- schema validation before deploy\n```\n\n### Seed a year\n```bash\nnpm run seed -- --year=2026\n```\n\n### Validate before deploy\n```bash\nnpm run validate -- --year=2026\n```\n\n### Patch Eid after NCMF confirmation\n```bash\nnpm run patch-eid -- --year=2026 --holiday=fitr --date=2026-03-21 --proclamation=\"No. 1234\"\n```\n\n### Year rollover (January 1)\n```bash\nnpm run rollover\n```\n\n## Development\n\n```bash\nnpm install\nnpm run seed -- --year=2026\nnpm run dev\n```\n\nDev server starts at `http://localhost:8787`. Connect your MCP client to `http://localhost:8787/mcp`.\n\n### Setup\n\nBefore first deploy, create the KV namespace:\n```bash\nnpx wrangler kv namespace create HOLIDAYS_KV\n```\n\nUpdate `wrangler.jsonc` with the returned namespace ID.\n\n## Related Projects\n\nPart of a suite of Philippine public data MCP servers:\n\n- **[PSGC MCP](https://github.com/GodModeArch/psgc-mcp)** - Philippine Standard Geographic Code\n- **[LTS MCP](https://github.com/GodModeArch/lts-mcp)** - DHSUD License to Sell verification\n- **PH Holidays MCP** (this repo)\n- **BSP Bank Directory MCP** -> Coming soon\n\nAll servers are free, public, and read-only. Data pulled from official Philippine government sources.\n\n## Contributing and Issues\n\nFound a data error or a holiday that was missed? Open an issue. Philippine holidays can change via mid-year proclamations, and the issues list is the best place to flag them.\n\nEid dates are confirmed separately each year. When NCMF announces the confirmed date, open an issue or PR with the proclamation reference.\n\n## Built by\n\n**Aaron Zara** - Fractional CTO at [Godmode Digital](https://godmode.ph)\n\nFor enterprise SLAs, custom integrations, or other PH data sources:\n-> [godmode.ph](https://godmode.ph)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-2c91f07375cb4a2015f2ebf1a77276e9"}