Why an MCP server for fortune-telling?

I'm not joking. Hear me out.

The Chinese divination corpus is deterministic computation dressed up as mysticism. BaZi (八字) is a date conversion problem — given a Gregorian datetime, derive the four ganzhi pillars considering solar terms, true solar time, and timezone offsets. ZiWei (紫微斗数) takes those four pillars and runs a 12-palace placement algorithm with three layers of star transformations. None of this is "AI-able" — LLMs hallucinate the day pillar when crossing midnight, mix up shen-sha (神煞) names, and silently apply the wrong solar-term cutoff. Every engineer who has tried to put BaZi inside a system prompt has felt this pain.

So I built it the boring way: 7 FastAPI endpoints with rule-based engines under each route, exposed via MCP for agents and via x402 for monetization.

The 7 endpoints

The first 3 calls per unique UA are free, so you can play without paying.

Why x402 is the right fit

Traditional API gateways assume:

• A monthly subscription tier
• A signup + KYC flow
• An API key to provision

For an MCP server consumed by an autonomous agent, none of that fits. The agent doesn't have a credit card, doesn't want a 2-week free trial, and may need to call this once a quarter when a user asks about a specific date.

x402 (Coinbase's payment-required HTTP standard, USDC-on-Base) gives you a per-call, no-account, < $0.05 settlement primitive. The flow is:

1. Client → GET /bazi-matching?...
2. Server → 402 Payment Required + price + receiving address
3. Client → re-GET with X-PAYMENT header (signed USDC transfer)
4. Server → verifies on-chain → 200 with result

This whole dance is wrapped by the MCP TS SDK so the agent author doesn't see it — they just npx -y xuanxue-bazi-matching and provide an XUANXUE_PAYMENT_TOKEN env var.

Engineering edge cases (this is where I learned the most)

1. The day-pillar boundary

BaZi day pillars roll over at 23:00 local true solar time, not midnight. If a client says "I was born at 23:30 on April 15" and provides their longitude, the engine has to:

1. Compute true solar time offset (equation of time + longitude correction)
2. Decide whether 23:30 is "late April 15" or "early April 16 子时"
3. Pick the right day pillar accordingly

Get this wrong by 30 minutes and the entire chart shifts. We solved it by computing TST upfront and having a single canonical effective_datetime propagate through all 4 pillar derivations.

2. Solar terms (节气)

The boundary for the month pillar is not the Gregorian month, but the 24 solar terms (立春, 雨水, 惊蛰...). These cutoffs vary year to year by hours. We use the VSOP87 short-period truncation (8 harmonic terms) which is good to ~30 seconds of accuracy — overkill for divination but eliminates the "did the month change yet" question entirely.

3. Leap months in lunar calendar

Some BaZi schools want the lunar month even though the engine uses solar terms. We expose both and let the client pick. The MCP meihua-oracle endpoint specifically uses lunar month-day-hour for the upper/lower trigram derivation, so we needed a working lunar calendar regardless.

4. QiMen Yin/Yang escape (阴阳遁)

The Qi-Men Dun-Jia engine alternates between Yang escape (winter solstice → summer solstice) and Yin escape. There's a special exception during the 5-day "transition" near the solstices where some schools use the previous escape and some use the next. We implement the 拆补法 (chai-bu-fa) consistently — same school for the entire engine — to avoid silent regressions.

What's open vs. paid

• Calculation rules: open (the npm package contains the rule engines, MIT license)
• Aggregation, hosted endpoint, x402 settlement, MCP transport: paid

This split lets agent authors verify "no LLM in here" and even run their own instance for free if they want — the hosted version is just convenience + payment routing.

Try it

For agents:

npm install -g xuanxue-bazi-matching
# then in your Claude Desktop config:
{
  "mcpServers": {
    "xuanxue": {
      "command": "npx",
      "args": ["-y", "xuanxue-bazi-matching"]
    }
  }
}

For humans wanting a synthesized destiny report (~1000 words integrating all 6 systems): https://decodeyourming.com — $1.99 one-time.

What's next

• Open-sourcing more of the engines (currently the binary calculation tables are bundled but not auditable)
• More languages — currently zh-CN/zh-TW/en. Vietnamese and Korean asked for.
• Western astrology compatibility layer — common requests, but the natal-chart math is a different rabbit hole. PRs welcome if anyone has a deterministic Western engine.

If you're building an agent that touches dates, timing, or compatibility — this is a useful primitive. And if you find a calculation bug, please file an issue. I'd rather get a "your shensha is wrong" GitHub report than ship the wrong thing.

Repo: https://github.com/jasonwagao-bit/m2m
Docs: https://api.decodeyourming.com/docs/agents
NPM: https://www.npmjs.com/package/xuanxue-bazi-matching