Mingyu (命语): a TypeScript divination toolkit that outputs prompts, not predictions

What Mingyu actually produces

The README is explicit that the deliverable is not a verdict. Mingyu performs the chart calculation for a birth time or a question, then assembles a prompt that can be handed to any large model for interpretation. That split matters. The repository owns the calendar arithmetic, the stem and branch placement, the hexagram construction and the card draw. The model owns the reading. If you were looking for a system that tells you what the chart means, this is not it, and the disclaimer at the bottom of the README says as much: results are for traditional culture research and entertainment, and are not a substitute for medical, psychological, legal or investment advice. The audience is therefore narrower than the topic list suggests. It is developers building divination features into an app, and people who already use a chat model and want the chart data fed in correctly rather than hallucinated.

One repository, four delivery surfaces

The same engine is exposed four ways, and the choice between them is the first decision a reader has to make. mingyu-core is the npm package, installed with npm install mingyu-core, for code that runs inside your own process. The REST API lives at https://aov.cc/api/v1 with an OpenAPI document at https://aov.cc/api/v1/openapi.json and an llms.txt at https://aov.cc/llms.txt. The MCP server comes in two forms: a remote Streamable HTTP endpoint at https://aov.cc/mcp, and a local process started with npx -y mingyu-mcp. The Android APK is the fourth surface, and it works differently from the others: after generating a chart it hands off to an already installed AI app such as ChatGPT, Claude or Kimi, with the API key kept on the device. That last detail is the honest design choice here. The app does not proxy your key through aov.cc. The repository also lists a fifth integration, an agent skill installed with npx skills add Brhiza/mingyu --skill mingyu -g -y.

The calculation surface, method by method

The feature table is the most concrete part of the README, and it is worth reading as a scope statement rather than a marketing list. Under fate calculation the project claims bazi, ziwei, a combined bazi-ziwei mode, Western natal charts and qizheng siyu, with true solar time conversion, major and annual luck cycles down to month and day, the sanfang sizheng frame, temple and fall states, the four transformations, shensha, synastry, and planetary periods with flowing luminaries. Divination covers liuyao najia and meihua yishu, including hand-shaken or specified hexagrams, the Jing Fang eight-palace najia arrangement, the six relations and six spirits, shi and ying lines with moving and changed lines, and ti-yong generation and restraint. The san shi group covers qimen dunjia, da liuren, jin kou jue, taiyi shenshu and huangji jingshi, with rotating and flying plate qimen, four lessons and three transmissions, and the seventy-two annual configurations. Cards and lots include 78 tarot cards, 36 Lenormand cards with a grand tableau, the 92-lot Sanshan Guowang oracle, and xiao liuren. Day selection and feng shui add the almanac, eight-mansion, flying star and five movements six qi systems. The breadth is real, but breadth in a table is not the same as correctness in the rules, and the README does not attempt to argue for any particular school's interpretation.

Calling it from TypeScript

The README gives one code block for the core package and it is short enough to quote in full. After npm install mingyu-core, you import generateBazi, generateLiuyao and drawTarotSpread. The bazi call takes an object with solarDate, solarTime and gender, for example solarDate: '1995-08-18', solarTime: '09:30', gender: '男'. The liuyao call takes a Date. The tarot call takes a spread name as a string, shown as 'celtic'. That is the entire documented surface at the top level, and the README points to packages/core/README.md for the rest. The gap is worth naming plainly: there is no example of what any of these three functions returns. Since the project's whole premise is structured output, the return type is the thing a developer most needs to see, and it is not in the README. Anyone evaluating this should open packages/core/README.md first, and if the shapes are still unclear, call the REST API once and inspect the JSON before writing integration code.

Wiring the MCP server into an editor

For agent use the setup is a single command per client. Claude Code takes claude mcp add mingyu --transport sse https://aov.cc/mcp. Cursor, Windsurf and VS Code are configured by adding an SSE server URL of https://aov.cc/mcp directly in the client's MCP settings. The README also mentions Claude Desktop as a supported target for the remote endpoint. If you would rather not depend on the hosted endpoint, the local server runs with npx -y mingyu-mcp, and the README notes that pnpm mcp starts it from a source checkout. The two paths are not equivalent. The remote endpoint removes installation but puts a third party in the request path and depends on aov.cc being reachable; the local npx process keeps everything on your machine but pulls the package on each run unless it is cached. For a tool that handles birth data, that distinction is the one to think about before choosing.

Where the project is thin, and where it is the wrong tool

Several things a reader would want are simply absent from the supplied material. There is no description of the API's authentication model, rate limits, or response schema beyond the OpenAPI link. There is no statement about the accuracy of the underlying calendar conversion, which is the part most likely to be wrong in any divination library, particularly around true solar time and historical timezone offsets. There is no versioning policy for mingyu-core, no changelog in the README, and no indication of how breaking changes are handled. The release list shows three Android builds in three days in September 2026, which suggests active mobile work, but says nothing about the stability of the core package. The AGPL-3.0-only licence is the other hard constraint. If you embed mingyu-core in a network service, the copyleft terms reach the service, and that is a decision for your own legal review rather than something this article can settle. Finally, this is the wrong tool if you want a maintained SaaS with a support contract. The README describes the project as maintained by an individual in their spare time, alongside a second project, with donations from the tip jar given to charity.

A different approach: the hosted chart API

The obvious alternative for a developer is not another open source package but a commercial chart-calculation API, the kind sold per request with a documented response schema, a versioned contract and an SLA. The difference is not accuracy, which neither side demonstrates here, but who carries the risk. A hosted API takes responsibility for calendar edge cases, library updates and uptime, and charges for it. Mingyu puts all of that on you: you pin a version of mingyu-core, you handle the AGPL-3.0-only obligations, and you are the one who notices when a rule changes. In exchange you get the source, the ability to patch a rule you disagree with, and no per-call cost. The second alternative is writing the chart logic yourself, which for a single method such as tarot or xiao liuren is genuinely feasible, and for bazi with true solar time and luck cycles is not a weekend project. Mingyu's value is concentrated in the methods where the rule set is large and the edge cases are many.

Maintenance, licence and what to check before you build on it

The licence is AGPL-3.0-only, stated once in the README and once in the repository metadata, with the full text in LICENSE. That is the most consequential fact in this review for anyone building a product. There is no dual licence, no commercial exception and no contributor licence agreement mentioned in the material, which means the project cannot easily relicense later and you cannot negotiate different terms. On maintenance, the only signals available are the last push date of 2026-09-10, the three Android releases in the days before it, a CI workflow badge, and a stated intent to keep the project free. The README documents the local workflow as pnpm install, pnpm dev, pnpm test and pnpm build, plus pnpm android:sync for the mobile build, so a source build is a known quantity. What is not documented is the upgrade path: no migration notes, no deprecation policy, no statement about which Node or pnpm versions are supported. If you are choosing between the npm package and the REST API, the API insulates you from version churn at the cost of a network dependency; the package gives you control at the cost of tracking releases yourself.

Editorial conclusion

Adopt Mingyu if you need chart calculation as a library or as a tool an agent can call, and you are comfortable with AGPL-3.0-only. Do not adopt it if you need a hosted service with an uptime commitment, or if your product cannot carry copyleft obligations. Before committing, verify two things yourself: that the chart rules in docs/capabilities.md match the schools you care about, and that the exported types from mingyu-core cover the fields you intend to store, since the README shows only three function signatures and nothing about the shape of what they return.

Official sources

1. Brhiza/mingyu on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases