mcp-chrono 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp-chrono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# mcp-chrono
+
+MCP server providing time, calendar, timezone, Chinese lunar calendar, almanac, and date utilities for AI agents.
+
+## Quick Start
+
+### Using npx (no installation needed)
+
+```bash
+npx mcp-chrono
+```
+
+### Global install
+
+```bash
+npm install -g mcp-chrono
+mcp-chrono
+```
+
+## Usage with MCP Clients
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "chrono": {
+      "command": "npx",
+      "args": ["-y", "mcp-chrono"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add chrono -- npx -y mcp-chrono
+```
+
+Or with a custom data directory:
+
+```bash
+claude mcp add chrono -- npx -y mcp-chrono --data-dir /path/to/data
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "chrono": {
+      "command": "npx",
+      "args": ["-y", "mcp-chrono"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chrono": {
+      "command": "npx",
+      "args": ["-y", "mcp-chrono"]
+    }
+  }
+}
+```
+
+### Generic MCP client (mcp.json)
+
+Any MCP-compatible client can use the standard `mcp.json` format:
+
+```json
+{
+  "mcpServers": {
+    "chrono": {
+      "command": "npx",
+      "args": ["-y", "mcp-chrono"],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+With custom data directory:
+
+```json
+{
+  "mcpServers": {
+    "chrono": {
+      "command": "npx",
+      "args": ["-y", "mcp-chrono", "--data-dir", "/path/to/data"],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+## Data Directory
+
+Holiday API responses are cached locally to avoid repeated network requests. Default location: `~/.mcp-chrono/`
+
+Override with `--data-dir`:
+
+```bash
+npx mcp-chrono --data-dir /tmp/mcp-chrono-data
+```
+
+## Tools
+
+### Time & Timezone
+
+| Tool | Description |
+|------|-------------|
+| `get_current_time` | Get current time in any IANA timezone with detailed components (weekday, week of year, day of year, UTC offset, etc.) |
+| `convert_timezone` | Convert a datetime between two IANA timezones |
+| `list_timezones` | Search IANA timezones with current offsets and Chinese city names |
+| `parse_timestamp` | Parse Unix timestamps (seconds/milliseconds) or ISO 8601 strings into date components |
+
+### Date Calculation
+
+| Tool | Description |
+|------|-------------|
+| `calculate_time` | Add/subtract time from a date. Three modes: **gregorian** (standard), **lunar** (Chinese calendar arithmetic), **anchor** (offset from a named festival like 春节 or Thanksgiving) |
+| `date_diff` | Difference between two dates in years, months, days, hours, minutes, and total counts |
+| `countdown` | Countdown from now to a target date with remaining days/hours/minutes/seconds |
+| `calculate_business_days` | Count or add business days, skipping weekends and optionally public holidays (supports CN makeup workdays) |
+
+### Calendar & Festivals
+
+| Tool | Description |
+|------|-------------|
+| `convert_calendar` | Convert between Gregorian and Chinese Lunar calendar. Returns Ganzhi (干支), zodiac, solar terms, festivals, constellation |
+| `get_festivals` | List festivals, solar terms, and public holidays within a date range. Filterable by type |
+| `get_month_info` | Month details: day count, first/last weekday, leap year, quarter, week count |
+
+### Chinese Almanac
+
+| Tool | Description |
+|------|-------------|
+| `get_almanac` | Chinese almanac (黄历) for a date: 宜 (suitable) / 忌 (avoid) activities, lucky directions (喜神/财神/福神), conflict zodiac, 彭祖百忌, 吉神宜趋, 凶煞宜忌, 天神, 纳音, and more |
+
+### Persistent Countdowns
+
+| Tool | Description |
+|------|-------------|
+| `manage_countdown` | CRUD for persistent countdown timers (set / get / list / delete), stored as JSON on disk |
+
+## Supported Regions
+
+| Region | Festivals | Public Holiday API |
+|--------|-----------|-------------------|
+| CN | 27 festivals (lunar + solar) | [timor.tech](https://timor.tech) (includes makeup workdays) |
+| US | 10 federal holidays | [date.nager.at](https://date.nager.at) |
+| HK | 17 public holidays (lunar, Easter, Ching Ming, fixed) | [date.nager.at](https://date.nager.at) |
+
+## License
+
+MIT

package/build/data/festivals-cn.d.ts

@@ -0,0 +1,17 @@
+import { Solar } from "lunar-typescript";
+export interface ChineseFestival {
+    name: string;
+    nameEn: string;
+    lunarMonth?: number;
+    lunarDay?: number;
+    solarMonth?: number;
+    solarDay?: number;
+    type: "lunar" | "solar";
+}
+export declare const CHINESE_FESTIVALS: ChineseFestival[];
+/**
+ * Resolve a Chinese festival name to a Solar date for a given year.
+ * For lunar festivals, `year` is the lunar year.
+ * Returns null if festival not found.
+ */
+export declare function resolveFestivalDate(name: string, year: number): Solar | null;

package/build/data/festivals-cn.js

@@ -0,0 +1,67 @@
+import { Lunar, Solar } from "lunar-typescript";
+export const CHINESE_FESTIVALS = [
+    { name: "\u6625\u8282", nameEn: "Spring Festival", lunarMonth: 1, lunarDay: 1, type: "lunar" },
+    { name: "\u5143\u5bb5\u8282", nameEn: "Lantern Festival", lunarMonth: 1, lunarDay: 15, type: "lunar" },
+    { name: "\u9f99\u62ac\u5934", nameEn: "Dragon Head Raising", lunarMonth: 2, lunarDay: 2, type: "lunar" },
+    { name: "\u4e0a\u5df3\u8282", nameEn: "Shangsi Festival", lunarMonth: 3, lunarDay: 3, type: "lunar" },
+    { name: "\u6e05\u660e\u8282", nameEn: "Qingming Festival", solarMonth: 4, solarDay: 5, type: "solar" },
+    { name: "\u7aef\u5348\u8282", nameEn: "Dragon Boat Festival", lunarMonth: 5, lunarDay: 5, type: "lunar" },
+    { name: "\u4e03\u5915\u8282", nameEn: "Qixi Festival", lunarMonth: 7, lunarDay: 7, type: "lunar" },
+    { name: "\u4e2d\u5143\u8282", nameEn: "Ghost Festival", lunarMonth: 7, lunarDay: 15, type: "lunar" },
+    { name: "\u4e2d\u79cb\u8282", nameEn: "Mid-Autumn Festival", lunarMonth: 8, lunarDay: 15, type: "lunar" },
+    { name: "\u91cd\u9633\u8282", nameEn: "Double Ninth Festival", lunarMonth: 9, lunarDay: 9, type: "lunar" },
+    { name: "\u5bd2\u8863\u8282", nameEn: "Hanyi Festival", lunarMonth: 10, lunarDay: 1, type: "lunar" },
+    { name: "\u4e0b\u5143\u8282", nameEn: "Xiayuan Festival", lunarMonth: 10, lunarDay: 15, type: "lunar" },
+    { name: "\u51ac\u81f3", nameEn: "Winter Solstice", solarMonth: 12, solarDay: 22, type: "solar" },
+    { name: "\u814a\u516b\u8282", nameEn: "Laba Festival", lunarMonth: 12, lunarDay: 8, type: "lunar" },
+    { name: "\u5c0f\u5e74", nameEn: "Little New Year", lunarMonth: 12, lunarDay: 23, type: "lunar" },
+    { name: "\u9664\u5915", nameEn: "New Year's Eve", lunarMonth: 12, lunarDay: 30, type: "lunar" },
+    // Solar holidays
+    { name: "\u5143\u65e6", nameEn: "New Year's Day", solarMonth: 1, solarDay: 1, type: "solar" },
+    { name: "\u60c5\u4eba\u8282", nameEn: "Valentine's Day", solarMonth: 2, solarDay: 14, type: "solar" },
+    { name: "\u5987\u5973\u8282", nameEn: "Women's Day", solarMonth: 3, solarDay: 8, type: "solar" },
+    { name: "\u690d\u6811\u8282", nameEn: "Arbor Day", solarMonth: 3, solarDay: 12, type: "solar" },
+    { name: "\u52b3\u52a8\u8282", nameEn: "Labour Day", solarMonth: 5, solarDay: 1, type: "solar" },
+    { name: "\u9752\u5e74\u8282", nameEn: "Youth Day", solarMonth: 5, solarDay: 4, type: "solar" },
+    { name: "\u513f\u7ae5\u8282", nameEn: "Children's Day", solarMonth: 6, solarDay: 1, type: "solar" },
+    { name: "\u5efa\u515a\u8282", nameEn: "CPC Founding Day", solarMonth: 7, solarDay: 1, type: "solar" },
+    { name: "\u5efa\u519b\u8282", nameEn: "Army Day", solarMonth: 8, solarDay: 1, type: "solar" },
+    { name: "\u6559\u5e08\u8282", nameEn: "Teachers' Day", solarMonth: 9, solarDay: 10, type: "solar" },
+    { name: "\u56fd\u5e86\u8282", nameEn: "National Day", solarMonth: 10, solarDay: 1, type: "solar" },
+];
+/**
+ * Resolve a Chinese festival name to a Solar date for a given year.
+ * For lunar festivals, `year` is the lunar year.
+ * Returns null if festival not found.
+ */
+export function resolveFestivalDate(name, year) {
+    const festival = CHINESE_FESTIVALS.find(f => f.name === name || f.nameEn.toLowerCase() === name.toLowerCase());
+    if (!festival)
+        return null;
+    if (festival.type === "solar" && festival.solarMonth && festival.solarDay) {
+        return Solar.fromYmd(year, festival.solarMonth, festival.solarDay);
+    }
+    if (festival.type === "lunar" && festival.lunarMonth && festival.lunarDay) {
+        try {
+            // Handle \u9664\u5915 specially - it's the last day of the lunar year
+            // lunar-typescript may not have day 30 for some months
+            const lunar = Lunar.fromYmd(year, festival.lunarMonth, festival.lunarDay);
+            return lunar.getSolar();
+        }
+        catch {
+            // If the lunar date doesn't exist (e.g., no 30th day), try 29th for \u9664\u5915
+            if (festival.name === "\u9664\u5915") {
+                try {
+                    const lunar = Lunar.fromYmd(year, 12, 29);
+                    return lunar.getSolar();
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=festivals-cn.js.map

package/build/data/festivals-cn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"festivals-cn.js","sourceRoot":"","sources":["../../src/data/festivals-cn.ts"],"names":[],"mappings":"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"}

package/build/data/festivals-hk.d.ts

@@ -0,0 +1,46 @@
+export interface HKFestival {
+    name: string;
+    nameZh: string;
+    rule: HKFixedRule | HKLunarRule | HKSpecialRule;
+}
+interface HKFixedRule {
+    type: "fixed";
+    month: number;
+    day: number;
+}
+interface HKLunarRule {
+    type: "lunar";
+    lunarMonth: number;
+    lunarDay: number;
+}
+interface HKSpecialRule {
+    type: "special";
+    resolve: (year: number) => {
+        month: number;
+        day: number;
+    } | null;
+}
+/**
+ * Hong Kong public holidays (法定公众假期).
+ * Includes both fixed solar dates and lunar-based holidays.
+ */
+export declare const HK_FESTIVALS: HKFestival[];
+/**
+ * Resolve an HK festival name to a { month, day } in the Gregorian calendar for a given year.
+ * Returns null if not found.
+ */
+export declare function resolveHKFestivalDate(name: string, year: number): {
+    month: number;
+    day: number;
+} | null;
+/**
+ * Get all HK public holidays for a given year with their resolved Gregorian dates.
+ */
+export declare function getAllHKFestivals(year: number): Array<{
+    name: string;
+    nameZh: string;
+    month: number;
+    day: number;
+    date: string;
+}>;
+export {};

package/build/data/festivals-hk.js

@@ -0,0 +1,186 @@
+import { Lunar, Solar } from "lunar-typescript";
+/**
+ * Hong Kong public holidays (法定公众假期).
+ * Includes both fixed solar dates and lunar-based holidays.
+ */
+export const HK_FESTIVALS = [
+    // Fixed solar holidays
+    { name: "New Year's Day", nameZh: "元旦", rule: { type: "fixed", month: 1, day: 1 } },
+    { name: "Labour Day", nameZh: "劳动节", rule: { type: "fixed", month: 5, day: 1 } },
+    { name: "HKSAR Establishment Day", nameZh: "香港特别行政区成立纪念日", rule: { type: "fixed", month: 7, day: 1 } },
+    { name: "National Day", nameZh: "国庆日", rule: { type: "fixed", month: 10, day: 1 } },
+    { name: "Christmas Day", nameZh: "圣诞节", rule: { type: "fixed", month: 12, day: 25 } },
+    { name: "Boxing Day", nameZh: "圣诞节翌日", rule: { type: "fixed", month: 12, day: 26 } },
+    // Lunar-based holidays
+    { name: "Lunar New Year's Day", nameZh: "农历年初一", rule: { type: "lunar", lunarMonth: 1, lunarDay: 1 } },
+    { name: "Lunar New Year's Day 2", nameZh: "农历年初二", rule: { type: "lunar", lunarMonth: 1, lunarDay: 2 } },
+    { name: "Lunar New Year's Day 3", nameZh: "农历年初三", rule: { type: "lunar", lunarMonth: 1, lunarDay: 3 } },
+    { name: "Buddha's Birthday", nameZh: "佛诞", rule: { type: "lunar", lunarMonth: 4, lunarDay: 8 } },
+    { name: "Tuen Ng Festival", nameZh: "端午节", rule: { type: "lunar", lunarMonth: 5, lunarDay: 5 } },
+    { name: "Mid-Autumn Festival", nameZh: "中秋节翌日", rule: { type: "lunar", lunarMonth: 8, lunarDay: 16 } },
+    { name: "Chung Yeung Festival", nameZh: "重阳节", rule: { type: "lunar", lunarMonth: 9, lunarDay: 9 } },
+    // Special calculation holidays
+    {
+        name: "Ching Ming Festival",
+        nameZh: "清明节",
+        rule: {
+            type: "special",
+            resolve: (year) => {
+                // Ching Ming is a solar term, typically April 4 or 5
+                // Use lunar-typescript to find the exact date
+                const solar4 = Solar.fromYmd(year, 4, 4);
+                const lunar4 = solar4.getLunar();
+                if (lunar4.getJieQi() === "清明") {
+                    return { month: 4, day: 4 };
+                }
+                const solar5 = Solar.fromYmd(year, 4, 5);
+                const lunar5 = solar5.getLunar();
+                if (lunar5.getJieQi() === "清明") {
+                    return { month: 4, day: 5 };
+                }
+                // Fallback: scan April 3-6
+                for (let d = 3; d <= 6; d++) {
+                    const s = Solar.fromYmd(year, 4, d);
+                    if (s.getLunar().getJieQi() === "清明") {
+                        return { month: 4, day: d };
+                    }
+                }
+                return { month: 4, day: 5 }; // default
+            },
+        },
+    },
+    {
+        name: "Easter Monday",
+        nameZh: "复活节星期一",
+        rule: {
+            type: "special",
+            resolve: (year) => {
+                // Computus algorithm for Easter Sunday
+                const a = year % 19;
+                const b = Math.floor(year / 100);
+                const c = year % 100;
+                const d = Math.floor(b / 4);
+                const e = b % 4;
+                const f = Math.floor((b + 8) / 25);
+                const g = Math.floor((b - f + 1) / 3);
+                const h = (19 * a + b - d - g + 15) % 30;
+                const i = Math.floor(c / 4);
+                const k = c % 4;
+                const l = (32 + 2 * e + 2 * i - h - k) % 7;
+                const m = Math.floor((a + 11 * h + 22 * l) / 451);
+                const month = Math.floor((h + l - 7 * m + 114) / 31);
+                const day = ((h + l - 7 * m + 114) % 31) + 1;
+                // Easter Monday = Easter Sunday + 1
+                const easterSunday = new Date(year, month - 1, day);
+                const easterMonday = new Date(easterSunday);
+                easterMonday.setDate(easterMonday.getDate() + 1);
+                return { month: easterMonday.getMonth() + 1, day: easterMonday.getDate() };
+            },
+        },
+    },
+    {
+        name: "Good Friday",
+        nameZh: "耶稣受难节",
+        rule: {
+            type: "special",
+            resolve: (year) => {
+                const a = year % 19;
+                const b = Math.floor(year / 100);
+                const c = year % 100;
+                const d = Math.floor(b / 4);
+                const e = b % 4;
+                const f = Math.floor((b + 8) / 25);
+                const g = Math.floor((b - f + 1) / 3);
+                const h = (19 * a + b - d - g + 15) % 30;
+                const i = Math.floor(c / 4);
+                const k = c % 4;
+                const l = (32 + 2 * e + 2 * i - h - k) % 7;
+                const m = Math.floor((a + 11 * h + 22 * l) / 451);
+                const month = Math.floor((h + l - 7 * m + 114) / 31);
+                const day = ((h + l - 7 * m + 114) % 31) + 1;
+                // Good Friday = Easter Sunday - 2
+                const easterSunday = new Date(year, month - 1, day);
+                const goodFriday = new Date(easterSunday);
+                goodFriday.setDate(goodFriday.getDate() - 2);
+                return { month: goodFriday.getMonth() + 1, day: goodFriday.getDate() };
+            },
+        },
+    },
+    {
+        name: "Day after Good Friday",
+        nameZh: "耶稣受难节翌日",
+        rule: {
+            type: "special",
+            resolve: (year) => {
+                const a = year % 19;
+                const b = Math.floor(year / 100);
+                const c = year % 100;
+                const d = Math.floor(b / 4);
+                const e = b % 4;
+                const f = Math.floor((b + 8) / 25);
+                const g = Math.floor((b - f + 1) / 3);
+                const h = (19 * a + b - d - g + 15) % 30;
+                const i = Math.floor(c / 4);
+                const k = c % 4;
+                const l = (32 + 2 * e + 2 * i - h - k) % 7;
+                const m = Math.floor((a + 11 * h + 22 * l) / 451);
+                const month = Math.floor((h + l - 7 * m + 114) / 31);
+                const day = ((h + l - 7 * m + 114) % 31) + 1;
+                const easterSunday = new Date(year, month - 1, day);
+                const sat = new Date(easterSunday);
+                sat.setDate(sat.getDate() - 1);
+                return { month: sat.getMonth() + 1, day: sat.getDate() };
+            },
+        },
+    },
+];
+/**
+ * Resolve an HK festival name to a { month, day } in the Gregorian calendar for a given year.
+ * Returns null if not found.
+ */
+export function resolveHKFestivalDate(name, year) {
+    const festival = HK_FESTIVALS.find(f => f.name.toLowerCase() === name.toLowerCase() || f.nameZh === name);
+    if (!festival)
+        return null;
+    const rule = festival.rule;
+    if (rule.type === "fixed") {
+        return { month: rule.month, day: rule.day };
+    }
+    if (rule.type === "lunar") {
+        try {
+            const lunar = Lunar.fromYmd(year, rule.lunarMonth, rule.lunarDay);
+            const solar = lunar.getSolar();
+            return { month: solar.getMonth(), day: solar.getDay() };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (rule.type === "special") {
+        return rule.resolve(year);
+    }
+    return null;
+}
+/**
+ * Get all HK public holidays for a given year with their resolved Gregorian dates.
+ */
+export function getAllHKFestivals(year) {
+    const results = [];
+    for (const festival of HK_FESTIVALS) {
+        const resolved = resolveHKFestivalDate(festival.name, year);
+        if (resolved) {
+            const m = String(resolved.month).padStart(2, "0");
+            const d = String(resolved.day).padStart(2, "0");
+            results.push({
+                name: festival.name,
+                nameZh: festival.nameZh,
+                month: resolved.month,
+                day: resolved.day,
+                date: `${year}-${m}-${d}`,
+            });
+        }
+    }
+    results.sort((a, b) => a.date.localeCompare(b.date));
+    return results;
+}
+//# sourceMappingURL=festivals-hk.js.map

package/build/data/festivals-hk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"festivals-hk.js","sourceRoot":"","sources":["../../src/data/festivals-hk.ts"],"names":[],"mappings":"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"}

package/build/data/festivals-us.d.ts

@@ -0,0 +1,25 @@
+export interface USFestival {
+    name: string;
+    rule: FixedDateRule | NthWeekdayRule;
+}
+interface FixedDateRule {
+    type: "fixed";
+    month: number;
+    day: number;
+}
+interface NthWeekdayRule {
+    type: "nth_weekday";
+    month: number;
+    weekday: number;
+    n: number;
+}
+export declare const US_FESTIVALS: USFestival[];
+/**
+ * Resolve a US festival name to a { month, day } for a given year.
+ * Returns null if not found.
+ */
+export declare function resolveUSFestivalDate(name: string, year: number): {
+    month: number;
+    day: number;
+} | null;
+export {};

package/build/data/festivals-us.js

@@ -0,0 +1,53 @@
+export const US_FESTIVALS = [
+    { name: "New Year's Day", rule: { type: "fixed", month: 1, day: 1 } },
+    { name: "Martin Luther King Jr. Day", rule: { type: "nth_weekday", month: 1, weekday: 1, n: 3 } },
+    { name: "Presidents' Day", rule: { type: "nth_weekday", month: 2, weekday: 1, n: 3 } },
+    { name: "Memorial Day", rule: { type: "nth_weekday", month: 5, weekday: 1, n: -1 } },
+    { name: "Independence Day", rule: { type: "fixed", month: 7, day: 4 } },
+    { name: "Labor Day", rule: { type: "nth_weekday", month: 9, weekday: 1, n: 1 } },
+    { name: "Columbus Day", rule: { type: "nth_weekday", month: 10, weekday: 1, n: 2 } },
+    { name: "Veterans Day", rule: { type: "fixed", month: 11, day: 11 } },
+    { name: "Thanksgiving", rule: { type: "nth_weekday", month: 11, weekday: 4, n: 4 } },
+    { name: "Christmas", rule: { type: "fixed", month: 12, day: 25 } },
+];
+/**
+ * Resolve a US festival name to a { month, day } for a given year.
+ * Returns null if not found.
+ */
+export function resolveUSFestivalDate(name, year) {
+    const festival = US_FESTIVALS.find(f => f.name.toLowerCase() === name.toLowerCase());
+    if (!festival)
+        return null;
+    const rule = festival.rule;
+    if (rule.type === "fixed") {
+        return { month: rule.month, day: rule.day };
+    }
+    // nth_weekday
+    if (rule.n === -1) {
+        // Last occurrence of weekday in month
+        // Start from last day of month and go backward
+        const lastDay = new Date(year, rule.month, 0).getDate();
+        for (let d = lastDay; d >= 1; d--) {
+            const dt = new Date(year, rule.month - 1, d);
+            if (dt.getDay() === rule.weekday) {
+                return { month: rule.month, day: d };
+            }
+        }
+    }
+    else {
+        // Nth occurrence
+        let count = 0;
+        const daysInMonth = new Date(year, rule.month, 0).getDate();
+        for (let d = 1; d <= daysInMonth; d++) {
+            const dt = new Date(year, rule.month - 1, d);
+            if (dt.getDay() === rule.weekday) {
+                count++;
+                if (count === rule.n) {
+                    return { month: rule.month, day: d };
+                }
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=festivals-us.js.map

package/build/data/festivals-us.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"festivals-us.js","sourceRoot":"","sources":["../../src/data/festivals-us.ts"],"names":[],"mappings":"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"}

package/build/data/holidays.d.ts

@@ -0,0 +1,8 @@
+export interface HolidayInfo {
+    date: string;
+    name: string;
+    isOffDay: boolean;
+    type: "public_holiday" | "makeup_workday" | "regular";
+}
+export declare function getHolidays(dataDir: string, country: string, year: number): Promise<Map<string, HolidayInfo>>;
+export declare function getHolidayInfoSync(dataDir: string, country: string, year: number, date: string): HolidayInfo | undefined;