# Brhiza/mingyu: a self-hosted divination engine that outputs prompts, not predictions

> Mingyu is a TypeScript toolkit that computes Chinese and Western divination charts and turns them into structured prompts for any LLM. The interesting part is not the fortune telling, it is the separation between chart generation and interpretation.

**Brhiza/mingyu** — 八字、紫微、星盘、六爻、梅花、奇门、大六壬、小六壬、塔罗、雷诺曼、灵签、择日一站式玄学算命占卜工具包，输出结构化提示词与数据。提供公开 API、MCP Server 与 skill。

- Repository: https://github.com/Brhiza/mingyu
- Website: https://aov.cc
- Stars: 453 · Forks: 119
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/brhiza-mingyu

## The problem Mingyu actually solves

Most divination software bundles two things that should be separate: calculating a chart, and interpreting it. The calculation is deterministic. Given a birth date, a time and a gender, a bazi chart or a ziwei chart is a fixed transformation with rules that can be checked. The interpretation is not deterministic, and increasingly people want to hand it to whichever model they already pay for.

Mingyu takes the first half and stops there. The README describes it as a toolkit that performs chart calculation and then generates a complete prompt that can be handed to any large model for interpretation. That is the whole design bet: the project owns the rules and the prompt structure, and the model choice stays with the user.

That makes it useful to two groups. Developers building an astrology or metaphysics feature who do not want to reimplement 纳甲 or 四化 rules. And agent users who want a tool their assistant can call, where the assistant does the talking and the library does the counting. The supported list is wide: 八字, 紫微斗数, 西方星盘, 七政四余, 六爻, 梅花易数, 奇门遁甲, 大六壬, 金口诀, 太乙神数, 皇极经世, 塔罗, 雷诺曼, 三山国王灵签, 小六壬, and 择日 methods including 八宅明镜, 玄空飞星 and 五运六气. Breadth is not depth, and the README does not claim otherwise.

## How the chart-to-prompt pipeline is laid out

The repository is a pnpm workspace. packages/core holds mingyu-core, the algorithm package that does the actual chart work. src/ is the Vue and Vite front end. server/ and vite.server.config.ts build the Node server that the Dockerfile runs. mcp/ holds the MCP server, with its own Vite config. functions/ is for Cloudflare Pages Functions, with a size check script wired into build:pages-functions. android/ is a Capacitor project, which is why capacitor.config.ts sits at the root and why there is a pnpm android:sync script.

The data flow is one direction. Input is a solar date, a solar time and a gender, or a question in the case of the divination methods, or a Date object for 六爻. The core package converts and lays out the chart, including 真太阳时 conversion for bazi and 大运流年流月流日 detail. Then a prompt builder turns that structure into text. The README's own example shows the three entry points sitting side by side: generateBazi, generateLiuyao and drawTarotSpread. Each returns a chart object, and the prompt layer is separate from it.

The AI server side is configured entirely through environment variables, which is the clearest sign that the maintainers expect self-hosting rather than a managed product. AI_BASE_URL defaults to https://api.deepseek.com/v1, AI_MODEL defaults to deepseek-chat, and AI_BUILTIN_ENABLED and AI_DEFAULT_ENABLED both default to false. Rate limiting is on by default at 12 requests per 600 seconds. Stream timeouts are set at 30000 ms idle and 95000 ms total. Those defaults are opinionated and worth reading before you deploy, because AI_BUILTIN_ENABLED=false means the built-in assistant is off until you turn it on.

## Installing mingyu-core and generating a first chart

The library path is the shortest one. The README gives npm install mingyu-core as the install step, and the package is published under that name on npm.

```bash
npm install mingyu-core
```

The README's usage example imports three functions and calls them with plain arguments. Note that gender is passed as the Chinese character 男, not an English string, so the API is not localized at the type level.

```typescript
import { generateBazi, generateLiuyao, drawTarotSpread } from 'mingyu-core';

const bazi = generateBazi({ solarDate: '1995-08-18', solarTime: '09:30', gender: '男' });

const liuyao = generateLiuyao(new Date());

const tarot = drawTarotSpread('celtic');
```

After that call, bazi holds the chart structure. What you do with it is up to you: render it, store it, or pass it to your own prompt template. The README points to packages/core/README.md for the full surface, and that file is where the real API documentation lives.

If you would rather run the whole application, the repository ships a Dockerfile and a docker-compose.yml. The compose file maps port 3000 and passes the AI_* variables through from your environment.

```bash
docker compose up
```

The Dockerfile is a three-stage build on node:22-alpine, running pnpm build and pnpm build:server, then starting server-dist/docker-server.mjs as the node user on port 3000. Building from source instead means pnpm install, then pnpm dev for the dev server or pnpm build for the bundle. The build script runs skill:sync and builds mingyu-core first, so a bare pnpm build is not just a Vite call.

## Connecting Mingyu to an agent over MCP

The MCP path is the one most likely to be used by people who never open the source. There are two variants and they are not equivalent.

The remote variant needs no install. The README gives the Claude Code command directly, and for Cursor, Windsurf and VS Code it says to add an SSE server URL of https://aov.cc/mcp. That endpoint is operated by the project, so the tool calls leave your machine.

```bash
claude mcp add mingyu --transport sse https://aov.cc/mcp
```

The local variant runs on your machine through npx. The README gives npx -y mingyu-mcp as the command, and notes that pnpm mcp starts it from a source checkout.

```bash
npx -y mingyu-mcp
```

There is also a skill installation, which the README labels as the recommended option because it needs no configuration. It installs globally with the -g and -y flags.

```bash
npx skills add Brhiza/mingyu --skill mingyu -g -y
```

The distinction matters. Remote MCP sends your birth data and questions to aov.cc. Local npx keeps the computation on your machine, though the interpretation still goes wherever your model runs. If you are handling other people's birth data, that is the line to think about before picking the convenient option.

## Where Mingyu is the wrong choice

The README is explicit that results and prompts are for traditional culture research and entertainment, and that they do not replace medical, psychological, legal or investment advice. That is a disclaimer, but it also describes a real boundary. Do not route a decision through this.

The second limitation is interpretive. Mingyu generates prompts. If you want a library that returns a reading, you are building the reading layer yourself, including the prompt template if you do not like the bundled one. The README does not describe how the prompt text is versioned or how it changes between releases, so a prompt that works today is not guaranteed to be byte-identical after an upgrade.

The third is operational. The README does not document rollback, and it does not describe a versioning or migration policy for the chart output shape. The repository is at version 0.4.0 in package.json. For a library whose output feeds downstream prompt templates, a change to a field name is a breaking change for you even if it is a minor release for the project. Pin your version.

Fourth, depth varies. The feature table lists 太乙神数 and 皇极经世 alongside 八字, but the README does not describe the implementation depth of each in the same detail. The 三山国王灵签 section is specific: 92 signs from the 揭西 祖庙, each with a sign number, title, original verse and allusion. That level of specificity is not repeated for every method in the table, and docs/capabilities.md is where the project says the scope is defined.

Finally, the Android app is the only mobile story. It is a Capacitor wrapper that hands a chart off to an installed AI app, with the README stating that API keys stay on the device. There is no iOS build in the repository layout.

## How this differs from calling a hosted astrology API

The obvious alternative is a hosted chart API, where you send a birth date and get back a formatted reading. The difference is where the rules live. With a hosted API you get a result and no visibility into the 纳甲 or 四化 logic that produced it. With Mingyu you get the chart structure and you write the interpretation step, which means you can diff two versions of the chart for the same input and see what changed.

A second alternative is 时月东方, which the README describes as built on Mingyu's core capability using Vue 3 and Vite, and points to as a real reference for consuming mingyu-core inside a separate product. That is not a competitor so much as a worked example, and it is the most useful thing to read if you are evaluating whether the core package is pleasant to consume. The repository is at github.com/Brhiza/sydf.

A third option is writing the chart rules yourself. For 八字 that is a substantial project. For 六爻 with 京房八宫纳甲, 六亲六神 and 世应动变, it is worse. The honest comparison is not feature count, it is whether you want to own a rules engine that has to be correct, or own an integration that has to be maintained.

## Licence, maintenance and the cost of upgrading

Mingyu is AGPL-3.0-only. The practical consequence is that if you run a modified version as a network service, the licence's network clause reaches you. For an internal tool this rarely matters. For a hosted product that embeds mingyu-core, it is the first thing to take to a lawyer, and this article is not legal advice. The npm package mingyu-core is published under the same project, so the same terms apply when you import it.

The last push to the repository was on 2026-09-10, and the repository is not archived. Recent releases are Android builds: android-v1.1.3 on 2026-09-07, android-v1.1.4 and android-v1.1.5 both on 2026-09-09. The Android version numbering is ahead of the 0.4.0 in package.json, so do not read the release tag as the library version.

The upgrade cost is concentrated in two places. First, the chart output shape, which the README does not promise to keep stable. Second, the prompt text, which is the thing you are actually shipping to a model. Neither has a documented migration path. The README says the project is maintained as a personal side project, and it asks for support through a donation box that it says is passed on to charity. That is a reasonable arrangement, but it means there is no support contract, no SLA, and no published deprecation policy. Budget for reading the diff on every bump.

## Conclusion

Adopt it if you want chart computation and prompt generation separated from model choice, and you are comfortable with AGPL-3.0-only. Skip it if you need a hosted service with an uptime commitment, or if you want the library itself to give you interpretive answers rather than prompts. Before committing, run pnpm test in a clone and read docs/capabilities.md to see which of the listed methods are covered in depth and which are listed without detail.

## FAQ

### What is Mingyu and who is it for?

It is a free open source toolkit for Chinese and Western divination chart calculation that outputs structured prompts for an LLM to interpret. It targets developers who want the chart rules handled for them and agent users who want a callable tool.

### How do I install Mingyu as a library?

The README gives npm install mingyu-core, after which you import generateBazi, generateLiuyao or drawTarotSpread. The core package documentation is in packages/core/README.md.

### Can I use Mingyu with Claude Code or Cursor?

Yes. The README gives claude mcp add mingyu --transport sse https://aov.cc/mcp for Claude Code, and says to add https://aov.cc/mcp as an SSE server URL in Cursor, Windsurf or VS Code.

### Does Mingyu run locally or in the cloud?

Both. The remote MCP endpoint at https://aov.cc/mcp sends tool calls to the project's server, while npx -y mingyu-mcp runs the MCP server on your own machine. The Dockerfile builds a self-hosted server on port 3000.

### What licence does Mingyu use?

The repository and package.json both state AGPL-3.0-only. The README links to the LICENSE file for the full text.

## Sources

- [Brhiza/mingyu on GitHub](https://github.com/Brhiza/mingyu)
- [License: AGPL-3.0](https://github.com/Brhiza/mingyu/blob/main/LICENSE)
- [Project website](https://aov.cc)
- [README](https://github.com/Brhiza/mingyu/blob/main/README.md)
- [Releases](https://github.com/Brhiza/mingyu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brhiza-mingyu