Yuanzi Zhiyi Bazi Agent Kit MCP server

Yuanzi Bazi Agent Kit

Yuanzi Zhiyi website · 简体中文

A local-first, deterministic basic Four Pillars (Bazi) engine, CLI, MCP server, and Agent Skill by Yuanzi Zhiyi.

The calculation scope includes: calendar conversion, time-zone and true-solar-time handling, explicit day boundaries, four pillars, day master, ten gods, hidden stems, and unweighted five-element counts, composition shares, and a documented eight-shensha rule set. The stable result schema is yuanzi-basic-bazi/v1.

Chinese documentation

Topics / 主题： 八字排盘 · Bazi / Four Pillars · 真太阳时 / True Solar Time · 历法转换 / Calendar Conversion · MCP · Agent Skill · 本地命盘图片 / Local Chart Images

Example chart

Illustrative chart. Birth date, time and location are hidden; no customer data is used.

Why this kit exists

Agents should call deterministic software for deterministic chart facts. This kit gives OpenAI, Google, and other MCP-compatible agents the same reviewable calculation core without requiring users to upload identity data or send birth data to a hosted API.

Calculation is local, uses zero telemetry, and makes no network requests. See scope and privacy.

Included

Luck cycles, interpretation of shensha, compatibility, AI readings, reports, and advisor services are not part of the public core.

Install with npm

Version 0.3.0 includes the new chart layout, bundled fonts, and chart structure extension.

Requires Node.js 22.19 or later. Start the local MCP server:

npx -y yuanzi-bazi-agent-kit@0.3.0 mcp

MCP client configuration:

{
  "mcpServers": {
    "yuanzi-bazi": {
      "command": "npx",
      "args": ["-y", "yuanzi-bazi-agent-kit@0.3.0", "mcp"]
    }
  }
}

The first run downloads npm dependencies; chart calculation and image rendering then run locally.

Install from this source tree

Requires Node.js 22.19 or later.

git clone https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit.git
cd yuanzi-bazi-agent-kit
npm ci
npm run build
npm test
npm link

The source repository is yuanzizhiyi/yuanzi-bazi-agent-kit. The npm package is yuanzi-bazi-agent-kit, version 0.3.0.

Chart images

MCP calculatebasicbazi_chart returns structuredContent.chart, JSON text, readable facts, and an image/png content block. Clients that support MCP images can display the chart directly. The Skill also saves and displays a PNG by default.

For CLI usage, append --image chart.png to chart --stdin --format json. JSON stays on stdout; a save confirmation goes to stderr. Choose an unused filename in an existing directory. Images contain birth/chart data: share them deliberately. Rendering uses the same paper and pillar design language as the main site, without its advanced calculations. It runs locally with bundled Noto-derived serif and sans-serif fonts and no network calls. The 2160px-wide report includes the highlighted day column, full pillar table, shensha and combinations, directed element relationships and all ten composition bars. See chart structure and rules.

CLI

Shortened. The full README is on GitHub.