true-solar-time-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shan Liu
+
+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,80 @@
+# true-solar-time-mcp
+
+**True solar time correction for BaZi / Four Pillars charts — the step most calculators skip.**
+
+An MCP server, CLI, and TypeScript library that converts a recorded birth time (wall clock + IANA time zone + longitude) into the sun's actual time at the birthplace. Deterministic: same input, same output, every time.
+
+```
+$ npx true-solar-time 1988-07-01 08:00 Asia/Shanghai 121.47
+
+clock time    1988-07-01 08:00 (Asia/Shanghai, DST GMT+9)
+true solar    1988-07-01 07:02
+correction    -58 min
+  DST         -60
+  longitude   +6
+  eq. of time -4
+hour branch   辰 (2 min from 卯)
+⚠ within 8 min of a branch boundary — cast both candidates
+```
+
+## Why this exists
+
+A BaZi chart is a function of the sun's position, but birth records are written in civil clock time. Between the two sit three corrections that nearly every chart tool — including the popular open-source LLM "skills" — silently skips:
+
+1. **Historical DST.** China observed daylight saving time from 1986 to 1991. Everyone born in those six summers has a birth certificate recording a clock moved forward one hour — enough to cross an entire hour branch, and at the right time of night, the day pillar too. The IANA/ICU time-zone database knows this; most calculators never ask it.
+2. **Longitude.** China spans four geographic time zones and runs on one clock. At 07:10 Beijing time in Ürümqi, local solar time is barely past 05:00 — two full branches away.
+3. **Equation of time.** True and mean solar time drift apart by up to ±16 minutes over the year (NOAA approximation here, error well under a minute). In early November it alone can move a chart across a branch boundary.
+
+This library also reports two things most tools won't tell you:
+
+- **Whether your birth time ever existed.** On a spring-forward night the local clock jumps from 01:59 to 03:00; a birth record saying 02:30 refers to no real instant. We detect the gap, report its width, and never silently guess.
+- **How close the corrected time sits to a branch boundary.** Within a few minutes, the honest answer is "cast both candidates", not false precision.
+
+## What it deliberately does *not* do
+
+It does not cast charts, pick favorable elements, or interpret anything. Casting is a solved problem with good open-source implementations; interpretation has no unique right answer and doesn't belong in a lookup library. One step, done carefully.
+
+The full methodology — every constant, threshold, and convention, including the ones this library uses — is published at **[auspiceoracle.com/en/method](https://auspiceoracle.com/en/method)**. Three worked examples with full derivations: **[the birth-time test](https://auspiceoracle.com/en/content/birth-time-test)**. Background essay: **[true solar time](https://auspiceoracle.com/en/content/true-solar-time)**.
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "true-solar-time": {
+      "command": "npx",
+      "args": ["-y", "true-solar-time-mcp"]
+    }
+  }
+}
+```
+
+Tools:
+
+- **`true_solar_time`** — full correction: corrected instant, DST/longitude/EoT breakdown (the three always sum exactly to the total), hour branch, boundary distance, nonexistent-time detection.
+- **`hour_branch`** — branch membership and boundary distance for an already-corrected time.
+
+If you're building a BaZi skill or agent: call `true_solar_time` **before** casting, and pass the corrected time to your caster. An LLM cannot do this conversion in-context — the equation of time is a trigonometric series and the DST history lives in a database, not in model weights.
+
+## Library
+
+```ts
+import { toTrueSolarTime } from 'true-solar-time-mcp'
+
+const r = toTrueSolarTime(1992, 6, 15, 7, 10, 'Asia/Shanghai', 87.6)
+// r.hour === 4, r.minute === 59, r.correctionMinutes === -130
+// r.hourBranch === '寅' — two branches away from what the clock says
+```
+
+## Conventions, stated plainly
+
+- Hour branches switch on odd hours (子 starts at 23:00), 120 minutes each.
+- The boundary-risk flag uses an 8-minute threshold. That is a convention, not physics — tune it to your own tolerance; near-boundary charts should be cast both ways regardless.
+- Historical time zones come from your runtime's ICU data (Node ≥ 18). We do not maintain our own tables.
+- When the standard offset itself changed mid-year (Russia 2011), the DST/longitude split of the *breakdown* can attribute imperfectly; the total correction is always computed from the actual offset and is unaffected.
+
+## Relationship to auspiceoracle.com
+
+This is an extracted mirror of the solar-time layer of the engine behind [Auspice Oracle](https://auspiceoracle.com). The main engine is the source of truth; the golden tests here pin this mirror to the same published examples. Bug reports are very welcome; PRs that change the conventions above will be declined (a convention fork would make the published methodology untrue).
+
+MIT © [Shan Liu](https://auspiceoracle.com/en/about#author)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * CLI: npx true-solar-time 1988-07-01 08:00 Asia/Shanghai 121.47
+ */
+import { toTrueSolarTime, BOUNDARY_RISK_MINUTES } from './solar-time.js';
+const [date, time, timeZone, lonArg] = process.argv.slice(2);
+if (!date || !time || !timeZone || lonArg === undefined) {
+    console.log('Usage: true-solar-time <YYYY-MM-DD> <HH:mm> <IANA-timezone> <longitude>');
+    console.log('   eg: true-solar-time 1988-07-01 08:00 Asia/Shanghai 121.47');
+    process.exit(1);
+}
+const [y, m, d] = date.split('-').map(Number);
+const [hh, mm] = time.split(':').map(Number);
+const lon = Number(lonArg);
+if ([y, m, d, hh, mm, lon].some(Number.isNaN)) {
+    console.error('Could not parse arguments.');
+    process.exit(1);
+}
+let info;
+try {
+    info = toTrueSolarTime(y, m, d, hh, mm, timeZone, lon);
+}
+catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : String(e)} — is "${timeZone}" a valid IANA zone?`);
+    process.exit(1);
+}
+const pad = (n) => String(n).padStart(2, '0');
+const sign = (n) => (n >= 0 ? `+${n}` : `${n}`);
+console.log(`clock time    ${date} ${time} (${info.timeZone}${info.dst.active ? `, DST ${info.dst.abbr}` : ''})`);
+console.log(`true solar    ${info.year}-${pad(info.month)}-${pad(info.day)} ${pad(info.hour)}:${pad(info.minute)}`);
+console.log(`correction    ${sign(info.correctionMinutes)} min`);
+console.log(`  DST         ${sign(info.parts.dstMinutes)}`);
+console.log(`  longitude   ${sign(info.parts.longitudeMinutes)}`);
+console.log(`  eq. of time ${sign(info.parts.equationOfTimeMinutes)}`);
+console.log(`hour branch   ${info.hourBranch} (${info.minutesToBoundary} min from ${info.neighborBranch})`);
+if (info.boundaryRisk) {
+    console.log(`⚠ within ${BOUNDARY_RISK_MINUTES} min of a branch boundary — cast both candidates`);
+}
+if (info.nonexistentWallTime.hit) {
+    console.log(`⚠ this clock time never existed in ${info.timeZone} (DST gap of ${info.nonexistentWallTime.gapMinutes} min) — verify the birth record`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * MCP server: true solar time correction for BaZi / Four Pillars charts.
+ *
+ * One tool, on purpose. Casting a chart is a solved, commoditized problem
+ * (lunar-typescript, many MIT casters). The step nearly every tool skips is
+ * converting the recorded clock time into the sun's time at the birthplace —
+ * historical DST included. This server does exactly that step, and nothing else.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { toTrueSolarTime, hourBranchContext, BOUNDARY_RISK_MINUTES } from './solar-time.js';
+const server = new McpServer({
+    name: 'true-solar-time',
+    version: '1.0.0',
+});
+server.registerTool('true_solar_time', {
+    title: 'True solar time correction',
+    description: 'Convert a recorded birth time (wall clock + IANA time zone + longitude) into true solar time — ' +
+        'the time a BaZi / Four Pillars chart should actually be cast from. Returns the corrected instant, ' +
+        'the total correction decomposed into DST + longitude + equation-of-time (the three always sum exactly), ' +
+        'the resulting two-hour branch, distance to the nearest branch boundary, and whether the reported ' +
+        'clock time even existed (spring-forward DST gaps, e.g. China 1986–91). ' +
+        'Deterministic: same input, same output, every time.',
+    inputSchema: {
+        year: z.number().int().min(1800).max(2200).describe('Birth year (Gregorian)'),
+        month: z.number().int().min(1).max(12),
+        day: z.number().int().min(1).max(31),
+        hour: z.number().int().min(0).max(23).describe('Recorded wall-clock hour, 24h'),
+        minute: z.number().int().min(0).max(59),
+        timeZone: z
+            .string()
+            .describe("IANA time zone of the birthplace, e.g. 'Asia/Shanghai', 'America/Vancouver'"),
+        longitude: z
+            .number()
+            .min(-180)
+            .max(180)
+            .describe('Birthplace longitude in degrees, east positive (Ürümqi ≈ 87.6, Vancouver ≈ -123.1)'),
+    },
+}, async ({ year, month, day, hour, minute, timeZone, longitude }) => {
+    let info;
+    try {
+        info = toTrueSolarTime(year, month, day, hour, minute, timeZone, longitude);
+    }
+    catch (e) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${e instanceof Error ? e.message : String(e)} — check that timeZone is a valid IANA name.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const pad = (n) => String(n).padStart(2, '0');
+    const summary = [
+        `Corrected (true solar) time: ${info.year}-${pad(info.month)}-${pad(info.day)} ${pad(info.hour)}:${pad(info.minute)}`,
+        `Total correction: ${info.correctionMinutes >= 0 ? '+' : ''}${info.correctionMinutes} min = DST ${info.parts.dstMinutes} + longitude ${info.parts.longitudeMinutes >= 0 ? '+' : ''}${info.parts.longitudeMinutes} + equation of time ${info.parts.equationOfTimeMinutes >= 0 ? '+' : ''}${info.parts.equationOfTimeMinutes}`,
+        `Hour branch: ${info.hourBranch} (${info.minutesToBoundary} min from the ${info.neighborBranch} boundary)`,
+        info.boundaryRisk
+            ? `⚠ Boundary risk: within ${BOUNDARY_RISK_MINUTES} min of a branch boundary — a small error in the recorded time flips the hour pillar. Cast both candidates.`
+            : '',
+        info.nonexistentWallTime.hit
+            ? `⚠ The reported clock time never existed in ${info.timeZone} (spring-forward gap of ${info.nonexistentWallTime.gapMinutes} min). The birth record was likely written in pre-jump time — verify which clock it used.`
+            : '',
+        info.dst.active ? `DST was in effect (${info.dst.abbr}).` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return {
+        content: [
+            { type: 'text', text: summary },
+            { type: 'text', text: JSON.stringify(info, null, 2) },
+        ],
+    };
+});
+server.registerTool('hour_branch', {
+    title: 'Hour branch of a clock time',
+    description: 'Which two-hour branch (子丑寅卯…) a given time falls in, and how many minutes it sits from the ' +
+        'nearest branch boundary. Use on an already-corrected time; for raw birth records use true_solar_time.',
+    inputSchema: {
+        hour: z.number().int().min(0).max(23),
+        minute: z.number().int().min(0).max(59),
+    },
+}, async ({ hour, minute }) => {
+    const hb = hourBranchContext(hour, minute);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${hb.branch} — ${hb.minutes} min from the ${hb.neighbor} boundary${hb.minutes <= BOUNDARY_RISK_MINUTES ? ' (⚠ boundary risk: cast both candidates)' : ''}`,
+            },
+        ],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/solar-time.d.ts

@@ -0,0 +1,137 @@
+/**
+ * True solar time correction — the step most BaZi / Four Pillars calculators skip.
+ *
+ * Pipeline:
+ *   1. wall-clock time + IANA time zone (historical DST rules included, via ICU) → UTC instant
+ *   2. UTC + longitude × 4 min/degree → local mean solar time
+ *   3. + equation of time → true (apparent) solar time
+ *
+ * The total correction is also decomposed into three parts (DST + longitude +
+ * equation of time) whose rounded sum is always exactly equal to the total —
+ * so the result can be shown as an addition table a reader can check by hand.
+ *
+ * Equation of time uses the NOAA approximation (error well under a minute; it
+ * can only matter within ±1 minute of an hour-branch boundary). The bigger,
+ * more common risk is the corrected time landing near a boundary at all —
+ * see `minutesToBoundary` / `boundaryRisk`.
+ *
+ * No home-grown historical time-zone tables: Node's ICU data already knows
+ * China's 1986–91 DST, early Taiwan/HK/Singapore DST, pre-1949 Asia/Harbin,
+ * and so on. Give it the right IANA zone name and the offset is right.
+ *
+ * This file mirrors the engine behind https://auspiceoracle.com — the full
+ * methodology, with every constant, is published at
+ * https://auspiceoracle.com/en/method
+ */
+export interface SolarTimeParts {
+    /** DST component: usually −60 when DST was in effect, else 0. Always ≤ 0. */
+    dstMinutes: number;
+    /** Longitude component: (birth longitude − zone's standard meridian) × 4 min/deg */
+    longitudeMinutes: number;
+    /** Equation-of-time component */
+    equationOfTimeMinutes: number;
+}
+export interface TrueSolarTimeInfo {
+    /** Corrected instant, as local true-solar calendar fields */
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    /** Total correction relative to the reported wall-clock time (minutes) */
+    correctionMinutes: number;
+    /** Equation of time, one decimal (the rounded integer lives in `parts`) */
+    equationOfTimeMinutes: number;
+    /** DST + longitude + equation of time; the three always sum to correctionMinutes */
+    parts: SolarTimeParts;
+    timeZone: string;
+    /** Longitude normalized to within ±180° of the zone's standard meridian */
+    longitude: number;
+    /** Zone's actual UTC offset at that instant (minutes, DST included) */
+    tzOffsetMinutes: number;
+    /** Zone's standard offset (DST excluded) */
+    standardOffsetMinutes: number;
+    /** Standard meridian of the zone (degrees, east positive) = standardOffsetMinutes / 4 */
+    standardMeridian: number;
+    dst: {
+        active: boolean;
+        abbr: string;
+    };
+    /**
+     * The reported wall-clock time never existed in that zone (spring-forward
+     * gap — e.g. China, each year 1986–91, one night jumps 02:00 → 03:00).
+     * When hit, the correction is computed from the jump instant, and callers
+     * should tell the user to double-check which clock the record was written in.
+     */
+    nonexistentWallTime: {
+        hit: boolean;
+        gapMinutes: number;
+    };
+    /** Two-hour branch (子丑寅…) the corrected time falls in */
+    hourBranch: string;
+    /** Branch on the other side of the nearest boundary */
+    neighborBranch: string;
+    /** Minutes to the nearest hour-branch boundary; 0 = exactly on it */
+    minutesToBoundary: number;
+    /**
+     * Corrected time sits close enough to a boundary that a small error in the
+     * recorded birth time flips the entire hour pillar. Threshold below —
+     * it is a convention, not physics; treat near-boundary charts as "cast both".
+     */
+    boundaryRisk: boolean;
+}
+/** Within this many minutes of a branch boundary we flag `boundaryRisk` */
+export declare const BOUNDARY_RISK_MINUTES = 8;
+/** UTC offset (minutes, east positive) of an IANA zone at a given UTC instant */
+export declare function tzOffsetMinutes(timeZone: string, utcMillis: number): number;
+/** Zone abbreviation, e.g. 'PDT' / 'GMT+9' */
+export declare function tzAbbr(timeZone: string, utcMillis: number): string;
+/**
+ * Standard (non-DST) offset of the zone around a given instant.
+ *
+ * JS has no isdst API, so sample Jan 1, Jul 1 and the instant itself and take
+ * the minimum: DST always moves the clock forward (larger offset), so the
+ * minimum is the standard offset in both hemispheres. Including the instant
+ * itself keeps dstMinutes ≤ 0 — otherwise Morocco-style "negative DST"
+ * (Ramadan) would be reported as +60 minutes of DST.
+ *
+ * Limitation: in a year where the standard offset itself changed (Russia 2011,
+ * parts of South America), this heuristic attributes to "standard" whichever
+ * is smaller. That only affects how the parts are labeled — the total
+ * correction always comes from the actual offset and is unaffected.
+ */
+export declare function standardOffsetMinutes(timeZone: string, utcMillis: number): number;
+/**
+ * Wall-clock time (in the birth zone) → UTC millis, reporting whether that
+ * clock reading ever actually existed.
+ *
+ * At a spring-forward transition the local clock jumps straight from 01:59 to
+ * 03:00 — the hour in between **never happened in that zone** (China each
+ * year 1986–91; early DST in Taiwan/HK/Singapore too). For such inputs the
+ * fixed-point iteration below has no solution: the computed UTC instant reads
+ * back to a different local time than the input. A naive implementation
+ * returns it anyway, silently landing after the jump — so 02:59 and 03:00
+ * map to the same real instant yet produce different hour pillars.
+ *
+ * So we verify by reading back. On mismatch, classify as a gap input, pin
+ * `utc` to the jump instant (the first moment the clock is continuous again)
+ * and report the gap width, letting the caller say "this clock time did not
+ * exist that night" instead of guessing on the user's behalf.
+ */
+export declare function resolveWallTime(year: number, month: number, day: number, hour: number, minute: number, timeZone: string): {
+    utc: number;
+    nonexistent: boolean;
+    gapMinutes: number;
+};
+/** Equation of time (minutes), NOAA approximation */
+export declare function equationOfTimeMinutes(dayOfYear: number): number;
+/**
+ * Branch membership and boundary distance. Branches switch on odd hours
+ * (子 starts 23:00, 丑 starts 01:00, …), 120 minutes each.
+ */
+export declare function hourBranchContext(hour: number, minute: number): {
+    branch: string;
+    neighbor: string;
+    minutes: number;
+};
+export declare function toTrueSolarTime(year: number, month: number, day: number, hour: number, minute: number, timeZone: string, longitude: number): TrueSolarTimeInfo;

package/dist/solar-time.js

@@ -0,0 +1,230 @@
+/**
+ * True solar time correction — the step most BaZi / Four Pillars calculators skip.
+ *
+ * Pipeline:
+ *   1. wall-clock time + IANA time zone (historical DST rules included, via ICU) → UTC instant
+ *   2. UTC + longitude × 4 min/degree → local mean solar time
+ *   3. + equation of time → true (apparent) solar time
+ *
+ * The total correction is also decomposed into three parts (DST + longitude +
+ * equation of time) whose rounded sum is always exactly equal to the total —
+ * so the result can be shown as an addition table a reader can check by hand.
+ *
+ * Equation of time uses the NOAA approximation (error well under a minute; it
+ * can only matter within ±1 minute of an hour-branch boundary). The bigger,
+ * more common risk is the corrected time landing near a boundary at all —
+ * see `minutesToBoundary` / `boundaryRisk`.
+ *
+ * No home-grown historical time-zone tables: Node's ICU data already knows
+ * China's 1986–91 DST, early Taiwan/HK/Singapore DST, pre-1949 Asia/Harbin,
+ * and so on. Give it the right IANA zone name and the offset is right.
+ *
+ * This file mirrors the engine behind https://auspiceoracle.com — the full
+ * methodology, with every constant, is published at
+ * https://auspiceoracle.com/en/method
+ */
+/** Within this many minutes of a branch boundary we flag `boundaryRisk` */
+export const BOUNDARY_RISK_MINUTES = 8;
+/** UTC offset (minutes, east positive) of an IANA zone at a given UTC instant */
+export function tzOffsetMinutes(timeZone, utcMillis) {
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    });
+    const parts = {};
+    for (const p of dtf.formatToParts(utcMillis)) {
+        if (p.type !== 'literal')
+            parts[p.type] = parseInt(p.value, 10);
+    }
+    const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+    return Math.round((asUtc - utcMillis) / 60000);
+}
+/** Zone abbreviation, e.g. 'PDT' / 'GMT+9' */
+export function tzAbbr(timeZone, utcMillis) {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'short' }).formatToParts(utcMillis);
+    return parts.find((p) => p.type === 'timeZoneName')?.value ?? '';
+}
+/**
+ * Standard (non-DST) offset of the zone around a given instant.
+ *
+ * JS has no isdst API, so sample Jan 1, Jul 1 and the instant itself and take
+ * the minimum: DST always moves the clock forward (larger offset), so the
+ * minimum is the standard offset in both hemispheres. Including the instant
+ * itself keeps dstMinutes ≤ 0 — otherwise Morocco-style "negative DST"
+ * (Ramadan) would be reported as +60 minutes of DST.
+ *
+ * Limitation: in a year where the standard offset itself changed (Russia 2011,
+ * parts of South America), this heuristic attributes to "standard" whichever
+ * is smaller. That only affects how the parts are labeled — the total
+ * correction always comes from the actual offset and is unaffected.
+ */
+export function standardOffsetMinutes(timeZone, utcMillis) {
+    const year = new Date(utcMillis).getUTCFullYear();
+    return Math.min(tzOffsetMinutes(timeZone, Date.UTC(year, 0, 1)), tzOffsetMinutes(timeZone, Date.UTC(year, 6, 1)), tzOffsetMinutes(timeZone, utcMillis));
+}
+/**
+ * Wall-clock time (in the birth zone) → UTC millis, reporting whether that
+ * clock reading ever actually existed.
+ *
+ * At a spring-forward transition the local clock jumps straight from 01:59 to
+ * 03:00 — the hour in between **never happened in that zone** (China each
+ * year 1986–91; early DST in Taiwan/HK/Singapore too). For such inputs the
+ * fixed-point iteration below has no solution: the computed UTC instant reads
+ * back to a different local time than the input. A naive implementation
+ * returns it anyway, silently landing after the jump — so 02:59 and 03:00
+ * map to the same real instant yet produce different hour pillars.
+ *
+ * So we verify by reading back. On mismatch, classify as a gap input, pin
+ * `utc` to the jump instant (the first moment the clock is continuous again)
+ * and report the gap width, letting the caller say "this clock time did not
+ * exist that night" instead of guessing on the user's behalf.
+ */
+export function resolveWallTime(year, month, day, hour, minute, timeZone) {
+    const target = Date.UTC(year, month - 1, day, hour, minute);
+    let guess = target;
+    for (let i = 0; i < 2; i++) {
+        const offset = tzOffsetMinutes(timeZone, guess);
+        guess = target - offset * 60000;
+    }
+    // Read-back check: an existing clock time must be self-consistent
+    if (tzOffsetMinutes(timeZone, guess) * 60000 + guess === target) {
+        return { utc: guess, nonexistent: false, gapMinutes: 0 };
+    }
+    // Inside the gap. Bisect on the **UTC axis** (the local axis is
+    // discontinuous here, bisecting it is meaningless) for the minute where
+    // the offset jumps.
+    let lo = target - 86400000;
+    let hi = target + 86400000;
+    const offBefore = tzOffsetMinutes(timeZone, lo);
+    const offAfter = tzOffsetMinutes(timeZone, hi);
+    while (hi - lo > 60000) {
+        const mid = lo + Math.floor((hi - lo) / 2 / 60000) * 60000;
+        if (mid <= lo)
+            break;
+        if (tzOffsetMinutes(timeZone, mid) === offBefore)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    // hi = first instant after the jump; gap width = minutes the clock skipped
+    return { utc: hi, nonexistent: true, gapMinutes: offAfter - offBefore };
+}
+/** Equation of time (minutes), NOAA approximation */
+export function equationOfTimeMinutes(dayOfYear) {
+    const b = (2 * Math.PI * (dayOfYear - 81)) / 364;
+    return 9.87 * Math.sin(2 * b) - 7.53 * Math.cos(b) - 1.5 * Math.sin(b);
+}
+function utcDayOfYear(millis) {
+    const d = new Date(millis);
+    const start = Date.UTC(d.getUTCFullYear(), 0, 1);
+    return Math.floor((millis - start) / 86400000) + 1;
+}
+/** The twelve hour-branches; index = branch ordinal (子 = 0) */
+const HOUR_BRANCHES = ['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥'];
+/**
+ * Branch membership and boundary distance. Branches switch on odd hours
+ * (子 starts 23:00, 丑 starts 01:00, …), 120 minutes each.
+ */
+export function hourBranchContext(hour, minute) {
+    const idx = Math.floor(((hour + 1) % 24) / 2);
+    const pos = (((hour * 60 + minute - 60) % 120) + 120) % 120;
+    return pos <= 60
+        ? { branch: HOUR_BRANCHES[idx], neighbor: HOUR_BRANCHES[(idx + 11) % 12], minutes: pos }
+        : { branch: HOUR_BRANCHES[idx], neighbor: HOUR_BRANCHES[(idx + 1) % 12], minutes: 120 - pos };
+}
+/**
+ * Normalize longitude to within ±180° of the zone's standard meridian.
+ * Regions across the date line from their meridian (Chatham at 176.5°W on
+ * UTC+12:45, Samoa, Kiritimati) would otherwise get a mean solar time a full
+ * day off — which mis-casts the day pillar.
+ */
+function normalizeLongitude(longitude, standardMeridian) {
+    let lon = longitude;
+    while (lon - standardMeridian > 180)
+        lon -= 360;
+    while (lon - standardMeridian < -180)
+        lon += 360;
+    return lon;
+}
+/**
+ * The three rounded parts must sum exactly to the rounded total, or the
+ * addition table stops adding up. Distribute the residual (at most ±1) to the
+ * component with the largest rounding error — the zone offset is always whole
+ * minutes, so it lands on longitude or the equation of time.
+ */
+function allocateParts(total, exact) {
+    const rounded = exact.map((v) => Math.round(v));
+    let residual = total - rounded[0] - rounded[1] - rounded[2];
+    const order = exact
+        .map((v, i) => ({ i, err: Math.abs(v - rounded[i]) }))
+        .sort((a, b) => b.err - a.err);
+    for (const { i } of order) {
+        if (residual === 0)
+            break;
+        const step = Math.sign(residual);
+        rounded[i] += step;
+        residual -= step;
+    }
+    return rounded;
+}
+export function toTrueSolarTime(year, month, day, hour, minute, timeZone, longitude) {
+    const resolved = resolveWallTime(year, month, day, hour, minute, timeZone);
+    const utc = resolved.utc;
+    const actualOffset = tzOffsetMinutes(timeZone, utc);
+    const stdOffset = standardOffsetMinutes(timeZone, utc);
+    const standardMeridian = stdOffset / 4;
+    const lon = normalizeLongitude(longitude, standardMeridian);
+    // local mean solar time = UTC + longitude × 4 min (east positive)
+    const meanSolar = utc + lon * 4 * 60000;
+    const eot = equationOfTimeMinutes(utcDayOfYear(meanSolar));
+    const trueSolar = meanSolar + eot * 60000;
+    const d = new Date(trueSolar);
+    // The correction's reference is the clock time the user reported. A gap
+    // input has no such clock time, so use the local reading at the jump
+    // instant instead — otherwise the three parts stop summing to the total.
+    const clockAsUtc = resolved.nonexistent
+        ? utc + actualOffset * 60000
+        : Date.UTC(year, month - 1, day, hour, minute);
+    const correctionMinutes = Math.round((trueSolar - clockAsUtc) / 60000);
+    // total = −actual offset + longitude×4 + EoT
+    //       = (standard − actual) + (longitude×4 − standard) + EoT
+    //       =        DST         +      longitude           + EoT
+    const [dstMinutes, longitudeMinutes, eotMinutes] = allocateParts(correctionMinutes, [
+        stdOffset - actualOffset,
+        lon * 4 - stdOffset,
+        eot,
+    ]);
+    const outHour = d.getUTCHours();
+    const outMinute = d.getUTCMinutes();
+    const hb = hourBranchContext(outHour, outMinute);
+    return {
+        year: d.getUTCFullYear(),
+        month: d.getUTCMonth() + 1,
+        day: d.getUTCDate(),
+        hour: outHour,
+        minute: outMinute,
+        correctionMinutes,
+        equationOfTimeMinutes: Math.round(eot * 10) / 10,
+        parts: { dstMinutes, longitudeMinutes, equationOfTimeMinutes: eotMinutes },
+        timeZone,
+        longitude: lon,
+        tzOffsetMinutes: actualOffset,
+        standardOffsetMinutes: stdOffset,
+        standardMeridian,
+        dst: { active: dstMinutes !== 0, abbr: tzAbbr(timeZone, utc) },
+        nonexistentWallTime: {
+            hit: resolved.nonexistent,
+            gapMinutes: resolved.nonexistent ? resolved.gapMinutes : 0,
+        },
+        hourBranch: hb.branch,
+        neighborBranch: hb.neighbor,
+        minutesToBoundary: hb.minutes,
+        boundaryRisk: hb.minutes <= BOUNDARY_RISK_MINUTES,
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "true-solar-time-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.shann5/true-solar-time",
+  "description": "True solar time correction for BaZi / Four Pillars charts — historical DST + longitude + equation of time. The step most chart calculators skip. MCP server + CLI + library.",
+  "keywords": [
+    "bazi",
+    "four-pillars",
+    "chinese-astrology",
+    "true-solar-time",
+    "equation-of-time",
+    "mcp",
+    "mcp-server",
+    "timezone",
+    "dst"
+  ],
+  "license": "MIT",
+  "author": "Shan Liu (https://auspiceoracle.com)",
+  "homepage": "https://auspiceoracle.com/en/content/true-solar-time",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shann5/true-solar-time-mcp.git"
+  },
+  "type": "module",
+  "main": "dist/solar-time.js",
+  "types": "dist/solar-time.d.ts",
+  "bin": {
+    "true-solar-time-mcp": "dist/index.js",
+    "true-solar-time": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}