freebazi-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Su
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# freebazi-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that computes a full Chinese **Bazi** (八字, Four Pillars of Destiny) chart from a birth date, time, and place.
+
+It wraps the same calculation engine that powers **[freebazi.com](https://freebazi.com)**: an offline engine that corrects for **True Solar Time** and historical **daylight saving**, and is cross-validated against established Bazi libraries. No API key, no network calls, everything runs locally.
+
+## What it returns
+
+Give it a birth moment and a city, and `compute_bazi_chart` returns:
+
+- The **Four Pillars** (Year, Month, Day, Hour), each as a Heavenly Stem and Earthly Branch
+- Your **Day Master** (日干) and the **Ten Gods** (十神) of every character
+- **Hidden Stems** (藏干), **Na Yin** (纳音), and the **Twelve Growth Stages** (十二长生)
+- **Five Elements** distribution, both visible and including hidden stems
+- **Shen Sha** (神煞) and **branch relations** (合冲刑害)
+- **Luck Pillars** (大运) with the current period flagged, and the current year's pillar
+- A link to the full interactive chart on [freebazi.com](https://freebazi.com)
+
+## Install
+
+Requires Node.js 18+.
+
+Run directly with npx:
+
+```bash
+npx freebazi-mcp
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "freebazi": {
+      "command": "npx",
+      "args": ["-y", "freebazi-mcp"]
+    }
+  }
+}
+```
+
+Other MCP clients (Cline, Continue, Cursor, etc.) take the same `command` / `args`.
+
+## Tools
+
+### `compute_bazi_chart`
+
+Compute a full chart.
+
+| Argument | Type | Notes |
+|---|---|---|
+| `year`, `month`, `day` | number | Birth date |
+| `hour`, `minute` | number | Local clock time as recorded (omit if `timeUnknown`) |
+| `gender` | `"male"` \| `"female"` | Needed for luck-pillar direction |
+| `city` | string | e.g. `"Taipei"`, `"New York"`. Resolved to longitude + time zone for True Solar Time |
+| `longitude`, `utcOffset` | number | Alternative to `city` |
+| `timeUnknown` | boolean | Hour pillar becomes tentative |
+| `trueSolarTime` | boolean | Default `true` |
+| `dayRule` | `"zi23"` \| `"midnight"` | Day boundary, default 23:00 |
+| `yearRule` | `"lichun"` \| `"cny"` | Year boundary, default Li Chun |
+
+### `search_cities`
+
+Search about 490 major world cities by English or Chinese name. Returns each match's country, longitude, and IANA time zone, so you can pass an exact city to `compute_bazi_chart`.
+
+## Example
+
+> Compute the Bazi chart for someone born 15 June 1990, 9:30 AM, in New York.
+
+The server resolves New York, applies True Solar Time (9:30 AM becomes 8:34 AM, 56 minutes earlier, which shifts the Hour pillar), and returns the four pillars 庚午 壬午 辛亥 壬辰 with a Xin (辛) yin Metal Day Master, all Ten Gods, elements, luck pillars, and more.
+
+## Accuracy and honesty
+
+Solar-term boundaries are computed from the sun's apparent longitude with standard astronomical formulas, and time zones (including historical daylight saving) are resolved from the IANA database. The engine's four pillars match established libraries character for character across thousands of test charts.
+
+Bazi is a traditional framework for reflection on temperament, tendencies, and timing. This tool describes a chart; it does not predict events.
+
+## Links
+
+- Interactive calculator, guides, and full charts: **[freebazi.com](https://freebazi.com)**
+- What is a Day Master: [freebazi.com/day-master](https://freebazi.com/day-master/)
+- The Ten Gods explained: [freebazi.com/ten-gods](https://freebazi.com/ten-gods/)
+
+## Credits
+
+City data from [GeoNames](https://www.geonames.org/) (CC BY 4.0). Simplified to Traditional conversion via OpenCC.
+
+## License
+
+MIT