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

```json
{
  "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:

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

```bash
npm install
npm run build
npm test
```

## MCP Config

Example Codex/Claude/OpenCode-style MCP config:

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

For local development:

```bash
npm run build
node dist/server.js
```

## Example Result

```json
{
  "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