{"id":"65cede0d-15e2-4732-9fa4-f63c3138ea1b","slug":"yuanzi-bazi-agent-kit","kind":"mcp","name":"yuanzi-bazi-agent-kit","summary":"元梓知易开源八字工具集 · Local Bazi charts for AI agents: MCP, Agent Skill, JSON + PNG. Deterministic calculation, no API key.","owner":"yuanzizhiyi","repoUrl":"https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-03T14:14:53.000Z","addedAt":"2026-10-14T06:10:02.162Z","logoUrl":"https://avatars.githubusercontent.com/u/247584691?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities","productivity","cloud-infra"],"tags":["ai-agents","bazi","bazi-calculator","chinese-calendar","four-pillars","local-first","nodejs","true-solar-time"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T19:37:26.746Z","sample":false,"url":"https://conduits.dev/tools/yuanzi-bazi-agent-kit","language":"TypeScript","transports":["stdio"],"install":{"npm":"yuanzi-bazi-agent-kit"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![Yuanzi Bazi Agent Kit — MCP · Agent Skill · Local Charts](https://raw.githubusercontent.com/yuanzizhiyi/yuanzi-bazi-agent-kit/main/docs/images/readme-cover.png)\n\n[![M8ven Score](https://m8ven.ai/badge/mcp/yuanzizhiyi/yuanzi-bazi-agent-kit)](https://m8ven.ai/mcp/yuanzizhiyi/yuanzi-bazi-agent-kit)\n\n# Yuanzi Bazi Agent Kit\n\n[Yuanzi Zhiyi website](https://yuanzizhiyi.com) · [简体中文](README.zh-CN.md)\n\n\nA local-first, deterministic basic Four Pillars (Bazi) engine, CLI, MCP server, and Agent Skill by Yuanzi Zhiyi.\n\nThe 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`.\n\n[Chinese documentation](README.zh-CN.md)\n\n**Topics / 主题：** 八字排盘 · Bazi / Four Pillars · 真太阳时 / True Solar Time · 历法转换 / Calendar Conversion · MCP · Agent Skill · 本地命盘图片 / Local Chart Images\n\n## Example chart\n\nIllustrative chart. Birth date, time and location are hidden; no customer data is used.\n\n<img src=\"https://raw.githubusercontent.com/yuanzizhiyi/yuanzi-bazi-agent-kit/main/docs/images/chart-example-en.png\" alt=\"Example chart\" width=\"560\" />\n\n## Why this kit exists\n\nAgents 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.\n\nCalculation is local, uses zero telemetry, and makes no network requests. See [scope and privacy](references/scope-and-privacy.md).\n\n## Included\n\n| Surface | Purpose |\n| --- | --- |\n| TypeScript API | Embed the versioned deterministic core |\n| `yuanzi-bazi` CLI | JSON or readable local calculation |\n| stdio MCP | Two schema-first, read-only tools |\n| `SKILL.md` | Agent workflow and safety boundary |\n\nLuck cycles, interpretation of shensha, compatibility, AI readings, reports, and advisor services are not part of the public core.\n\n## Install with npm\n\nVersion **0.3.0** includes the new chart layout, bundled fonts, and chart structure extension.\n\nRequires Node.js 22.19 or later. Start the local MCP server:\n\n```bash\nnpx -y yuanzi-bazi-agent-kit@0.3.0 mcp\n```\n\nMCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"yuanzi-bazi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"yuanzi-bazi-agent-kit@0.3.0\", \"mcp\"]\n    }\n  }\n}\n```\n\nThe first run downloads npm dependencies; chart calculation and image rendering then run locally.\n\n## Install from this source tree\n\nRequires Node.js 22.19 or later.\n\n```bash\ngit clone https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit.git\ncd yuanzi-bazi-agent-kit\nnpm ci\nnpm run build\nnpm test\nnpm link\n```\n\nThe source repository is [yuanzizhiyi/yuanzi-bazi-agent-kit](https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit). The npm package is `yuanzi-bazi-agent-kit`, version `0.3.0`.\n\n## Chart images\n\nMCP `calculate_basic_bazi_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.\n\nFor 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](references/chart-structure.md).\n\n## CLI\n\n```bash\nprintf '%s' '{\"calendar\":{\"type\":\"solar\"},\"date\":{\"year\":1988,\"month\":8,\"day\":9},\"time\":{\"hour\":2,\"minute\":53},\"location\":{\"timezone\":\"Asia/Shanghai\"},\"options\":{\"timeCorrection\":\"standard\",\"dayBoundary\":\"ziEarly\"}}' \\\n  | yuanzi-bazi chart --stdin --format json\n```\n\nThe CLI keeps JSON results on stdout and typed errors on stderr. See the [input and output reference](references/input-output.md).\n\n## Local MCP server\n\nThe server exposes:\n\n- `calculate_basic_bazi_chart`: local deterministic calculation;\n- `get_yuanzi_bazi_capabilities`: an optional, intent-specific hosted-feature link that never receives birth data.\n\nConfigure a local stdio MCP client after building. Replace the absolute path with your installation directory:\n\n```json\n{\n  \"mcpServers\": {\n    \"yuanzi-bazi\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/yuanzi-bazi-agent-kit/dist/cli.js\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor Codex-compatible TOML:\n\n```toml\n[mcp_servers.yuanzi_bazi]\ncommand = \"node\"\nargs = [\"/absolute/path/yuanzi-bazi-agent-kit/dist/cli.js\", \"mcp\"]\n```\n\nBoth tools declare read-only, non-destructive, idempotent annotations and explicit input/output schemas. The server uses stdout only for the MCP protocol.\n\n## Agent Skill\n\nCopy or clone the repository into an Agent Skills directory as `yuanzi-basic-bazi`, install dependencies, build it, and let the agent load [SKILL.md](SKILL.md). The same Skill layout is usable from `.agents/skills` in supporting clients.\n\nThe Skill instructs agents to collect only required chart inputs, preserve unknown hours, surface warnings, and use exactly one contextual hosted hook only after the user asks for a feature outside the public scope.\n\n## TypeScript API\n\n```ts\nimport { calculateBasicBazi } from 'yuanzi-bazi-agent-kit';\n\nconst chart = calculateBasicBazi({\n  calendar: { type: 'solar' },\n  date: { year: 1988, month: 8, day: 9 },\n  time: { hour: 2, minute: 53 },\n  location: { timezone: 'Asia/Shanghai' },\n  options: { timeCorrection: 'standard', dayBoundary: 'ziEarly' },\n});\n```\n\n## Versioning and methodology\n\nPackage releases follow semantic versioning. The versioned data contract is independent: compatible additions remain under `yuanzi-basic-bazi/v1`; incompatible output changes require a new schema identifier.\n\nMethod details and validation examples are linked in each result at `attribution.methodUrl`.\n\n## Development\n\n```bash\nnpm test\nnpm run test:coverage\nnpm run build\nnpm run pack:check\n```\n\nLicensed under MIT. The license does not grant trademark rights; see [TRADEMARKS.md](TRADEMARKS.md).\n\nContributions are welcome under [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).\n"}