{"slug": "building-an-offline-rokuyo-calendar-mcp-server-in-node-js", "title": "Building an offline Rokuyo calendar MCP server in Node.js", "summary": "The Astromei team released an open-source Rokuyo calendar core library and a Model Context Protocol adapter that exposes three read-only tools — get_rokuyo, get_rokuyo_month and find_rokuyo_dates — for querying the traditional Japanese six-label calendar system locally in Node.js 20 or later. Calendar queries run offline after installation with no API key or runtime network requests, and the library restricts its supported window to January 1, 2025 through December 31, 2027, throwing RangeError outside it. The team notes the lunar conversion relies on the MIT-licensed korean-lunar-calendar (KASI, UTC+9) and is not an official Japanese calendar, warning that substituting a UTC+8 calendar can shift results near midnight new moons.", "body_md": "Rokuyo (六曜) is a traditional six-label calendar system used in Japan. You may see labels such as 大安 (Taian) and 友引 (Tomobiki) on calendars or when people discuss wedding dates.\n\nWe maintain [Astromei](https://astromei.com/ja?utm_source=devto&utm_medium=referral&utm_campaign=rokuyo_mcp_tutorial), an astrology platform with a [Japanese Rokuyo calendar](https://astromei.com/ja/rokuyo?utm_source=devto&utm_medium=referral&utm_campaign=rokuyo_mcp_tutorial). We extracted its calendar calculation into an open-source core library, then added a small Model Context Protocol adapter.\n\nThis tutorial shows how to run the source locally, query it from JavaScript, and connect its three read-only tools to a stdio MCP client.\n\nThe repositories are public, but the npm releases are still pending as of November 20, 2026. For now, use the source checkout rather than `npx astromei`.\n\nYou need Node.js 20 or later, npm, and Git:\n\n```\ngit clone https://github.com/astromei/rokuyo-mcp.git\ncd rokuyo-mcp\nnpm ci\nnpm run build\n```\n\nInstallation needs network access. The MCP adapter currently depends on a pinned HTTPS Git commit of [astromei-core](https://github.com/astromei/astromei-core); installation builds that dependency automatically. Calendar queries run locally afterward, without an API key or runtime network requests.\n\nThe initial supported date range is **January 1, 2025 through December 31, 2027**. This boundary is part of the API contract, not an invitation to extrapolate to other years.\n\nSave the following as `example.mjs` in the checkout:\n\n``` js\nimport {\n  getRokuyo,\n  getRokuyoMonth,\n  findRokuyoDates,\n} from './dist/index.js';\n\nconst day = getRokuyo('2026-10-11');\nconsole.log(day.rokuyo);\nconsole.log(day.lunarDate);\n\nconst month = getRokuyoMonth(2026, 11);\nconsole.log(month.length);\n\nconst taianDates = findRokuyoDates(\n  '2026-11-01',\n  '2026-11-30',\n  '大安',\n);\nconsole.log(taianDates.map(({ date }) => date));\n```\n\nRun it:\n\n```\nnode example.mjs\n```\n\nThese are the results from the current implementation:\n\n```\n先負\n{ year: 2026, month: 9, day: 1, leap: false }\n30\n[\n  '2026-11-06',\n  '2026-11-10',\n  '2026-11-16',\n  '2026-11-22',\n  '2026-11-28'\n]\n```\n\nThe daily result also includes Japanese pronunciation, romaji, a short cultural description, and customary time-slot descriptions. Those descriptions explain calendar traditions; they are not forecasts.\n\nInputs use date-only strings in `YYYY-MM-DD` format, representing calendar dates in `Asia/Tokyo`. Invalid dates or dates outside the supported window throw `RangeError`. Range searches include both endpoints and accept at most 366 days.\n\nThe label calculation is small:\n\n``` js\nconst labels = ['先勝', '友引', '先負', '仏滅', '大安', '赤口'];\nconst label = labels[(lunarMonth + lunarDay - 2) % 6];\n```\n\nThe harder part is deciding which lunar month and day correspond to the input date. A one-day difference at a new-moon boundary changes the label.\n\nFor example, the current engine returns:\n\n| Gregorian date | Lunar month/day | Rokuyo | \n|---|---|---|\n| 2026-10-10 | 8/30 | 先勝 | \n| 2026-10-11 | 9/1 | 先負 | \n\nOur lunar conversion uses the MIT-licensed [korean-lunar-calendar](https://github.com/usingsky/korean_lunar_calendar_js), based on KASI's UTC+9 calendar. It follows the convention used by Astromei's calendar. It is **not an official Japanese calendar**, and Korean and Japanese calendar conventions should not be assumed identical for every historical or future year.\n\nSubstituting a UTC+8 lunar calendar can change the result near midnight new moons. That is why the library states its conversion source and restricts its supported window. A production integration should document its calendar convention just as explicitly as its timezone.\n\nThe adapter exposes three tools:\n\n| Tool | Input | Purpose | \n|---|---|---|\n| `get_rokuyo` | `date` | Return one date's Rokuyo and lunar date | \n| `get_rokuyo_month` | `year` ,`month` | Generate a Gregorian month's calendar | \n| `find_rokuyo_dates` | `start` ,`end` , optional`rokuyo` | Find matching labels in a date range | \n\nFor a client supporting local stdio MCP servers, configure the built checkout:\n\n```\n{\n  \"mcpServers\": {\n    \"astromei-rokuyo\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/rokuyo-mcp/dist/stdio.js\"]\n    }\n  }\n}\n```\n\nReplace the path with your actual checkout path. If your desktop client does not inherit your shell's Node installation, use the full path to the Node executable too.\n\nYou can then ask the client: “List the Taian dates in November 2026.” The client can call `find_rokuyo_dates` and receive structured calendar results rather than inventing dates in prose.\n\nAll three tools are read-only. This first release does not calculate Japanese public holidays, Ichiryumanbaibi, Tenshanichi, astronomy, or birth charts. The npm-based launch configuration will become useful after the registry release; the source configuration above works independently of that release.\n\nWe separated the project into two layers:\n\nThe repository includes tests for date validation, bounded searches, the midnight new-moon boundary, and an actual MCP stdio handshake and tool invocation. Run them with `npm test`.\n\nA model can help explain a returned label, but the date calculation stays in the deterministic layer. The same separation applies to cultural interpretation: describing a tradition should not turn it into a guarantee about an event's outcome.\n\nThe source is MIT licensed. If you would like to inspect the date behavior before integrating it, the [browser calendar](https://astromei.com/ja/rokuyo?utm_source=devto&utm_medium=referral&utm_campaign=rokuyo_mcp_tutorial) is another entry point.", "url": "https://wpnews.pro/news/building-an-offline-rokuyo-calendar-mcp-server-in-node-js", "canonical_source": "https://dev.to/astromei/building-an-offline-rokuyo-calendar-mcp-server-in-nodejs-5j4", "published_at": "2026-11-20 02:40:15+00:00", "updated_at": "2026-11-20 02:43:03.054625+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools"], "entities": ["Astromei", "Model Context Protocol", "Node.js", "korean-lunar-calendar", "astromei-core", "GitHub"], "also_reported_by": [], "takeaway": "The Rokuyo MCP adapter ships three read-only tools (get_rokuyo, get_rokuyo_month, find_rokuyo_dates) that run fully offline after a build-time install, but only for dates between 2025-01-01 and 2027-12-31, outside which inputs throw RangeError.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/building-an-offline-rokuyo-calendar-mcp-server-in-node-js", "markdown": "https://wpnews.pro/news/building-an-offline-rokuyo-calendar-mcp-server-in-node-js.md", "text": "https://wpnews.pro/news/building-an-offline-rokuyo-calendar-mcp-server-in-node-js.txt", "jsonld": "https://wpnews.pro/news/building-an-offline-rokuyo-calendar-mcp-server-in-node-js.jsonld"}}