shunshi-ai/bazi-reader-mcp

> 🇨🇳 **中国八字 (Four Pillars of Destiny)** ・ 🇯🇵 **四柱推命 (しちゅうすいめい)** ・ 🇰🇷 **사주팔자 (四柱八字)**
>
> The calculation engine (and MCP server) behind Shunshi.AI / 顺时, open-sourced.
> 🇯🇵 **日本の開発者の方へ**: これは中国の「八字 (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** | Pure TypeScript calculation library. Zero framework deps. Use it from any Node.js / browser app. | npm install shunshi-bazi-core |
| **shunshi-bazi-mcp** | Thin Model Context Protocol 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'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 问真八字.
- ✅ **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
→ Full API and output reference: 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):
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.