bazi-reader-mcp

🇨🇳 中国八字 (Four Pillars of Destiny) ・ 🇯🇵 四柱推命 (しちゅうすいめい) ・ 🇰🇷 사주팔자 (四柱八字)

Shunshi.AI / 顺时背后的计算引擎（及 MCP 服务器），现已开源。

🇯🇵 日本の開発者の方へ: これは中国の「八字 (bāzì)」— 日本で言う 四柱推命 の計算エンジン + MCP サーバーです。生年月日・出生時刻・出生地から四柱 / 十神 / 大運 / 五行バランスを計算できます。真太陽時（均時差）補正にも対応しており、AI エージェント (Claude / Cursor / Cline など) から直接呼び出せます。

🇰🇷 한국 개발자분들께: 중국의 "八字 (bāzì)" — 한국에서는 사주팔자라고 부르는 명리학의 계산 엔진 + MCP 서버입니다. 생년월일·출생시각·출생지로부터 사주 / 십성 / 대운 / 오행 균형을 계산합니다. 진태양시 보정도 지원하며, AI 에이전트 (Claude / Cursor / Cline 등) 에서 바로 사용할 수 있습니다.

本仓库是一个包含两个已发布 npm 包的 monorepo：

两个包共享 Shunshi.AI 生产环境后端所使用的相同计算引擎。且在每次发布时都会进行对齐测试。

为什么会有这个项目

大多数现有的开源八字库（无论何种语言）通常存在以下至少一个问题：

1. 没有真太阳时校准。 直接使用钟表时间，导致出生地远离时区标准经度（如新疆 / 黑龙江 / 美国西海岸 / 北海道）时排盘错误。30 分钟的误差足以改变整个时柱。

2. 子时处理不一致。 有些库将 23:00-23:59 归入“昨天”的日柱，有些则归入“明天”。如果不明确选择，排出的盘将与专业参考工具不符。

3. 缺乏对齐基准。 本地计算出的盘与付费服务对比，结果不同，却无法判断谁是正确的。

4. 仅有原始数据，缺乏多语言上下文。 输出以中文为中心，难以集成到日/韩/英 AI 助手工具中。

shunshi-bazi-core + shunshi-bazi-mcp 解决了上述所有四个问题：

• ✅ 内置真太阳时校准，默认开启（只需传入 city 或 longitude/latitude）。

• ✅ 默认 sect=1（23:00 为次日日柱），与问真八字保持一致。

• ✅ 对齐测试：与 Shunshi.AI 的 Python 后端（5/5 金标准案例）以及 cantian-tymext 的 calculateRelation()（在刑冲合会两两子集上 5/5 匹配）进行了对齐测试。

• ✅ 多语言可发现性：通过关键词（bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei）优化，方便日/韩/英开发者找到该包。

快速开始

如果你想在自己的应用中嵌入八字计算

npm install shunshi-bazi-core

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)

→ 完整的 API 和输出参考：packages/bazi-core/README.md

如果你想让 Claude / Cursor / Cline 计算八字盘

将以下内容添加到你的 MCP 配置文件中（例如 claude_desktop_config.json）：

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

然后重启客户端，并用自然语言询问你的 AI 助手：

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

→ 完整的 MCP 工具文档、其他客户端配置、故障排除：packages/bazi-mcp/README.md

仓库结构

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

开发

# 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

测试覆盖率

• packages/bazi-core/tests/parity.test.ts — 5 个从问真八字截图手动标注的金标准案例，在四柱 / 十神 / 空亡 / 纳音 / 藏干方面与 Shunshi.AI 的 Python 后端进行了交叉验证。

• packages/bazi-core/tests/relations-vs-cantian.test.ts — 在刑冲合会（两两子集：合 / 冲 / 刑 / 害 / 破 / 克）方面与 cantian-tymext 的 calculateRelation() 5/5 匹配。

• packages/bazi-mcp/tests/smoke-stdio.ts — 端到端 stdio 握手 + tools/list + tools/call，验证真实的 四柱 输出和 数据来源 归属块。使用真实的 MCP SDK 客户端，因此执行路径与 Claude Desktop 完全一致。

相关项目

• tyme4ts by 6tail — 本库所基于的 TypeScript 农历/公历基础库。

• cantian-ai/bazi-mcp — 开源八字 MCP 的先行者。我们将其 cantian-tymext 作为关系对齐测试的开发依赖。这两个 MCP 是互补而非竞争关系——我们基于符合华人世界专业实践的原则，设定了不同的默认值（sect=1，默认开启真太阳时）。

关于 Shunshi.AI

🌐 网站: https://shunshi.ai 🐦 X / Twitter: @shunshiai2026 🚀 Product Hunt: Shunshi.AI

Shunshi.AI (顺时) 是一个支持英语、中文、日本語和 한국어 的 AI 八字排盘平台。免费试用，无需信用卡。

我们开源了生产环境后端背后的计算引擎，以便：

• 任何开发者都能以与我们付费产品相同的精度计算八字。

• 真太阳时 / 子时边界情况得到彻底解决，而不是每个项目都以略有不同的方式出错。

• 日/韩/英开发者终于拥有了一个使用他们术语（四柱推命 / 사주팔자）的 TypeScript 库。

许可证

MIT © 2026 Shunshi.AI