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.

Related MCP server: BaZi (Eight Characters) Calculator

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. Three worked examples with full derivations: the birth-time test. Background essay: true solar time.

MCP server

Hosted endpoint (no install): https://auspiceoracle.com/mcp — stateless streamable HTTP, no auth. Works as a claude.ai custom connector or in any MCP client that speaks streamable HTTP:

{
  "mcpServers": {
    "true-solar-time": { "url": "https://auspiceoracle.com/mcp" }
  }
}

Local (stdio):

{
  "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.

The hosted endpoint additionally exposes cast_pillars — solar-corrected four pillars with hidden stems, Na Yin and luck cycles, computed by the production Auspice Oracle engine (closed source; same conventions as the published methodology). Facts only — no strength verdicts, no interpretation.

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

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. 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