<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Astromei</title>
    <description>The latest articles on DEV Community by Astromei (@astromei).</description>
    <link>https://dev.to/astromei</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254722%2F76594394-840d-48cf-a918-99cd82720bd1.png</url>
      <title>DEV Community: Astromei</title>
      <link>https://dev.to/astromei</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/astromei"/>
    <language>en</language>
    <item>
      <title>Building an offline Rokuyo calendar MCP server in Node.js</title>
      <dc:creator>Astromei</dc:creator>
      <pubDate>Fri, 20 Nov 2026 02:40:15 +0000</pubDate>
      <link>https://dev.to/astromei/building-an-offline-rokuyo-calendar-mcp-server-in-nodejs-5j4</link>
      <guid>https://dev.to/astromei/building-an-offline-rokuyo-calendar-mcp-server-in-nodejs-5j4</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;We maintain &lt;a href="https://astromei.com/ja?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=rokuyo_mcp_tutorial" rel="noopener noreferrer"&gt;Astromei&lt;/a&gt;, an astrology platform with a &lt;a href="https://astromei.com/ja/rokuyo?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=rokuyo_mcp_tutorial" rel="noopener noreferrer"&gt;Japanese Rokuyo calendar&lt;/a&gt;. We extracted its calendar calculation into an open-source core library, then added a small Model Context Protocol adapter.&lt;/p&gt;

&lt;p&gt;This tutorial shows how to run the source locally, query it from JavaScript, and connect its three read-only tools to a stdio MCP client.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start from the GitHub source
&lt;/h2&gt;

&lt;p&gt;The repositories are public, but the npm releases are still pending as of November 20, 2026. For now, use the source checkout rather than &lt;code&gt;npx astromei&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;You need Node.js 20 or later, npm, and Git:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/astromei/rokuyo-mcp.git
&lt;span class="nb"&gt;cd&lt;/span&gt; rokuyo-mcp
npm ci
npm run build
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Installation needs network access. The MCP adapter currently depends on a pinned HTTPS Git commit of &lt;a href="https://github.com/astromei/astromei-core" rel="noopener noreferrer"&gt;astromei-core&lt;/a&gt;; installation builds that dependency automatically. Calendar queries run locally afterward, without an API key or runtime network requests.&lt;/p&gt;

&lt;p&gt;The initial supported date range is &lt;strong&gt;January 1, 2025 through December 31, 2027&lt;/strong&gt;. This boundary is part of the API contract, not an invitation to extrapolate to other years.&lt;/p&gt;

&lt;h2&gt;
  
  
  Query one date, one month, or a range
&lt;/h2&gt;

&lt;p&gt;Save the following as &lt;code&gt;example.mjs&lt;/code&gt; in the checkout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;getRokuyo&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;getRokuyoMonth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;findRokuyoDates&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'./dist/index.js'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;day&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;getRokuyo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'2026-10-11'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;day&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;rokuyo&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;day&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lunarDate&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;month&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;getRokuyoMonth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2026&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;11&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;month&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;taianDates&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;findRokuyoDates&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="s1"&gt;'2026-11-01'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s1"&gt;'2026-11-30'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s1"&gt;'大安'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;taianDates&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;date&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;date&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;node example.mjs
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;These are the results from the current implementation:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;先負
{ year: 2026, month: 9, day: 1, leap: false }
30
[
  '2026-11-06',
  '2026-11-10',
  '2026-11-16',
  '2026-11-22',
  '2026-11-28'
]
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The 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.&lt;/p&gt;

&lt;p&gt;Inputs use date-only strings in &lt;code&gt;YYYY-MM-DD&lt;/code&gt; format, representing calendar dates in &lt;code&gt;Asia/Tokyo&lt;/code&gt;. Invalid dates or dates outside the supported window throw &lt;code&gt;RangeError&lt;/code&gt;. Range searches include both endpoints and accept at most 366 days.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why lunar conversion matters more than the final formula
&lt;/h2&gt;

&lt;p&gt;The label calculation is small:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;labels&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'先勝'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'友引'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'先負'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'仏滅'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'大安'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'赤口'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;label&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;labels&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lunarMonth&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;lunarDay&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The 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.&lt;/p&gt;

&lt;p&gt;For example, the current engine returns:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Gregorian date&lt;/th&gt;
&lt;th&gt;Lunar month/day&lt;/th&gt;
&lt;th&gt;Rokuyo&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2026-10-10&lt;/td&gt;
&lt;td&gt;8/30&lt;/td&gt;
&lt;td&gt;先勝&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2026-10-11&lt;/td&gt;
&lt;td&gt;9/1&lt;/td&gt;
&lt;td&gt;先負&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Our lunar conversion uses the MIT-licensed &lt;a href="https://github.com/usingsky/korean_lunar_calendar_js" rel="noopener noreferrer"&gt;korean-lunar-calendar&lt;/a&gt;, based on KASI's UTC+9 calendar. It follows the convention used by Astromei's calendar. It is &lt;strong&gt;not an official Japanese calendar&lt;/strong&gt;, and Korean and Japanese calendar conventions should not be assumed identical for every historical or future year.&lt;/p&gt;

&lt;p&gt;Substituting 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Connect the tools to an MCP client
&lt;/h2&gt;

&lt;p&gt;The adapter exposes three tools:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Tool&lt;/th&gt;
&lt;th&gt;Input&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;get_rokuyo&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;date&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Return one date's Rokuyo and lunar date&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;get_rokuyo_month&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;year&lt;/code&gt;, &lt;code&gt;month&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Generate a Gregorian month's calendar&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;find_rokuyo_dates&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;start&lt;/code&gt;, &lt;code&gt;end&lt;/code&gt;, optional &lt;code&gt;rokuyo&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Find matching labels in a date range&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For a client supporting local stdio MCP servers, configure the built checkout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"mcpServers"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"astromei-rokuyo"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"command"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"node"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"args"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"/absolute/path/to/rokuyo-mcp/dist/stdio.js"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Replace 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.&lt;/p&gt;

&lt;p&gt;You can then ask the client: “List the Taian dates in November 2026.” The client can call &lt;code&gt;find_rokuyo_dates&lt;/code&gt; and receive structured calendar results rather than inventing dates in prose.&lt;/p&gt;

&lt;p&gt;All 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep calculation and interpretation separate
&lt;/h2&gt;

&lt;p&gt;We separated the project into two layers:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://github.com/astromei/astromei-core" rel="noopener noreferrer"&gt;astromei-core&lt;/a&gt;:&lt;/strong&gt; calendar calculation, without MCP or AI dependencies.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://github.com/astromei/rokuyo-mcp" rel="noopener noreferrer"&gt;rokuyo-mcp&lt;/a&gt;:&lt;/strong&gt; protocol tools and compatible JavaScript exports.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The 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 &lt;code&gt;npm test&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;A 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.&lt;/p&gt;

&lt;p&gt;The source is MIT licensed. If you would like to inspect the date behavior before integrating it, the &lt;a href="https://astromei.com/ja/rokuyo?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=rokuyo_mcp_tutorial" rel="noopener noreferrer"&gt;browser calendar&lt;/a&gt; is another entry point.&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>javascript</category>
      <category>opensource</category>
      <category>node</category>
    </item>
  </channel>
</rss>
