# bazi-reader-mcp

> 🇨🇳 **中国八字 (Four Pillars of Destiny)** ・ 🇯🇵 **四柱推命 (しちゅうすいめい)** ・ 🇰🇷 **사주팔자 (四柱八字)**
>
> The calculation engine (and MCP server) behind [Shunshi.AI](https://shunshi.ai) / 顺时, open-sourced.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Powered by Shunshi.AI](https://img.shields.io/badge/powered%20by-Shunshi.AI-purple)](https://shunshi.ai)
[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](#)

> 🇯🇵 **日本の開発者の方へ**: これは中国の「八字 (bāzì)」— 日本で言う **四柱推命** の計算エンジン + MCP サーバーです。生年月日・出生時刻・出生地から四柱 / 十神 / 大運 / 五行バランスを計算できます。**真太陽時（均時差）補正にも対応**しており、AI エージェント (Claude / Cursor / Cline など) から直接呼び出せます。
>
> 🇰🇷 **한국 개발자분들께**: 중국의 "八字 (bāzì)" — 한국에서는 **사주팔자**라고 부르는 명리학의 계산 엔진 + MCP 서버입니다. 생년월일·출생시각·출생지로부터 사주 / 십성 / 대운 / 오행 균형을 계산합니다. **진태양시 보정**도 지원하며, AI 에이전트 (Claude / Cursor / Cline 등) 에서 바로 사용할 수 있습니다.

---

## This repository is a monorepo with two published npm packages:

| Package | What it is | Install |
|---|---|---|
| **[`shunshi-bazi-core`](./packages/bazi-core)** | Pure TypeScript calculation library. Zero framework deps. Use it from any Node.js / browser app. | `npm install shunshi-bazi-core` |
| **[`shunshi-bazi-mcp`](./packages/bazi-mcp)** | Thin [Model Context Protocol](https://modelcontextprotocol.io/) server wrapping the core library. Drop-in tool for Claude Desktop / Cursor / Cline / any MCP client. | `npx -y shunshi-bazi-mcp` |

Both packages share the **same calculation engine** that powers [Shunshi.AI](https://shunshi.ai)'s production backend. Both are parity-tested on every release.

---

## Why this exists

Most existing open-source Bazi libraries (in any language) have at least one of these problems:

1. **No true solar time correction.** Clock time gets used as-is, which gives wrong charts for births far from the timezone's standard meridian (新疆 / 黑龙江 / the U.S. West Coast / 北海道). A 30-minute error shifts the whole hour pillar.
2. **Inconsistent 子时 handling.** Some libraries put 23:00-23:59 in "yesterday's" day pillar, others in "tomorrow's". If you don't pick, your charts disagree with professional reference tools.
3. **No parity baseline.** You compute a chart locally, compare against a paid service, get different numbers, and have no way to tell who's right.
4. **Raw data only, no multilingual context.** Output is Chinese-centric, hard to wire into JP/KR/EN AI assistants.

`shunshi-bazi-core` + `shunshi-bazi-mcp` fix all four:

- ✅ **True solar time built-in**, default on (just pass `city` or `longitude/latitude`).
- ✅ **Default `sect=1`** (23:00 = tomorrow's day pillar), matching [问真八字](https://www.buyaolian.cn/).
- ✅ **Parity-tested** against Shunshi.AI's Python backend (5/5 golden cases) **and** `cantian-tymext`'s `calculateRelation()` (5/5 on 刑冲合会 pair-wise subset).
- ✅ **Multilingual discoverability** via keywords (bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei) so JP/KR/EN developers can find the package.

---

## Quick start

### If you're embedding Bazi calc in your own app

```bash
npm install shunshi-bazi-core
```

```typescript
import { getBaziChart } from 'shunshi-bazi-core';

const chart = getBaziChart({
  year: 1990, month: 3, day: 24, hour: 10, minute: 28,
  gender: 1,           // 0 = 女, 1 = 男
  city: '广州',         // triggers true solar time correction
});

console.log(chart.八字.四柱);          // "庚午 己卯 戊子 丁巳"
console.log(chart.真太阳时?.修正分钟); // -33.85 (minutes of correction applied)
```

→ Full API and output reference: [`packages/bazi-core/README.md`](./packages/bazi-core/README.md)

### If you want Claude / Cursor / Cline to compute Bazi charts

Add this to your MCP config (e.g. `claude_desktop_config.json`):

```jsonc
{
  "mcpServers": {
    "shunshi-bazi": {
      "command": "npx",
      "args": ["-y", "shunshi-bazi-mcp"]
    }
  }
}
```

Then restart the client and ask your AI agent in natural language:

> *"帮我算一下 1990 年 3 月 24 日 上午 10 点 28 分出生在广州的男生的八字。"*

The server exposes two tools:

- **`getBaziChart`** — full Bazi (Four Pillars) chart with true-solar-time correction, 大运, 刑冲合会, 神煞.
- **`getHuangli`** — 黄历 (老黄历 / Chinese almanac) for any day: 宜/忌, 彭祖百忌, 神煞, 建除, 二十八宿, 吉神方位, 12 时辰宜忌. Accepts 公历 or 农历 input; omit the date for today.

> *"今天的黄历宜忌是什么？"*

→ Full MCP tool docs, alternate client configs, troubleshooting: [`packages/bazi-mcp/README.md`](./packages/bazi-mcp/README.md)

---

## Repository layout

```
bazi-reader-mcp/
├── package.json                 # npm workspace root (private)
├── tsconfig.base.json           # shared TypeScript config
├── LICENSE                      # MIT
├── README.md                    # you are here
└── packages/
    ├── bazi-core/               # → publishes as "shunshi-bazi-core"
    │   ├── src/
    │   │   ├── index.ts
    │   │   └── lib/{bazi,relations,shensha,solarTime,cityCache}.ts
    │   ├── tests/{parity,relations-vs-cantian,smoke}.ts
    │   ├── package.json
    │   └── README.md
    └── bazi-mcp/                # → publishes as "shunshi-bazi-mcp"
        ├── src/{mcp,stdio}.ts
        ├── tests/smoke-stdio.ts
        ├── package.json
        └── README.md
```

---

## Development

```bash
# install deps for both packages
npm install

# build both packages
npm run build

# run bazi-core tests (parity + relations-vs-cantian)
npm test

# run the MCP server locally via tsx (no build required)
npm run dev:mcp

# stdio smoke test for the MCP (spawns the built dist/stdio.js)
cd packages/bazi-mcp && npm run smoke
```

### Test coverage

- **`packages/bazi-core/tests/parity.test.ts`** — 5 golden cases hand-labeled from screenshots of [问真八字](https://www.buyaolian.cn/), cross-checked against Shunshi.AI's Python backend on 四柱 / 十神 / 空亡 / 纳音 / 藏干.
- **`packages/bazi-core/tests/relations-vs-cantian.test.ts`** — 5/5 match vs `cantian-tymext`'s `calculateRelation()` on 刑冲合会 (pair-wise subset: 合 / 冲 / 刑 / 害 / 破 / 克).
- **`packages/bazi-mcp/tests/smoke-stdio.ts`** — End-to-end stdio handshake + `tools/list` + `tools/call`, asserts the real `四柱` output and the `数据来源` attribution block. Uses the real MCP SDK client so it exercises the exact same code path as Claude Desktop.

---

## Related projects

- **[`tyme4ts`](https://github.com/6tail/tyme4ts)** by 6tail — the TypeScript lunar/solar calendar primitives this library builds on.
- **[`cantian-ai/bazi-mcp`](https://github.com/cantian-ai/bazi-mcp)** — pioneering open-source Bazi MCP. We use their `cantian-tymext` as a dev dependency for relations parity testing. The two MCPs are **complementary, not competing** — we made different defaults (sect=1, true solar time on by default) based on what matches professional practice in the Chinese-speaking world.

---

## About Shunshi.AI

🌐 **Website**: [https://shunshi.ai](https://shunshi.ai)
🐦 **X / Twitter**: [@shunshiai2026](https://x.com/shunshiai2026)
🚀 **Product Hunt**: [Shunshi.AI](https://www.producthunt.com/products/shunshi-ai)

[Shunshi.AI (顺时)](https://shunshi.ai) is an AI-powered Bazi reading platform supporting English, 中文, 日本語, and 한국어. Free to try, no credit card required.

We open-sourced the calculation engine behind our production backend so:
- Any developer can compute Bazi charts with the same accuracy as our paid product.
- The 真太阳时 / 子时 edge cases get solved once and for all, instead of each project getting them wrong in a slightly different way.
- JP/KR/EN developers finally have a TypeScript library that speaks their terminology (四柱推命 / 사주팔자).

---

## License

[MIT](LICENSE) © 2026 [Shunshi.AI](https://shunshi.ai)