I built a BaZi/flying-star API where every answer is replayable (SHA-256)

#mcp #api #showdev #opensource

The problem: three tools, three answers.

Ask three online BaZi calculators for the same January birth date and you can get three different year pillars. It's not a bug in any one of them, necessarily — the tradition genuinely carries multiple conventions: the year flips at the exact Lichun instant in BaZi practice, at Chinese New Year in folk practice, and at January 1 in naive software. Most tools pick one convention silently. That's the thing we wanted to fix (our dispute register lists the cases).

What we built

Fengshui Calculator is a calculation engine for traditional Chinese calendrics — BaZi four pillars, Xuan Kong flying-star charts, Ming Gua / Kua numbers, the 24 solar terms, almanac officers, date selection — with two properties that are unusual in this space:

Every response carries provenance: engine version, ruleset id, and a SHA-256 input_digest computed over the JCS-canonicalised request. Any result can be replayed byte-for-byte (fingerprint format docs).
Conventions are returned side by side. /v1/ganzhi returns all four year-convention × day-boundary combinations rather than guessing which one you meant. Disagreements are labeled, never merged.

The same kernel runs three places: the browser (WebAssembly, zero network), the REST API, and a native MCP endpoint. We cross-check calendar output against the Hong Kong Observatory for 1901–2100, plus four open-source reference implementations across ~290,000 samples — every divergence is attributed in the public accuracy report.

Try it in 60 seconds (no key, no signup)

# Chinese almanac for a day — lunar date, day officer, yellow/black path, six officers
curl "https://fengshuicalculator.com/v1/calendar?date=2026-10-21"

# Four pillars, four conventions side by side
curl "https://fengshuicalculator.com/v1/ganzhi?date=1985-02-20&hour=14"

# Kua number with the exact Lichun instant applied
curl "https://fengshuicalculator.com/v1/kua?date=1990-07-01&gender=male"

# Flying-star chart (Period 9, Zi-shan Wu-xiang)
curl "https://fengshuicalculator.com/v1/flying-star?yun=9&sitting=子&kind=xiagua"

Every response includes provenance.engine_version, provenance.ruleset_id, and provenance.input_digest. To verify a response later, POST the same request to /v1/replay with the digest: you get MATCH or an honest MISMATCH (API reference).

The MCP endpoint (agents)

If your agent speaks MCP, point it at https://fengshuicalculator.com/v1/mcp (streamable HTTP, stateless, no auth). Ten tools: calendar, ganzhi, solar_terms, kua_number, flying_star_chart, yun_period, rulesets, form_analysis, terrain_white_tiger, replay. It's also listed in the official MCP Registry as com.fengshuicalculator/fengshui-calculator.

claude mcp add --transport http fengshui https://fengshuicalculator.com/v1/mcp

Design decisions you might argue with

We refuse to guess. Day/hour purple-white stars have materially different starting rules across the literature, so the engine returns an explicit "not closed" error instead of picking a formula. Fewer numbers, no invented ones. The rule provenance register lists every rule with its classical source — including texts whose attribution the Siku cataloguers doubted; those are flagged, not laundered.

We don't do predictions. No fortune verdicts, no "lucky direction" scores, no guarantees. The engine computes markers the tradition defines (a day officer, a flying-star chart, a Kua number); turning those into advice is a different product, and a legally different one in many jurisdictions.

Citations are provenance, not endorsement. A rule cites the text it descends from (rule_id → text → juan), exactly as our text register assesses that text's attribution status.

What it's for

Builders of astrology/metaphysics apps who don't want to re-verify a lunar calendar
AI agents that need deterministic calendar maths with a replayable audit trail
Practitioners who need batch charts and reproducible case records (there's a workbench with an offline license key)

The free tier is a permanent charter: the calculators, the almanac, and the free API tier don't shrink. Pro ($4.99 day pass / $19 month) adds workflow — batch charts, exports — not "more accurate numbers" (pricing).

DEV Community