bazi-reader-mcp

🇨🇳 中国八字 (Vier Säulen des Schicksals) ・ 🇯🇵 四柱推命 (Shichū Suimei) ・ 🇰🇷 사주팔자 (Saju Palja)

Die Berechnungs-Engine (und der MCP-Server) hinter Shunshi.AI / 顺时, als Open Source verfügbar.

🇯🇵 An japanische Entwickler: Dies ist die Berechnungs-Engine + MCP-Server für das chinesische „八字 (bāzì)“ — in Japan als 四柱推命 (Shichū Suimei) bekannt. Sie können die vier Säulen / Zehn Götter / Da-Yun / Fünf-Elemente-Balance basierend auf Geburtsdatum, Geburtszeit und Geburtsort berechnen. Die Korrektur der wahren Sonnenzeit (Zeitgleichung) wird ebenfalls unterstützt und kann direkt von KI-Agenten (Claude / Cursor / Cline usw.) aufgerufen werden.

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

Dieses Repository ist ein Monorepo mit zwei veröffentlichten npm-Paketen:

Beide Pakete teilen sich die gleiche Berechnungs-Engine, die das Produktions-Backend von Shunshi.AI antreibt. Beide werden bei jedem Release auf Parität getestet.

Warum existiert dieses Projekt?

Die meisten existierenden Open-Source-Bazi-Bibliotheken (in jeder Sprache) haben mindestens eines dieser Probleme:

1. Keine Korrektur der wahren Sonnenzeit. Die Uhrzeit wird unverändert verwendet, was bei Geburten weit entfernt vom Standardmeridian der Zeitzone (Xinjiang / Heilongjiang / US-Westküste / Hokkaido) zu falschen Diagrammen führt. Ein Fehler von 30 Minuten verschiebt die gesamte Stundensäule.

2. Inkonsistente Handhabung von 子时 (Zi-Zeit). Einige Bibliotheken ordnen 23:00-23:59 der Tagessäule von „gestern“ zu, andere der von „morgen“. Wenn man sich nicht festlegt, stimmen die Diagramme nicht mit professionellen Referenztools überein.

3. Keine Paritäts-Baseline. Man berechnet ein Diagramm lokal, vergleicht es mit einem kostenpflichtigen Dienst, erhält unterschiedliche Zahlen und hat keine Möglichkeit festzustellen, wer recht hat.

4. Nur Rohdaten, kein mehrsprachiger Kontext. Die Ausgabe ist auf Chinesisch zentriert und schwer in japanische/koreanische/englische KI-Assistenten zu integrieren.

shunshi-bazi-core + shunshi-bazi-mcp beheben alle vier Probleme:

• ✅ Wahre Sonnenzeit integriert, standardmäßig aktiviert (einfach city oder longitude/latitude übergeben).

• ✅ Standard sect=1 (23:00 = Tagessäule von morgen), passend zu 问真八字.

• ✅ Paritätsgetestet gegen das Python-Backend von Shunshi.AI (5/5 Gold-Fälle) und calculateRelation() von cantian-tymext (5/5 bei der paarweisen Teilmenge von 刑冲合会).

• ✅ Mehrsprachige Auffindbarkeit über Schlüsselwörter (bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei), damit JP/KR/EN-Entwickler das Paket finden können.

Schnellstart

Wenn Sie die Bazi-Berechnung in Ihre eigene App einbetten

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)

→ Vollständige API- und Ausgabereferenz: packages/bazi-core/README.md

Wenn Sie möchten, dass Claude / Cursor / Cline Bazi-Diagramme berechnet

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (z. B. claude_desktop_config.json):

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

Starten Sie dann den Client neu und fragen Sie Ihren KI-Agenten in natürlicher Sprache:

"Berechne mir das Bazi für einen Jungen, der am 24. März 1990 um 10:28 Uhr in Guangzhou geboren wurde."

→ Vollständige MCP-Tool-Dokumentation, alternative Client-Konfigurationen, Fehlerbehebung: packages/bazi-mcp/README.md

Repository-Struktur

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

Entwicklung

# 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

Testabdeckung

• packages/bazi-core/tests/parity.test.ts — 5 Gold-Fälle, manuell beschriftet anhand von Screenshots von 问真八字, gegengeprüft mit dem Python-Backend von Shunshi.AI bezüglich 四柱 / 十神 / 空亡 / 纳音 / 藏干.

• packages/bazi-core/tests/relations-vs-cantian.test.ts — 5/5 Übereinstimmung mit calculateRelation() von cantian-tymext bei 刑冲合会 (paarweise Teilmenge: 合 / 冲 / 刑 / 害 / 破 / 克).

• packages/bazi-mcp/tests/smoke-stdio.ts — End-to-End-stdio-Handshake + tools/list + tools/call, bestätigt die echte 四柱-Ausgabe und den 数据来源-Attributionsblock. Verwendet den echten MCP-SDK-Client, sodass derselbe Codepfad wie bei Claude Desktop ausgeführt wird.

Verwandte Projekte

• tyme4ts von 6tail — die TypeScript-Grundlagen für den Mond-/Sonnenkalender, auf denen diese Bibliothek aufbaut.

• cantian-ai/bazi-mcp — wegweisendes Open-Source-Bazi-MCP. Wir verwenden deren cantian-tymext als Entwicklungsabhängigkeit für den Test der Relations-Parität. Die beiden MCPs sind komplementär, nicht konkurrierend — wir haben unterschiedliche Standardeinstellungen (sect=1, wahre Sonnenzeit standardmäßig an) basierend darauf gewählt, was der professionellen Praxis in der chinesischsprachigen Welt entspricht.

Über Shunshi.AI

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

Shunshi.AI (顺时) ist eine KI-gestützte Bazi-Leseplattform, die Englisch, 中文, 日本語 und 한국어 unterstützt. Kostenlos zum Ausprobieren, keine Kreditkarte erforderlich.

Wir haben die Berechnungs-Engine hinter unserem Produktions-Backend als Open Source veröffentlicht, damit:

• Jeder Entwickler Bazi-Diagramme mit der gleichen Genauigkeit wie unser kostenpflichtiges Produkt berechnen kann.

• Die Grenzfälle 真太阳时 / 子时 ein für alle Mal gelöst werden, anstatt dass jedes Projekt sie auf leicht unterschiedliche Weise falsch macht.

• JP/KR/EN-Entwickler endlich eine TypeScript-Bibliothek haben, die ihre Terminologie spricht (四柱推命 / 사주팔자).

Lizenz

MIT © 2026 Shunshi.AI