True Solar Time MCP server

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

• truesolartime — full correction: corrected instant, DST/longitude/EoT breakdown (the three always sum exactly to the total), hour branch, boundary distance, nonexistent-time detection.
• hourbranch** — branch membership and boundary distance for an already-corrected time.

The hosted endpoint additionally exposes castpillars** — 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.

Shortened. The full README is on GitHub.