Skip to main content
Glama
True Solar Time MCP Server

True Solar Time MCP Server

README.md
# True Solar Time MCP Server

[![MCP server](https://img.shields.io/badge/MCP-server-5f5bd6)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io/) server for deterministic **true solar time** conversion from a local civil time, IANA timezone, and longitude.

Built for reproducible calendrical, astronomy, BaZi, and Four Pillars workflows. The server is intentionally narrow: it does not geocode an address, call a language model, persist birth data, or generate fortune-telling text.

## Why this is useful

- **No address lookup.** Pass the timezone and coordinates you already trust; there is no hidden geocoding request.
- **Transparent correction.** The result separates longitude correction, equation of time, DST correction, UTC, and date rollover.
- **MCP-native.** One read-only tool works with Claude Desktop, Cursor, Codex, and other MCP clients.
- **Privacy-friendly.** Calculation is local to the process running the server.

## Tool

### `calculate_true_solar_time`

Input:

```json
{
  "date": "1990-05-20",
  "time": "14:30",
  "timezone": "Asia/Shanghai",
  "longitude": 104.0668,
  "latitude": 30.5728
}
```

`longitude` is required and uses decimal degrees with east positive. `latitude` is optional and is retained for traceability; the correction is driven by longitude, the time-zone offset, and the equation of time.

The result includes the civil time, UTC instant, corrected true solar time, longitude correction, equation-of-time correction, DST correction, date shifts, warnings, and a confidence label.

## Quick start

```bash
git clone https://github.com/cdaily1995-create/true-solar-time-mcp.git
cd true-solar-time-mcp
pnpm install
pnpm build
node dist/server.js
```

MCP client configuration:

```json
{
  "mcpServers": {
    "true-solar-time": {
      "command": "node",
      "args": ["/absolute/path/to/true-solar-time-mcp/dist/server.js"]
    }
  }
}
```

## Example

```text
calculate_true_solar_time {
  "date": "2002-07-07",
  "time": "05:05",
  "timezone": "America/Los_Angeles",
  "longitude": -118.2437,
  "latitude": 34.0522
}
```

The response includes a versioned `engineVersion`, the UTC instant, the corrected local apparent solar time, each correction component, warnings, and confidence.

## Input contract

| Field       | Required | Description                                                       |
| ----------- | -------- | ----------------------------------------------------------------- |
| `date`      | yes      | Local civil date in `YYYY-MM-DD`.                                 |
| `time`      | yes      | Local civil time in `HH:mm`.                                      |
| `timezone`  | yes      | IANA identifier such as `Asia/Shanghai` or `America/Los_Angeles`. |
| `longitude` | yes      | Decimal degrees, east positive, from `-180` to `180`.             |
| `latitude`  | no       | Decimal degrees, from `-90` to `90`; retained for traceability.   |

## Links

- [BaZi Calculator](https://bazi-calculator.co/) — the public calculator project using this kind of time normalization.
- [Four Pillars of Destiny guide](https://bazi-calculator.co/four-pillars-of-destiny) — background on the chart context.
- [What is a BaZi chart?](https://bazi-calculator.co/what-is-a-bazi-chart) — plain-language chart explanation.
- [Four Pillars MCP Server](https://github.com/cdaily1995-create/four-pillars-mcp) — the companion deterministic chart calculator.
- [MCP specification](https://modelcontextprotocol.io/) — protocol documentation.
- [MCP TypeScript server SDK](https://www.npmjs.com/package/@modelcontextprotocol/server) — server SDK used by this project.
- [Full link inventory](LINKS.md) and [method references](REFERENCES.md).

## Search-friendly description

This project is a true solar time calculator for birth-time normalization. It explains how civil time, longitude, historical time zones, daylight-saving offsets, and the equation of time affect local apparent solar time. It is useful for BaZi, Four Pillars, traditional calendar, astronomy, and time-normalization workflows where reproducible numeric output is more important than interpretation.

## Privacy and scope

The server accepts coordinates and time-zone identifiers only. It has no address search, analytics, database, account, payment, or external API requirement. Results are calculated locally by the process running the MCP server.

This is a time conversion utility, not scientific proof of any astrological interpretation and not a prediction service.

## License

MIT

TDQS

A4.1/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusing it with another. Its purpose—converting civil time to true solar time—is stated unambiguously in the description.

Naming Consistency5/5

The single name, calculate_true_solar_time, follows a clear snake_case verb_noun pattern and precisely describes the action and target. No competing conventions exist to conflict with it.

Tool Count3/5

A one-tool surface is thin even for a narrowly scoped calculation server; useful neighbors like inverse conversion or batch/multi-date processing are absent. The tool itself is non-trivial and earns its place, but the set feels minimal.

Completeness3/5

The stated forward conversion (civil time → true solar time) appears fully served, including UTC, equation of time, DST and confidence outputs. However, there is no inverse conversion (true solar → civil), no batch handling, and no related solar computations, leaving notable gaps for agents working the domain both ways.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues