---
name: fatestar
description: 紫微斗數大模型：鄭大錢 (ZWDS LLM · ZDQ) — Zi Wei Dou Shu (紫微斗数) charting and AI readings from FateStar. Use when the user asks about 紫微斗數 / 紫微斗数 / Zi Wei Dou Shu / Purple Star Astrology, their natal chart (命盤), palaces, stars, 四化, 大限 / 流年 transits, or wants a fortune reading from their birth data. Pricing: charting is free; only AI readings are charged, US$0.10 per reading (US$0.20 for long questions), charged to the user's FateStar API balance (new accounts get a one-time US$3 free trial, about 30 standard readings, when they first connect via MCP sign-in or create an API key; top up at https://www.fatestar.top/settings?tab=api). Always tell the user the cost and get a yes first.
---

# FateStar · 紫微斗數大模型：鄭大錢

FateStar's MCP server (`fatestar`, URL `https://www.fatestar.top/mcp`) gives you the same chart engine and AI reader as the website https://www.fatestar.top, billed to the user's own FateStar account.

## Which tool, when

| User wants | Tool | Cost |
|---|---|---|
| A natal chart from birth data (palaces, stars, 四化, 格局) | `ziwei_chart` | free (no key needed; rate-limited per IP) |
| 大限 / 小限 / 流年 / 流月 / 流日 / 流時 for a date | `ziwei_transits` | free (no key needed; rate-limited per IP) |
| Their charts saved on FateStar | `fatestar_list_charts` → `fatestar_get_chart` | free |
| Save a chart to their FateStar account | `fatestar_save_chart` | free (API key needed; uses chart quota) |
| How much balance / how many credits they have | `fatestar_credits` | free |
| FateStar's own AI reader (鄭大錢) to answer a question | `ziwei_reading` | **US$0.10 (long questions US$0.20)** |

Charting is free. You can read the chart yourself from `ziwei_chart` / `ziwei_transits` output. Call `ziwei_reading` only when the user explicitly wants FateStar's reading.

## Birth data to collect

Ask for anything missing, in one message:
- date (year, month, day) and whether it is solar (國曆 / 阳历) or lunar (農曆 / 农历; ask about 閏月 if lunar)
- time of birth, 24-hour clock (`hour` 0–23, `minute`) — not a 時辰 index
- gender (`male` / `female`)
- optional: birthplace longitude and UTC offset (enables true solar time; matters near 時辰 boundaries)

## Before `ziwei_reading` (it spends money)

1. Tell the user it uses their FateStar credits: questions up to about 100 Chinese characters (300 Latin characters) cost **1 credit**, longer ones **2 credits**. Same price as the website.
2. Wait for a clear yes. Do not call it speculatively, in loops, or "to compare".
3. Pass a fresh random `idempotencyKey` per question (for example a UUID). If a call fails and you retry the same question, reuse the same key so it is charged once.
4. After the call, tell the user `creditsUsed` and `balanceAfter`.

## Tone (cruelty)

Readings default to 狠人模式 / tough-love mode (`cruelty: 2`, blunt and direct), the same default as the website. If the user wants a gentler tone, pass `cruelty: 1` to `ziwei_reading`. Only an explicit `1` turns it off.

## Errors

| `code` | What to do |
|---|---|
| `UNAUTHORIZED` / `INVALID_API_KEY` / `API_KEY_REVOKED` | The connection is not signed in. Ask the user to reconnect (OAuth) or create a key at https://www.fatestar.top/settings?tab=api |
| `INSUFFICIENT_CREDITS` (`need`, `have`) | Tell the user; they can top up at https://www.fatestar.top/pricing. Offer to interpret the free chart yourself instead. |
| `KEY_DAILY_LIMIT_REACHED` | This key's daily credit cap is used up; the owner can raise it in Settings → API. Resets 00:00 Asia/Shanghai. |
| `RATE_LIMITED` | Wait a minute, then continue. |
| `QUESTION_TOO_LONG` | Shorten the question. |

## Dates: dual-track 干支 (important)

- `真實出生四柱` / `真实出生四柱` and `真實干支` / `真实干支` are real calendar pillars. Use these when you talk about days, months, or years.
- The 天干地支 shown on each palace is a palace label used to derive 四化. Never present it as a date.
- FateStar uses the 三合派 rule set (庚 stem: 化祿太陽 / 化權武曲 / 化科天同 / 化忌太陰). Other schools differ; say so if the user cites another school.

## Tone and limits

Readings are cultural and reflective, not predictions or medical, legal, mental-health, or financial advice. If a question touches self-harm or a crisis, do not call the reading tool; respond with care and point to local emergency help.

## Not connected yet?

Follow https://www.fatestar.top/agent.md
