True Solar Time

What the True Solar Time MCP server does

The True Solar Time MCP server converts civil birth records into the Sun-based time used by BaZi and Four Pillars calculations. Inputs include the recorded date and clock time, an IANA time-zone identifier, and the birthplace longitude. The result includes the corrected time plus the separate effects of daylight saving time, longitude, and the equation of time.

This is a correction layer, not a complete interpretation system. It does not select favorable elements or provide readings. The local implementation also does not cast a full chart; it is intended to run before a separate caster receives the corrected time.

The calculation reports whether the corrected time is near an hour-branch boundary. By default, the warning threshold is eight minutes. It also identifies civil times that fell inside a spring-forward gap, where the stated clock time did not correspond to a real instant.

How it works

Historical offset data comes from the runtime's ICU time-zone database, with Node.js 18 or newer required for the documented historical behavior. Longitude adjusts the shared civil clock toward local solar time, while the equation-of-time calculation accounts for the seasonal difference between apparent and mean solar time. The three correction components sum exactly to the reported total.

Hour branches occupy 120-minute intervals and change on odd hours, with Zi beginning at 23:00. Near a boundary, the response gives the distance so an application can cast both possible candidates instead of treating the result as exact.

The True Solar Time MCP server is deterministic: identical inputs produce identical outputs. A standard-offset change during a year can make the DST and longitude labels in the component breakdown imperfect, but the total correction still uses the actual offset.

Setup and configuration

Use the local stdio server through npx with the package name true-solar-time-mcp:

{
  "mcpServers": {
    "true-solar-time": {
      "command": "npx",
      "args": ["-y", "true-solar-time-mcp"]
    }
  }
}

The hosted endpoint at https://auspiceoracle.com/mcp uses stateless streamable HTTP and does not require authentication. It can be added as a remote MCP connection, including as a Claude custom connector. The repository also provides an MCPB bundle for Claude Desktop; its remote charting calls use the separate /mcp/bazi endpoint.

The package can also be used as a TypeScript library through toTrueSolarTime. No environment variables are documented as required.

Tools and capabilities

• true_solar_time: Calculates the corrected instant, correction total, DST, longitude, and equation-of-time components; returns the hour branch, boundary distance, and nonexistent-time status.
• hour_branch: Determines branch membership and boundary distance for a time that has already been corrected.
• cast_pillars: Available on the hosted endpoint, returning solar-corrected Four Pillars with hidden stems, Na Yin, and luck cycles.

The hosted endpoint's cast_pillars tool uses the production Auspice Oracle engine. The Claude Desktop bundle also forwards cast_chart, personality_sketch, and compose_sketch remotely; those tools are not local code from this repository.

Limitations and notes

Local tools operate offline and write no files or telemetry. Remote charting tools send the supplied birth details over HTTPS, including the date, time, time zone, longitude, and—when required for casting—the gender flag used for luck-cycle direction. The hosted service is described as stateless and does not retain request content, though standard edge logs are kept for abuse prevention.

A corrected time should be passed to a chart caster before pillar calculation. The boundary warning is a stated convention rather than a physical uncertainty measurement, so applications may choose a different tolerance while still considering both candidates near a boundary. The repository does not maintain its own time-zone tables.