taibu: a TypeScript divination engine that exposes 15 MCP tools

What taibu actually computes, and who needs that

The repository is a divination calculator with an AI layer on top. Its README lists bazi (four pillars), ziwei doushu, liuyao, meihua yishu, qimen dunjia, da liuren, xiao liuren, Western astrology, taiyi, tarot, MBTI, face and palm reading, relationship compatibility and daily or monthly fortune. Each of those is a separate calculation system with its own inputs and its own output structure. Bazi alone is documented as covering true solar time, solar and lunar calendars, the ten stems and twelve branches, ten gods, hidden stems, nayin, 51 kinds of shensha, twelve stages of growth, and clash/combination/punishment relations, plus luck cycles down to the daily level.

The audience is narrower than the feature list suggests. Someone who wants a fortune reading has the hosted site at mingai.fun. The people who would clone this repository are developers who want the calculation output as structured data, either through the MCP server or through the taibu-core npm package. The README states that taibu-core lets you call the calculation engine directly from a Node.js project without speaking the MCP protocol at all. That is the real product boundary: a rules engine for calendar-based systems, wrapped in two delivery mechanisms.

What it does not claim to be is a validated predictive system. Nothing in the material offers accuracy figures, backtesting or comparison against practitioners. Treat the output as a deterministic transformation of birth data and query parameters into a structured chart, which is what the tool descriptions actually promise.

The MCP server is the part worth studying

Taibu ships a deployed public MCP server at https://mcp.mingai.fun/mcp. The README says the service was upgraded to MCP 2026-07-28 (released 2026-07-29 Beijing time) and remains compatible with stateless clients speaking the 2025 protocol. Configuration is a single JSON block with type streamable-http and the URL. The README states that newer clients perform server/discover automatically and generate per-request protocol metadata, so no OAuth, API key or session header is needed.

Fifteen tools are listed. They are not uniform wrappers. bazi returns a chart. bazi_pillars_resolve runs the reverse direction, taking four pillars and returning candidate birth times between 1900 and 2100. bazi_dayun computes ten-year luck cycles with annual detail, tai sui markers and minor cycles. ziwei, ziwei_horoscope and ziwei_flying_star split the natal chart, the time-based horoscope and the flying-star transformation analysis into three separate calls. liuyao, meihua, tarot, almanac, astrology, qimen, taiyi, daliuren and xiaoliuren each expose one system.

That split matters for agent design. A model that needs a full ziwei reading has to chain three tool calls and pass chart state between them, which the README implies the agent handles rather than the server. The parameter surface is also uneven: bazi accepts solar or lunar input, qimen and daliuren are documented as having explicit timezone support, and meihua accepts year-month-day-hour, object counts, sound counts, character divination, measurements and directional correspondences. There is no schema documentation in the material, so an integrator is reading tool descriptions rather than a typed contract.

Getting it running: Docker first, pnpm second

The README gives three Docker paths. Copy .env.example to .env first, then choose one of: `docker compose up -d --build` to start web and MCP together, `docker compose -f docker-compose.web.yml up -d --build` for web only, or `docker compose -f docker-compose.mcp.yml up -d --build` for the MCP server alone. The documented default ports are 3000 for the web app and 3001 for MCP, reachable at http://localhost:3001/mcp.

For local development the requirements are Node.js 18+ and pnpm, npm or yarn, with pnpm recommended. The sequence is `git clone git@github.com:hhszzzz/taibu.git`, `cd taibu`, `pnpm install`, `cp .env.example .env`, edit .env to fill in the necessary API keys, then `pnpm dev` and open http://localhost:3000.

The README does not enumerate which API keys are needed or which model providers are supported, only that the app has multi-model support, deep reasoning and visual recognition. That gap is the first thing to check in .env.example. It also does not describe the Supabase schema, even though Supabase/PostgreSQL is listed as a stack component and the feature list includes stored records, a personal knowledge base and anonymous discussion. If you self-host, expect to provision a database before the history and knowledge-base features work. For pure calculation work, `npm install taibu-core` avoids all of this.

The licence split is the decision point

The repository uses a mixed licence. Three packages, packages/core, packages/mcp and packages/mcp-server, carry MIT, with LICENSE files in their own directories. Everything else, described as the web, server, deployment and runtime code, is AGPL-3.0-only under the root LICENSE. The README notes that AGPL-3.0-only does not prohibit commercial use, but requires that a modified network service release corresponding source when it is offered to others. MIT packages allow commercial use, redistribution and modification provided copyright and licence notices are kept.

The practical consequence is that the calculation engine and the MCP server are the permissively licensed parts, and the application around them is not. If you want to embed divination calculations in a closed product, taibu-core is the path the README points to. If you fork the web app and run it as a network service, the AGPL obligation attaches to your modified version. That is a description of the stated terms, not legal advice; the exact scope of what counts as the network service is a question for your own counsel, especially since the repository is flagged as NOASSERTION at the metadata level while the README describes the split in prose.

One more cost: there are no retrieved releases. With no version tags in the material, there is no changelog to read and no way to pin a known-good commit other than by SHA. The npm package taibu-core has its own versioning, which is a separate track from the repository.

Where the design shows strain

The feature list is the main risk. Bazi, ziwei, qimen, da liuren, liuyao, meihua, taiyi, xiao liuren, astrology, tarot, MBTI, face reading, palm reading, compatibility and dream interpretation are fifteen domains in one repository, and the README presents each with a dense bullet list of rules. Depth per domain is hard to judge from the outside. The 51 shensha count and the 49 shensha count for da liuren are specific, which suggests real implementation work, but there is no test output, no reference chart comparison and no statement about which classical sources the rules follow. For bazi the README distinguishes traditional analysis from blind-school analysis, implying two rule sets, without saying how they diverge.

A second strain is input ambiguity. Divination systems depend on time and place. The README highlights true solar time for bazi and explicit timezone support for qimen and da liuren, which implies other tools may not carry the same handling. If you feed a timestamp without a timezone into a system that expects one, the chart shifts. Nothing in the material states a default.

Finally, the AI layer is not the calculator. The README describes AI analysis, personalization with style and user profiles, prompt budget visualization and @-mentions of divination data sources. Those are application features built on top of the engine. If your interest is the engine, most of that surface is irrelevant, and the parts you need are the tool schemas and taibu-core exports.

Alternatives and the real difference in approach

The closest comparison is not another divination app but a general purpose calendar and ephemeris library such as a Swiss Ephemeris binding or a lunar calendar package. Those give you astronomical positions and calendar conversion, and you write the interpretive layer yourself. Taibu takes the opposite position: it ships the interpretive layer, including shensha tables, palace structures, hexagram relations and card meanings, and exposes it through tool calls. If you want raw planetary longitudes, an ephemeris library is smaller and better documented. If you want a ziwei chart with twelve palaces and four transformations, taibu has already encoded the mapping rules and an ephemeris library will not help you.

The second alternative is writing your own MCP tools over a hand-rolled calculation module. That gives you a schema you control and no dependency on someone else's hosted endpoint. The cost is reimplementing the rule tables, which the README suggests is the bulk of the work here. Taibu's advantage is that the tool layer is already MCP 2026-07-28 and the transport is streamable-http, so an MCP-capable agent can call it with a five-line configuration block and no authentication.

The third option is simply using the hosted site. That is appropriate for a person who wants readings, and inappropriate for anyone who needs the output as data.

Who should adopt it, and what to check first

Adopt taibu if you are building an agent that needs structured divination output and you want to skip the rule-table work. The fastest path is the hosted MCP endpoint; the second fastest is `docker compose -f docker-compose.mcp.yml up -d --build` on port 3001. If you only need calculations inside a Node service, `npm install taibu-core` is the smallest dependency and sits under MIT.

Do not adopt it if you need a published accuracy methodology, a stable versioned API with a changelog, or a fully permissive codebase. The absence of releases in the material means you cannot pin a version tag. The AGPL-3.0-only portion covers the web and runtime code, so a hosted fork carries source-release obligations. And the README's silence on model providers, environment variables and database schema means self-hosting the full app is an exploratory task, not a documented one.

Before you commit, do three concrete things. Read packages/core/LICENSE and packages/mcp/LICENSE to confirm the MIT boundary matches where your code will sit. Read packages/mcp/README.md to decide between the hosted streamable-http endpoint and the offline local stdio mode, because that choice determines whether your client needs network access. And open .env.example to see what the application actually requires, since the README only says to fill in API keys without naming them. If those three checks pass, the MCP tool list is the contract you are buying, and it is a long one.

Editorial conclusion

Adopt taibu if you want structured divination output inside an MCP-capable agent and you are willing to depend on either the hosted endpoint at mcp.mingai.fun or a self-hosted MCP container on port 3001. Do not adopt it if you need a documented accuracy guarantee, a stable versioned API surface, or permissive licensing across the whole stack, because the web and runtime code is AGPL-3.0-only while only packages/core, packages/mcp and packages/mcp-server are MIT. Before committing, verify three things yourself: which licence file actually sits in the directory you intend to vendor, whether the local stdio mode in packages/mcp/README.md fits your client, and what .env.example requires beyond the API keys the README mentions.

Official sources

1. hhszzzz/taibu on GitHub
2. Issues
3. Project website
4. README