true-solar-time-mcp

An MCP server for true solar time conversion and Chinese 时辰 boundary audit.

It is designed for time-sensitive divination workflows such as Qi Men Dun Jia, Bazi, date selection, and other agents that need to know whether civil clock time and local true solar time fall into the same two-hour 时辰.

Tools

convert_true_solar_time

Converts civil time to true solar time.

Input:

{
  "datetime": "2026-06-16T13:10:00+08:00",
  "longitude": 104.06,
  "location": "Chengdu"
}

Output includes:

• UTC time
• civil time with original offset
• longitude correction
• equation of time
• true solar time
• civil 时辰
• true solar 时辰
• boundary risk

audit_shichen_boundary

Audits whether civil clock time and true solar time cross a 时辰 boundary.

Risk labels:

Risk	Meaning
none	same 时辰, safely away from boundary
watch	same 时辰, but disclose boundary proximity
high	close to boundary; verify longitude and prefer true solar time
critical	crosses 时辰 or is extremely close to a boundary

qimen_time_prepare

Returns the datetime that should be used for time-based Qi Men charting.

If civil time and true solar time cross 时辰, it returns qimen_time_basis=true_solar_time.

Algorithm

The server computes:

longitude_correction_minutes = longitude * 4 - timezone_offset_minutes
true_solar_time = civil_time + longitude_correction_minutes + equation_of_time

The equation of time uses a common NOAA-style approximation. This is intended for 时辰 boundary audit and metaphysics workflows, not navigation-grade astronomy.

Important:

• datetime must include an explicit timezone offset, such as +08:00 or -04:00.
• Longitude is degrees east; west longitude is negative.
• Latitude is optional and is kept for audit/display. It does not directly change true solar time.

Install

npm install
npm run build
npm test

MCP Config

Example Codex/Claude/OpenCode-style MCP config:

[mcp_servers.true_solar_time]
command = "node"
args = ["C:\\path\\to\\true-solar-time-mcp\\dist\\server.js"]

For local development:

npm run build
node dist/server.js

Example Result

{
  "civil_time": "2026-06-16T13:10:00+08:00",
  "longitude_correction_minutes": -63.76,
  "equation_of_time_minutes": -0.357,
  "true_solar_time": "2026-06-16T12:05:53+08:00",
  "civil_shichen": { "name": "未时", "branch": "未" },
  "solar_shichen": { "name": "午时", "branch": "午" },
  "crosses_shichen": true,
  "boundary_risk": "critical"
}

License

MIT