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.

Desktop extension (Claude Desktop)

The MCPB bundle in the releases packages this server for one-click install, with the full charting flow added:

Casting the four pillars needs the production engine (solar-term instants, luck-cycle start dates, the late-Zi convention), which is not part of this package — so the bundle forwards those three calls over HTTPS and passes the result through unchanged. Build it yourself with npm run build:mcpb.

The same hosted endpoint works as a plain remote MCP server, no install required:

claude mcp add --transport http bazi https://auspiceoracle.com/mcp/bazi

Privacy Policy

Full policy: https://auspiceoracle.com/en/privacy

• Local tools (true_solar_time, hour_branch) send nothing anywhere. No network, no telemetry, no files written.

• Remote tools (cast_chart, personality_sketch, compose_sketch) send the birth details you provide — date, clock time, IANA time zone, longitude, and for casting the gender flag that sets luck-cycle direction — to https://auspiceoracle.com/mcp/bazi over HTTPS, to compute that one response.

• No name, no email, no account, no authentication is asked for or accepted by that endpoint.

• Nothing is persisted: the endpoint is stateless and does not store birth details or results, and does not use them for training. Standard edge request logs (IP, timestamp, path) are kept by the CDN for abuse prevention; request bodies are not logged.

• No third parties receive the data; the endpoint calls no external service.

• Retention: none for request content. Contact: https://github.com/Shann5/true-solar-time-mcp/issues or the contact route on auspiceoracle.com.

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