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:

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.

Related MCP server: BaZi (Eight Characters) Calculator

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