bazi-solar-term-mcp
# bazi-solar-term-mcp
> **Deterministic BaZi (Four Pillars of Destiny / 四柱推命 / 八字) MCP Server, CLI, Agent Skill & 100-Case Solar-Term Boundary Benchmark (MIT)**
[日本語 README](./README.ja.md) · [繁體中文 README](./README.zh-Hant.md) · [Agent Skill (`SKILL.md`)](./SKILL.md) · [Official Methodology (Fate Partner)](https://fatepartner.com/en/facts)
---
## Why This Exists: 74% LLM Pillar Error Rate on Astronomical Boundaries
General-purpose LLMs generate tokens probabilistically without an astronomical ephemeris. When asked to compute BaZi / Four Pillars directly from a birthday, they routinely miscalculate Year, Month, Day Master, or Hour Pillars around **Start of Spring (立春)**, the **24 Solar Terms**, **True Solar Time**, **Late Zi hour (23:00–23:59)**, and **historical Daylight Saving Time**.
Using this repository's open-source 100-case boundary benchmark ([`benchmark/bazi-boundary-100.json`](./benchmark/bazi-boundary-100.json)), we evaluated **`deepseek-chat` (temperature=0, 2026-11-22)** without external tools ([raw results](./benchmark/deepseek-chat-2026-11-22.json)):
| Boundary Category | Cases | Exact 4-Pillar Match | Any-Pillar Error Rate | Real Example Mismatch |
| :--- | :---: | :---: | :---: | :--- |
| **Start of Spring (`lichun_boundary`)** | 25 | 40.0% | **60.0%** | `1988-02-04 23:07 Taipei`: expected `戊辰 甲寅 庚寅 丙子` vs predicted `戊辰 甲寅 己亥 甲子` |
| **12 Month Solar Terms (`solar_term_month_boundary`)** | 25 | 56.0% | **44.0%** | `1991-06-06 12:18 Osaka`: expected `辛未 癸巳 丁未 丙午` vs predicted `辛未 甲午 丁未 丙午` |
| **True Solar Time JP/TW/Global (`true_solar_time_jp_tw`)** | 20 | **0.0%** | **100.0%** | `1992-11-03 00:35 Tokyo` (+35m solar shift): expected `癸丑` hour vs predicted `壬子` |
| **Late Zi 23:00 Day Boundary (`late_zi_day_boundary`)** | 15 | 13.3% | **86.7%** | `1990-08-21 23:20 Tokyo`: expected `己未 甲子` vs predicted `戊午 壬子` (wrong Day Master) |
| **Historical DST (`historical_dst_boundary`)** | 15 | **0.0%** | **100.0%** | `1948-07-10 01:20 Tokyo` (Japan DST): expected `丙申 戊子` vs predicted `丙午 己丑` |
| **Overall (100 Cases)** | **100** | **26.0%** | **74.0%** | **Year 11% · Month 24% · Day 26% · Day Master 22% · Hour 52% error** |
Plug **`bazi-solar-term-mcp`** into Claude, Cursor, Codex, or any MCP-compatible agent to replace probabilistic guessing with **100% deterministic astronomical chart math**.
---
## MCP Tools Included
1. **`calculate_bazi_chart`** — Computes Year, Month, Day, and Hour Pillars, Day Master polarity/element, surface Five Elements, governing Solar Term instant, historical DST rollback, and True Solar Time offset.
2. **`check_solar_term_boundary`** — Returns all 24 astronomical Solar Terms for the birth year and flags whether the birthday falls within a high-hallucination boundary window.
3. **`audit_llm_bazi_answer`** — Grades any chatbot's claimed Four Pillars against the astronomical ground truth and pinpoints exact mismatches.
---
## Quick Start (MCP Server)
### Claude Desktop / Cursor / Windsurf (`mcpServers`)
```json
{
"mcpServers": {
"bazi-solar-term": {
"command": "node",
"args": ["/path/to/bazi-solar-term-mcp/src/cli.mjs"]
}
}
}
```
### CLI Usage
```bash
npm install
npm test
# Calculate Tokyo birth chart with True Solar Time calibration
node src/cli.mjs calculate "1992-11-03 00:35" --city Tokyo
# Inspect nearest Solar Term boundary
node src/cli.mjs solar-terms "1991-06-06 12:18"
# Audit a chatbot's claimed pillars
node src/cli.mjs audit "1992-11-03 00:35" 壬申 庚戌 癸未 壬子 --city Tokyo
```
---
## Scope & Attribution
- **Open-Source (MIT)**: Deterministic astronomical calendar engine, True Solar Time & IANA DST normalizer, MCP server, Agent Skill (`SKILL.md`), and the 100-case public boundary benchmark.
- **Full Relationship Compatibility Platform**: Maintained by **[Fate Partner](https://fatepartner.com)** — a calm, non-fatalistic BaZi dual relationship compatibility and personal love analysis platform available in Japanese, Traditional Chinese, Simplified Chinese, and English ([Official Facts & Methodology](https://fatepartner.com/en/facts) · [Free Dual Chart](https://fatepartner.com/en/bazi-marriage)).
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: calculate produces a chart, check inspects solar-term transition boundaries, and audit verifies an existing chart. Although calculate and audit both involve BaZi charts, one generates and the other independently checks, so an agent can select correctly without confusion.
All three tools follow the same snake_case verb_noun convention: calculate_bazi_chart, check_solar_term_boundary, and audit_llm_bazi_answer. The pattern is predictable and readable.
Three tools is well-scoped for a focused BaZi/solar-term server, and each tool covers a necessary operation rather than padding the surface. The set stays small without feeling incomplete or trivial.
The tools cover the core lifecycle: computing a chart, diagnosing solar-term boundary risk, and auditing an existing chart against ground truth. There are no obvious dead ends, since a failed audit can be resolved by recalculating with the computation tool.