@finntang/bazi-core · @finntang/bazi-mcp

A deterministic, LLM-free BaZi (八字) computation engine for MCP and Node. It computes charts. It does not interpret them and it does not predict events.

What this is

A deterministic Four Pillars (八字 / BaZi) computation library and MCP server. Given a birth date, time, and location, it computes the four 干支 pillars, hidden stems, ten gods (十神), 納音, 旬空, typed branch relations (六合/三合/半合/六沖/相刑/相害/相破), true solar time, and the 大運 (decade luck-cycle) schedule — all under a stated traditional ruleset.

Scope of 0.x: structural computation only, matching the open surface of the incumbent open-source BaZi packages. No strength model, no 身強弱, no 用神, no 喜忌, no scores, no calibration weights.

What this is NOT

• Not a predictor. This package computes a traditional system faithfully; it does not claim the system predicts life events.
• Not an interpreter. It produces structural output; it does not narrate, advise, or generate commentary. That lives at finntang.com.
• Not a fortune-telling tool. It is a calculator.

Relationship to finntang.com

finntang.com is the hosted product from the same author. This package and that product share a calendar and a structural ruleset, and that is where the overlap ends.

The hosted product runs a different model that is not in this package — including a day-master strength model (身強弱), a 用神 / 喜忌 derivation, and interpretation. The difference between this package and the hosted product is not "untuned vs tuned." It is present vs absent: the hosted model's strength and favourable-element layers do not exist in any form in this repository, at any weight setting. Running this package does not reproduce a finntang.com reading at a lower quality; it produces a different kind of output (structure only).

The hosted strength layer is not a fixed parameter. It is re-calibrated against an open outcome cohort, so its weights change over time as evidence accumulates. This package is pinned at its published structural scope and does not receive those updates.

Accuracy and epistemics

There is no controlled evidence that BaZi — or any divination system — predicts life events above chance. The landmark double-blind test (Carlson, Nature, 1985) found astrologers performing at chance. This package computes a traditional system faithfully; that is a different claim from the system being predictive. No wording anywhere in this repository implies accuracy.

finntang.com runs an open validation cohort to measure this directly — including the misses. When that cohort produces a measured_at_chance result (an empirical confidence value measured at chance), the result will be published in this repository as a finding. The strength model that generated it stays in the hosted product — see "Relationship to finntang.com" above.

Install

npm install @finntang/bazi-mcp
# or, for library use without MCP:
npm install @finntang/bazi-core

Claude Desktop / Cursor config

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "finntang-bazi": {
      "command": "npx",
      "args": ["@finntang/bazi-mcp"]
    }
  }
}

The server runs over stdio by default (loopback, no network). For HTTP, run npx @finntang/bazi-mcp --http — it binds to 127.0.0.1:3000 by default.

Tools

| Tool | Computes | Weights | |------|----------|---------| | bazi_chart | Four pillars, hidden stems, ten gods, 納音, 旬空 (reported, not scored), branch relations, true solar time | n/a (none) | | dayun_schedule | 起運 age, cycle direction, up to 12 decade periods with ten-gods | n/a (none) |

Uncertainty handling

Unlike most libraries, this package surfaces uncertainty rather than compressing it into false precision:

• Boundary warnings: births near a 節氣 boundary (±30 min) emit a solar_term_boundary warning with the alternative chart.
• 晚子時 (23:00–23:59): day-pillar attribution depends on convention; both are shown.
• Unknown hour: birth_time: null is a first-class input — the hour pillar is omitted, no default is substituted.
• Historical timezone: irregular periods (HK wartime GMT+9, pre-1904 LMT) are detected and reported.

Ruleset and conventions

This package declares its conventions in RULESET.md. BaZi schools disagree more than they agree; without a declared ruleset, every "you calculated it wrong" report is a school difference, not a bug. Our defaults are documented, and each convention is (or will be) a runtime flag.

Historical time handling

This package handles historical timezone irregularities correctly because it relies on the platform's IANA tzdata rather than hand-rolled offset tables:

• Hong Kong wartime (1941–1945): GMT+9 (Tokyo time), detected and warned.
• Hong Kong DST (through 1979): multiple non-contiguous periods.
• China DST (1986–1991): one hour, mid-April to mid-September.
• Pre-1904 HK / pre-1949 CN: declared out of range for 0.x (LMT not applied).

The golden test suite verifies these cases. See the test/golden/ directory.

Privacy

This package stores nothing. The MCP server processes birth data in memory and discards it. Logs record only { tool, ok, duration_ms } — never the input payload. The logging helper's type signature physically cannot accept birth data (compiler-enforced, not discipline-enforced).

See PRIVACY.md.

Security defaults

• HTTP transport binds to 127.0.0.1 (loopback) by default.
• No CORS, ever — not even in examples.
• Bounded request body (64KB max).
• No input echo in error messages.

See SECURITY.md.

Contributing

Contributions are welcome via pull request with Signed-off-by (DCO, no CLA). See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.

Trademark notice: the license does NOT grant rights to the "finntang", "銘鏡", or project marks. Forks must not present themselves as this project.

About

This package is the open-source structural layer of finntang.com — classical Chinese metaphysics (BaZi) for self-reflection, by a named practitioner. The hosted side adds a separate, cohort-calibrated strength and interpretation model that is not contained in this repository; see "Relationship to finntang.com" above.