The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Icyn Date listing page.
Date context for AI agents and developers: lunar calendar, solar terms, holidays and "what does this day mean" — offline, verified, MIT.给 AI Agent 和开发者的日期语义层:农历、节气、节假日、"这一天意味着什么"——离线、可验证、MIT。
Status: week 1. Lunar calendar, the 24 solar terms and the holiday layer (12 regions) are in;
lunar & solar terms verified for 1900–2100, CN holidays for 2024–2026.
状态:第一周。农历、二十四节气、节假日层(12 个地区)均已落地;农历与节气 1900–2100 全量验证,
中国大陆节假日 2024–2026 逐天对拍。
Install / 安装
Terminal
npm i @icyn/date # library: lunar + solar terms + CN holidays (~90 KB)
import"@icyn/date/regions/all"; # opt in to the other 11 regions (+ subdivisions), or "@icyn/date/regions/JP"
npx -y @icyn/date-mcp # MCP server for Claude Desktop / Cursor / any MCP client
Dates can be given as "2026-02-17", [2026, 2, 17], { year, month, day } or a Date (UTC fields). Every holiday
answer carries source (official / baseline / predicted), confidence (certain / likely / uncertain) and data
version metadata; a year we know nothing about comes back as { available: false, reason }, never a guess.
Solar ⇄ lunar for every day 1900-01-31 .. 2100-12-31 (MAX_DATE; that last date falls inside lunar
2100 腊月, so monthLength for that month is null — the table ends mid-month and the real length is unknown)
Year / day 干支, zodiac, Chinese month & day names, leap month handling (incl. the 2033 閏冬月 case)
24 solar terms as exact instants (second precision), current/next lookup, "is there a term on this day" at any UTC offset
Workday / holiday queries for 12 regions, every answer tagged official / baseline / predicted — never silently guessed
Zero dependencies, no runtime astronomy; ~480 KB of table data, of which only the lunar/solar-term tables and CN are in the default entry point — the other 11 regions and their 70+ subdivisions load only if you import them
Error model / 失败行为
Functions that return an info object (dayInfo, dateContext, holidays) never throw for missing data: they return { available: false, reason } or an empty list.
Functions that return a scalar (isWorkday, addWorkdays, nextWorkday, workdayCount) throw RangeError when the region-year is not covered.
Search functions (nextLongWeekend, nextLunarDate) return null when nothing is found in range, and throw when data runs out.
Bad input (unknown region, malformed date, 2 月 30 日) always throws TypeError / RangeError.
Region codes are case-insensitive ("us-ca" = "US-CA"); a code with no data at all still throws.
Prediction is forward-only. A year we have not entered is extrapolated only if it is after the
last entered year (coverage(region).predictedFrom). Past uncovered years return
{ available: false } rather than a guess — extrapolating the current 《放假办法》 backwards would
invent history (清明/端午/中秋 became statutory only in 2008, 春节 runs 除夕..初三 only from 2025).
How it is verified / 验证方式
tools/gen_fixtures.py and tools/gen_solar_terms.py generate fixtures/lunar-1900-2100.json (73,384 rows) from two independent reference
implementations (sxtwl, lunar_python). The test suite converts every row in both directions.
Anything the two references disagree on is written to fixtures/lunar-disagreements.json and adjudicated by hand
(see NOTES.md). A release is blocked unless 100% of rows pass.
Terminal
npm install
npm test # Node only
# the full release gate: build + tsc + tests + the CN cross-check
python3 -m pip install -r tools/requirements.txt # one pure-Python package
npm run check
The last step of npm run check verifies CN.json day-by-day against chinesecalendar. If that
package is missing it fails loudly rather than skipping — an unverified table must not look like a
passing gate.
Roadmap / 路线图
Lunar core + 1900–2100 fixtures
24 solar terms with exact instants (two references agree within 55 s; spot-check against 紫金山天文台 published values before release)
Holidays CN 2024–2026 official (incl. 调休), cross-checked day-by-day with chinesecalendar; later years → statutory days predicted from lunar/solar-term rules (forward-only; earlier years are never guessed)
Holidays HK/MO/TW/JP/KR/VN/SG/US/GB/DE/FR 2024–2028 as baseline (python-holidays rules), CNY dates cross-checked against our lunar table
Region time zones (DST-aware via Intl) so JP/KR/EU decide solar-term days in their own zone; region hierarchy (US-CA, DE-BY, GB-SCT, 70+ subdivisions as diffs); holiday kind (public/federal/bank/substitute); previousWorkday / addWorkdays / workdayCount / holidaysBetween / isHolidayEve / nextLongWeekend; month & hour 干支, nextLunarDate (lunar birthdays); describe() one-sentence zh/en output for MCP
dateContext() one-call API, canonical date input, confidence levels, BCP-47 names with guaranteed en + zh-Hans, canonical festival ids across regions, data version metadata, graceful available: false
Upgrade baseline regions to official year by year against gazettes (TW 補班, HK gazette, KR substitute days first)
"On this day" from Wikipedia (CC BY-SA, attributed per entry)
@icyn/date npm package (esbuild ESM, per-region entry points, d.ts) · @icyn/date-mcp MCP server (11 tools, stdio, smoke-tested end to end)
icyndate pip package (same test vectors)
Hosted API
Repository layout / 目录
Code
docs/ product & technical plan(产品与技术方案), worklog
fixtures/ reference test vectors (generated, committed)
tools/ fixture generators (Python, not shipped)
packages/core/ @icyn/date — the library
packages/mcp/ @icyn/date-mcp — MCP server
License
MIT for code and the derived lunar / solar-term tables. The baseline holiday tables for the eleven
non-CN regions are derived from python-holidays (MIT) — its
licence is reproduced in THIRD-PARTY-LICENSES, and each generated file records the exact version in
baseline_note. Other third-party data (Wikipedia, government holiday notices) keeps its own licence
and is attributed per entry.