{
  "markdown": "# FateStar Ziwei\n\nA Zi Wei-focused hosted MCP for AI agents. One URL; no local server, package install, account, or API key for natal charts and six transit levels. Also available as an Agent Skill and REST API.\n\n[简体中文](./README.zh-CN.md)\n\n[![Validate](https://github.com/LouisLin0723/fatestar-ziwei/actions/workflows/validate.yml/badge.svg)](https://github.com/LouisLin0723/fatestar-ziwei/actions/workflows/validate.yml)\n[![Live contract](https://github.com/LouisLin0723/fatestar-ziwei/actions/workflows/live-contract.yml/badge.svg)](https://github.com/LouisLin0723/fatestar-ziwei/actions/workflows/live-contract.yml)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-8b5cf6)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.LouisLin0723%2Ffatestar-ziwei)\n[![Release](https://img.shields.io/github/v/release/LouisLin0723/fatestar-ziwei)](https://github.com/LouisLin0723/fatestar-ziwei/releases)\n[![Stars](https://img.shields.io/github/stars/LouisLin0723/fatestar-ziwei?style=flat)](https://github.com/LouisLin0723/fatestar-ziwei/stargazers)\n[![License](https://img.shields.io/github/license/LouisLin0723/fatestar-ziwei)](./LICENSE)\n\n![FateStar Ziwei Agent Skill, hosted MCP, and REST API preview](./assets/fatestar-ziwei-social-preview.png)\n\nNatal charts and six-level transits work anonymously. The optional Zheng Da Qian reading uses a FateStar API key and credits.\n\n## Try it now\n\n[Open a live anonymous chart response](https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male). No account or API key is required. Selected fields from that response:\n\n```text\nSolar 1990-7-23 | Lunar 一九九〇年六月初二\nFive-elements class 土五局 | Life ruler 文曲 | Body ruler 火星\nLife palace 己卯 | 廉贞 (平), 破军 (陷)\n12 palaces | 5 detected patterns | 4 natal transformations\n```\n\nAfter installing the Skill or connecting the MCP endpoint, tell your agent:\n\n> Create a Zi Wei Dou Shu chart for a man born on July 23, 1990 at 8:00 AM, then show his 2026 transits.\n\nThe agent calls FateStar and returns:\n\n- a natal chart with 12 palaces, stars, brightness, and Four Transformations;\n- true-solar-time correction when longitude and timezone are supplied;\n- decade, minor-cycle, annual, monthly, daily, and hourly transits;\n- an optional Zheng Da Qian reading when a valid key and credits are available.\n\nIf the live result is useful, [star the repository](https://github.com/LouisLin0723/fatestar-ziwei). It helps other agent developers find the free endpoint.\n\n## Why FateStar\n\nFateStar is deliberately narrow: it makes Zi Wei chart data easy to use from an AI agent without operating a local astrology server.\n\n| Choose | When it fits |\n| --- | --- |\n| **FateStar** | You want a hosted remote MCP now: one URL, anonymous free charting, six transit levels, native structured MCP output, and an official Registry listing. |\n| [Iztro](https://github.com/SylarLong/iztro) | You need an open-source Zi Wei engine to embed, inspect, or modify inside your own application. |\n| [Taibu](https://github.com/hhszzzz/taibu) or [Horosa Skill](https://github.com/Horace-Maxwell/horosa-skill) | You prefer broader multi-system or offline metaphysics tooling over a focused hosted Zi Wei endpoint. |\n\nThese are different deployment choices, not a claim that one school or engine is universally more accurate.\n\n## Quick start\n\n### Agent Skill\n\nGitHub CLI 2.90 or newer installs the Skill into Codex, Claude Code, Cursor, and many other agents.\n\n```bash\n# Codex\ngh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent codex --scope user\n\n# Claude Code\ngh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent claude-code --scope user\n\n# Cursor\ngh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent cursor --scope user\n```\n\nRestart the agent, then ask it to create a Zi Wei Dou Shu chart. The canonical Skill is in [`skills/ziwei-paipan`](./skills/ziwei-paipan).\n\nIf your GitHub CLI is older, [upgrade it](https://github.com/cli/cli#installation) or copy the `skills/ziwei-paipan` directory into your agent's Skill directory.\n\n### Hosted MCP\n\nNo local server is required. Add the remote endpoint to a client that supports Streamable HTTP:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"fatestar-ziwei\": {\n      \"url\": \"https://www.fatestar.top/api/mcp\"\n    }\n  }\n}\n```\n\nThe endpoint exposes `ziwei_chart`, `ziwei_transits`, and `ziwei_reading`. The first two tools are free and anonymous.\n\n`tools/list` declares an `outputSchema` and behavior annotations for every tool. Successful calls return both native `structuredContent` and legacy JSON text, so newer agents can consume typed fields while older clients keep working.\n\nThe server is listed in the official MCP Registry as [`io.github.LouisLin0723/fatestar-ziwei`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.LouisLin0723%2Ffatestar-ziwei).\n\n### REST API\n\nRun a free chart request without an account:\n\n```bash\ncurl \"https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male\"\n```\n\nFull API and client documentation: [fatestar.top/docs](https://www.fatestar.top/docs)\n\n## Choose an integration\n\n| Integration | Best for | Install | Free charting |\n| --- | --- | --- | --- |\n| Agent Skill | Codex, Claude Code, Cursor, and other coding agents | `gh skill install` | Yes |\n| Hosted MCP | MCP clients with remote HTTP support | One URL | Yes |\n| REST API | Apps, scripts, and backend services | `curl` or HTTP client | Yes |\n\nAll three routes use the same FateStar engine. Pick the interface that fits your client.\n\n## Capabilities\n\n| Capability | Cost | Notes |\n| --- | --- | --- |\n| Natal chart | Free | Solar or lunar input, 12 palaces, 102 stars, brightness, Four Transformations |\n| Six-level transits | Free | Decade, minor cycle, year, month, day, and hour |\n| True solar time | Free | Enabled with longitude and timezone input |\n| Zheng Da Qian reading | Credits | FateStar knowledge engine and hosted reading service |\n\nThe Skill ships Python, Node.js, PowerShell, and Bash clients. Python and Node.js use their standard libraries and require no package install.\n\n## CLI examples\n\nRun these commands from the installed `ziwei-paipan` Skill directory:\n\n```bash\n# Free natal chart\npython scripts/ziwei_cli.py chart \\\n  --year 1990 --month 7 --day 23 --hour 8 --gender male\n\n# Free 2026 transits\npython scripts/ziwei_cli.py transits \\\n  --year 1990 --month 7 --day 23 --hour 8 --gender male \\\n  --target-year 2026\n\n# Hosted reading, requires FATESTAR_API_KEY\npython scripts/ziwei_cli.py reading \\\n  --year 1990 --month 7 --day 23 --hour 8 --gender male \\\n  --question \"Should I change jobs this year?\"\n```\n\nUse `python scripts/ziwei_cli.py doc` for the offline interface reference. Equivalent Node.js, PowerShell, and Bash clients are in the same directory.\n\n## API key and billing\n\n`chart` and `transits` are free with or without a key. A key only attributes those free calls to your account.\n\n`reading` requires an `FSFSKey` and may consume credits. Create a key in the [FateStar developer center](https://www.fatestar.top/finance/developer). Store it outside source control:\n\n```bash\nexport FATESTAR_API_KEY=\"FSFSKey_your_key\"\n```\n\nFor MCP clients, send `Authorization: Bearer FSFSKey_your_key` only when you want to use `ziwei_reading`. Never commit a real key or paste it into an issue.\n\n## Repository layout\n\n```text\nskills/ziwei-paipan/\n├── SKILL.md\n├── agents/openai.yaml\n├── scripts/\n│   ├── ziwei_cli.py\n│   ├── ziwei_cli.js\n│   ├── ziwei_cli.ps1\n│   ├── ziwei_cli.sh\n│   └── shared/\n```\n\nThe root [`server.json`](./server.json) describes the hosted endpoint using the official MCP Registry schema.\n\n## Development\n\n```bash\npython skills/ziwei-paipan/scripts/generate.py --check\npython tests/live_contract_check.py\npython skills/ziwei-paipan/scripts/ziwei_cli.py doc\nnode skills/ziwei-paipan/scripts/ziwei_cli.js doc\npowershell -ExecutionPolicy Bypass -File skills/ziwei-paipan/scripts/ziwei_cli.ps1 doc\nbash skills/ziwei-paipan/scripts/ziwei_cli.sh doc\n```\n\nThe four clients share generated constants and an offline interface spec. Edit the shared files first, run `generate.py`, then run the checks above.\nThe broader compatibility matrix is in [`docs/TEST_PLAN.md`](./docs/TEST_PLAN.md). The exact hosted MCP assertions and their limits are documented in [`docs/VERIFICATION.md`](./docs/VERIFICATION.md).\n\n## Open-source boundary\n\nThis repository contains the Agent Skill, four thin clients, integration metadata, and public documentation. FateStar's server implementation, private prompts, Zheng Da Qian training data, retrieval corpus, evaluation sets, and billing controls are not included.\n\nThe repository code is MIT licensed. FateStar's brand, hosted service, and private knowledge assets remain proprietary.\n\n## Contributing\n\nBug reports, client examples, and compatibility fixes are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Security reports belong in [SECURITY.md](./SECURITY.md), not a public issue.\n",
  "bytes": 8995,
  "sha": "aa858522ea18e3ccb168c2c04dd8c756cae2921e0416e62952b23845a773978b",
  "repo_slug": "louislin0723/fatestar-ziwei",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_louislin0723_fatestar_ziwei_55e23257/readme"
}