Icyn Date

Name: Icyn Date
Author: icyn12-tinker

@icyn12-tinkerMCP server · External

Date context for agents: Chinese lunar calendar, solar terms, holidays for 12 regions. Offline.

Calendarv0.1.5MITTypeScript

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

What it does

Reads
Writes
High impact

At most: only reads or looks up information.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

npm@icyn/date-mcpv0.1.5

Run

npx -y @icyn/date-mcp

MCP client config

{
  "mcpServers": {
    "icyn-date": {
      "command": "npx",
      "args": [
        "-y",
        "@icyn/date-mcp"
      ]
    }
  }
}

README7 min readView on GitHub

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 / 安装

bash

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

What works today / 现在能用的

One call:

import { dateContext } from "@icyn/date";

dateContext("2026-02-17", { region: "CN" });
// {
//   date: "2026-02-17", region: "CN",
//   civil:    { weekday: 2, isoWeek: 8, isoWeekYear: 2026, dayOfYear: 48, leapYear: false },
//   workday:  { available: true, kind: "public_holiday", isWorkday: false, confidence: "certain", source: "official",
//               holiday: { id: "spring-festival", festival: "lunar-new-year", name: { "zh-Hans": "春节", en: "Chinese New Year" }, dayIndex: 3, span: 9 },
//               meta: { region: "CN", data_version: "2026.09.18", verified_until: 2026, … } },
//   lunar:    { year: 2026, month: 1, day: 1, yearGanZhi: "丙午", zodiac: "马", monthName: "正月", dayName: "初一", … },
//   solarTerm:{ onThisDay: null, current: { name: { zh: "立春", en: "Beginning of Spring" }, at: "2026-02-03T20:01:51.000Z" }, next: { zh: "雨水", … } }
// }

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.

Pieces:

import { solarToLunar, lunarToSolar } from "@icyn/date";

solarToLunar("2026-02-17");
// { year: 2026, month: 1, day: 1, leap: false, yearGanZhi: "丙午", dayGanZhi: "…",
//   zodiac: "马", monthName: "正月", dayName: "初一", isLeapYear: false, monthLength: 30 }

lunarToSolar({ year: 2033, month: 11, day: 1, leap: true }); // [2033, 12, 22]

import { solarTerms, solarTermAt, solarTermOnDay } from "@icyn/date";
solarTermOnDay("2026-02-04");          // { name: { zh: "立春", en: "Beginning of Spring" }, at: 2026-02-03T20:01:51Z, … }
solarTermAt(new Date());               // { current, next } with exact instants
solarTerms(2027);                      // all 24 of the year

import { dayInfo, nextWorkday, workdaysBetween, holidays } from "@icyn/date";
dayInfo("2026-02-14", "CN");           // { kind: "adjusted_workday", isWorkday: true, source: "official", confidence: "certain", … }
dayInfo("2027-02-13", "CN");           // { kind: "weekend", source: "predicted", confidence: "uncertain", note: "Within the usual 调休 window…" }
regionsObserving("lunar-new-year", 2026); // [{ region: "HK", days: [...] }, { region: "KR", … }, …]
dayInfo("2026-01-06", "DE-BY");        // Heilige Drei Könige — subdivision holiday, resolvedRegion "DE-BY"
nextLongWeekend("CN", "2026-09-18", 7); // { start: "2026-10-01", end: "2026-10-07", days: 7 }
nextLunarDate(8, 15, "2026-09-18");    // next 中秋: { date: "2026-09-25", lunarYear: 2026, adjusted: false }
describe("2026-02-17", { region: "CN" });
// "2026-02-17 星期二，农历丙午马年正月初一，CN 放假：春节（第 3/9 天）。"
nextWorkday("CN", "2026-09-30");       // "2026-10-08"
workdaysBetween("CN", "2026-02-13", "2026-02-24");

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.

bash

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 / 路线图

Repository layout / 目录

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.

Similar modules

Browse Calendar