DEV Community

Cover image for I Open-Sourced a Chinese Astrology Engine and Wired It Into Every AI Coding Tool
Shunshi Peter
Shunshi Peter

Posted on

I Open-Sourced a Chinese Astrology Engine and Wired It Into Every AI Coding Tool

#ai #mcp #opensource #typescript

TL;DR: I built shunshi-bazi-core — a TypeScript library that calculates Chinese Four Pillars of Destiny (八字 / 四柱推命 / 사주팔자) charts with true solar time correction. Then I wrapped it as an MCP server for Claude Desktop / Cursor / Cline, and a Claude Code skill for the CLI. Everything is MIT-licensed.

What is Bazi?

Bazi (八字, literally "eight characters") is a system from Chinese metaphysics that maps a person's birth date and time into a chart of heavenly stems and earthly branches. Think of it as the Chinese equivalent of a natal chart in Western astrology — except it operates on a completely different calendar system (the sexagenary cycle) and has its own analytical framework involving Ten Gods (十神), Five Elements (五行), and Dayun (大运, ten-year fate periods).

It's known as 四柱推命 (Shichū Suimei) in Japan and 사주팔자 (Saju Palja) in Korea. Hundreds of millions of people across East Asia consult Bazi readings — it's one of the most widely practiced forms of divination in the world.

The Problem: Why Existing Libraries Fall Short

When I started building Shunshi.AI (an AI-powered Bazi reading platform), I surveyed every open-source Bazi library I could find in JavaScript, Python, and TypeScript. They all had at least one of these issues:

1. No True Solar Time Correction

This is the big one. Bazi charts are based on solar time, not clock time. If you're born in Urumqi (western China, UTC+8) at 14:00 clock time, your actual solar time is closer to 12:00 — a two-hour difference that shifts the entire hour pillar and changes the reading completely.

Most libraries just take the clock time as-is. This gives wrong charts for anyone born far from their timezone's standard meridian: western China, Hokkaido, the U.S. West Coast, Western Europe...

2. The Midnight Problem (子時分日)

What happens when someone is born at 23:30? Is that "today" or "tomorrow" in Bazi terms?

Different schools disagree (早子時 vs 晚子時). Most libraries don't even let you choose — they silently pick one convention, and you discover the discrepancy only when your chart disagrees with a professional practitioner's.

3. No Parity Baseline

You compute a chart, compare it against a paid service, get different answers. Who's right? Without golden test cases against authoritative reference tools, there's no way to know.

The Solution: shunshi-bazi-core

I extracted the calculation engine from Shunshi.AI's production backend and published it as a standalone TypeScript library:

npm install shunshi-bazi-core
Enter fullscreen mode Exit fullscreen mode 
import { getBaziChart } from 'shunshi-bazi-core';

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

console.log(chart.八字.四柱);          // "庚午 己卯 戊子 丁巳"
console.log(chart.真太阳时?.修正分钟); // -33.85 (minutes corrected)
Enter fullscreen mode Exit fullscreen mode

What you get back:

  • Four Pillars with heavenly stems, earthly branches, and hidden stems
  • Ten Gods (十神) for each pillar
  • Five Element scores with percentages
  • 40+ Shensha (神煞, special stars) per pillar
  • Dayun (大运, ten-year fate periods) with the current period marked
  • Nayin (纳音), Kongwang (空亡), and Xing-Chong-He-Hui (刑冲合会)
  • True solar time correction — just pass a city name or longitude/latitude

The library is parity-tested against both Shunshi.AI's Python backend and cantian-tymext's relation calculations on 5 golden cases covering edge cases like 23:48 births and spring festival boundaries.

Wiring It Into AI Tools

A calculation engine is useful, but the real magic happens when AI agents can call it. I built three integration layers:

Layer 1: MCP Server (Claude Desktop / Cursor / Cline) 

npx -y shunshi-bazi-mcp
Enter fullscreen mode Exit fullscreen mode

Add this to your Claude Desktop config:

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

Now you can ask Claude in natural language:

"Calculate the Bazi chart for someone born on March 24, 1990 at 10:28 AM in Guangzhou, male."

Claude calls the MCP tool, gets the full chart JSON, and gives you a professional-grade reading — complete with Ten Gods analysis, Five Element balance, and Dayun forecast.

Layer 2: Claude Code Skill (ClawHub)

For Claude Code (Anthropic's CLI), I published a skill on ClawHub:

/bazi 1993-08-18 14:30 male Guangzhou
Enter fullscreen mode Exit fullscreen mode

The skill handles everything:

  1. Parses the birth info from natural language (supports Chinese, English, Japanese, Korean)
  2. Calls the calculation engine with true solar time correction
  3. Outputs a structured reading with tables, analysis, and actionable advice
  4. Offers follow-up options: yearly forecast, career advice, compatibility analysis

It passed ClawHub's security scan with Benign (HIGH CONFIDENCE) from both VirusTotal and OpenClaw — no runtime npm install, no undeclared dependencies, no credential requests.

Layer 3: Direct Library Usage

If you're building your own Bazi app, just use the core library directly. It's pure TypeScript with zero framework dependencies — works in Node.js and browsers.

Architecture 

shunshi-bazi-core          (npm library — pure calculation)
    ↓
shunshi-bazi-mcp           (MCP server — wraps core for AI agents)
    ↓
Claude Code Skill          (ClawHub — /bazi slash command)
    ↓
Shunshi.AI                 (Production app — full reading platform)
Enter fullscreen mode Exit fullscreen mode

All four layers share the exact same calculation engine. A fix in shunshi-bazi-core propagates to every integration point.

Comparison with Other Bazi MCPs

cantian-bazi shunshi-bazi
True solar time Clock time only Built-in, default on
子時 default sect=2 (23:00 = today) sect=1 (23:00 = tomorrow)
Shensha (神煞) Partial 40+ per chart
Dayun fields Partial 15 fields per decade
Parity-tested — vs production backend + cantian

The two projects are complementary, not competing. We chose different defaults based on what matches different schools of professional Bazi practice.

What I Learned

1. True Solar Time Is Non-Negotiable

I wasted weeks debugging charts that were "almost right" before realizing the hour pillar was wrong because I was using clock time. The Equation of Time correction (accounting for Earth's orbital eccentricity and axial tilt) can shift times by up to 30 minutes. For Bazi, where each "hour" is a 2-hour window, this regularly changes the chart.

2. Security Scanning for AI Skills Is Real

ClawHub's OpenClaw scanner flagged my first skill as "Suspicious" because it ran npm install at runtime. Fair enough — a skill that downloads arbitrary packages at execution time is a legitimate security concern. I restructured to declare dependencies in package.json with a proper install step, and it passed with HIGH CONFIDENCE.

3. The MCP Ecosystem Is Growing Fast

When I started, there were maybe 2-3 Bazi-related MCPs. Now there are several, each with different strengths. The Model Context Protocol is becoming the standard way to give AI agents domain-specific capabilities, and the tooling (ClawHub for skills, MCP registries) is maturing quickly.

4. Multilingual SEO Matters for Niche Libraries

Bazi is searched for as 八字 (Chinese), 四柱推命 (Japanese), 사주팔자 (Korean), and "Four Pillars" (English). By including all four in my package description and README, I get discovered by developers across all four language communities.

Try It

Everything is MIT-licensed. PRs welcome.

I'm building Shunshi.AI — an AI-powered Bazi reading platform supporting English, Chinese, Japanese, and Korean. If you're interested in Chinese metaphysics, AI tool integration, or multilingual TypeScript libraries, follow me here or on X.

Top comments (0)