bazi-reader-mcp

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

Shunshi.AI / 顺时 の背後にある計算エンジン（およびMCPサーバー）のオープンソース版です。

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

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

このリポジトリは2つのnpmパッケージを含むモノレポです：

両パッケージとも、Shunshi.AI のプロダクションバックエンドを支える同一の計算エンジンを共有しており、リリースごとにパリティテスト（整合性テスト）が行われています。

開発の背景

既存のオープンソース八字ライブラリの多く（言語を問わず）には、以下の問題の少なくとも1つが存在します：

1. 真太陽時補正がない。 時計の時間をそのまま使用するため、標準時子午線から離れた場所（新疆 / 黒竜江 / 米国西海岸 / 北海道など）での出生では誤った命式になります。30分の誤差で時柱全体がずれてしまいます。

2. 子時の扱いが不整合。 23:00-23:59を「前日」の日柱とするライブラリもあれば、「翌日」とするものもあります。基準が明確でないと、専門的な参照ツールと命式が一致しません。

3. パリティ（整合性）の基準がない。 ローカルで計算して有料サービスと比較しても数値が異なり、どちらが正しいか判断できません。

4. 生データのみで、多言語コンテキストがない。 出力が中国語中心であり、日本語・韓国語・英語のAIアシスタントに組み込むのが困難です。

shunshi-bazi-core + shunshi-bazi-mcp はこれら4つの問題を解決します：

• ✅ 真太陽時補正を内蔵、デフォルトで有効（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 を使用しています。これら2つのMCPは競合するものではなく補完的な関係です。私たちは中国語圏の専門的な慣習に基づき、異なるデフォルト設定（sect=1、真太陽時デフォルト有効）を採用しました。

Shunshi.AI について

🌐 ウェブサイト: https://shunshi.ai 🐦 X / Twitter: @shunshiai2026 🚀 Product Hunt: Shunshi.AI

Shunshi.AI (顺时) は、英語、中文、日本語、한국어をサポートするAI駆動の八字鑑定プラットフォームです。無料で試用可能、クレジットカード不要。

私たちはプロダクションバックエンドの計算エンジンをオープンソース化しました。その理由は以下の通りです：

• 開発者が有料製品と同等の精度で八字を計算できるようにするため。

• 真太陽時 / 子時のエッジケースを、プロジェクトごとに異なる誤った方法で解決するのではなく、一度で正しく解決するため。

• 日本語・韓国語・英語のエンジニアが、自分たちの用語（四柱推命 / 사주팔자）で扱えるTypeScriptライブラリを利用できるようにするため。

ライセンス

MIT © 2026 Shunshi.AI