nmhaaa3218/TuViMCP

This is a Model Context Protocol (MCP) server developed in Python that calculates and manages Vietnamese "Tử Vi" horoscope charts. It is optimized to output clean, structured JSON data that LLM agents can easily read, interpret, and explain to users.
---
English Documentation
Quick Links
- Full Documentation
- Contributing Guidelines
- Changelog / Release History
- Example JSON Outputs & Scripts
Features
- **Horoscope Generation:** Converts Solar or Lunar birth dates and times into a full Tử Vi chart (Thiên Bàn and Địa Bàn with 12 houses and over 100 stars).
- **51 Cách Cục Evaluation Engine:** Automatically recognizes all 51 traditional astrological formations (51 Cách Cục Trung Châu Phái) during chart generation, returning matched patterns with descriptions, poems (Cổ Ca), commentary (Bình Chú), and pros/cons (Ưu/Khuyết điểm).
- **High-Quality Image Rendering:** Generates beautiful, print-ready chart images with element-based colored text (Green for Wood, Red for Fire, Yellow for Earth, Gray for Metal, Blue for Water), custom badge boxes for Tuần & Triệt, and geometric connecting lines highlighting the Mệnh and Thân relationship.
- **Vận Hạn (Transit Analysis):** Computes transit stars (Lưu tinh) and maps the active 10-year period (Đại Hạn), yearly period (Tiểu Hạn), monthly period (Nguyệt Hạn), and daily period (Nhật Hạn) for any target year, month, and day (e.g., 2026).
- **Auspicious Date & Time Checker:** Evaluates Hoàng Đạo/Hắc Đạo, 12 Trực, 28 Tú, Tiết Khí, travel directions, and auspicious hours for any calendar date.
- **Local Persistence (Python Library):** Includes built-in SQLite database utilities (tuvi_mcp.database) for Python library consumers to save, retrieve, list, and delete horoscope profiles. (MCP tools are stateless and do not require a database.)
- **Flexible Hour Mapping:** Automatically maps calendar hours (e.g., "14:30") or string names (e.g., "Ngọ", "Tý") to the correct Earthly Branch hour index.
- **Local Inlining (Independent):** Includes the core ansaotuvi calculation logic internally with custom Tuần/Triệt double-cung fixes.
Python Library API
Beyond the MCP server, tuvi-mcp-server ships a typed, ergonomic Python API for direct use in scripts, notebooks, or web backends:
The same library is what the MCP tools wrap, so behavior is identical whether you call Horoscope.from_birth(...).chart() or invoke the generate_horoscope tool from an MCP client.
Known Limitations & Assumptions
- **Timezone:** Calculations default to the Vietnamese local timezone (GMT+7). For births elsewhere, pass timezone explicitly to the MCP tool (timezone accepts an integer like 8 or an h:30 string like "8:30"). Defaults to 7 when omitted. The astronomical engine uses the supplied timezone only for boundary rounding of the Solar↔Lunar date — the civil hour branch (chi giờ) is always derived from the user-supplied local clock time.
- **Calendar Boundaries:** The core calculations are stable for modern birth years, but traditional leap months (tháng nhuận) follow standard Vietnamese lunar calendar mappings (Hoang Nam Dia methodology) which might vary in historical or remote future years.
- **Calculations School (Phái):** Star distributions follow standard consensus calculations. Customizable star weight/distributions (different schools like Nam Phái vs. Bắc Phái vs. custom configurations) are not supported.
Accuracy, Methodology & Tradition Disclaimer
> [!NOTE]
> **Traditional Calculations Disclaimer:** Vietnamese "Tử Vi" is a highly rich astrological methodology with various traditional schools (e.g., Nam Phái vs. Bắc Phái). Calculation parameters, star rankings, element determinations, and interpretations may differ depending on the specific lineage or school. The output generated by this tool is calculated strictly according to standard consensus computational logic and should be treated as a computational reference rather than a definitive astrological interpretation.
Installation
You can install tuvi-mcp-server directly from PyPI:
Development & Contribution Setup
If you want to contribute to the package or run unit tests, set up a local development environment:
1. **Create Virtual Environment:**
2. **Install Package in Editable Mode:**
3. **Running Tests:**
Verify your local setup by running the test suite:
How to Run
1. Stdio Mode (Default for Claude Desktop & Cursor)
2. Streamable HTTP Mode (For Remote & Cloud Deployments)