true-solar-time-mcp

# 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

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

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

**Local (stdio):**


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

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](https://auspiceoracle.com/en/method)). 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

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

## Desktop extension (Claude Desktop)

The MCPB bundle in the [releases](https://github.com/Shann5/true-solar-time-mcp/releases) packages this server for one-click install, with the full charting flow added:

| Tool | Where it runs |
|---|---|
| `true_solar_time`, `hour_branch` | locally, offline, from the code in this repo |
| `cast_chart`, `personality_sketch`, `compose_sketch` | remotely, on `https://auspiceoracle.com/mcp/bazi` |

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:

```bash
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](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)