TuViMCP 是一个基于 Python 的 Model Context Protocol（MCP）服务器，专门用于计算和管理越南紫微斗数（Tử Vi）星盘。其设计目标是输出干净、结构化的 JSON 数据，使 LLM 智能体能够轻松读取、解读并向用户解释。
用途
该工具面向需要以编程方式生成、分析越南紫微斗数星盘的开发者与智能体应用。它既可作为 MCP 服务器供 LLM 客户端调用，也可作为 Python 库直接集成到脚本、笔记本或 Web 后端中。
主要能力
- 星盘生成：将阳历或阴历出生日期与时间转换为完整的紫微斗数星盘，包含天盘（Thiên Bàn）和地盘（Địa Bàn），共 12 宫和超过 100 颗星曜。
- 51 格局评估引擎：在生成星盘时自动识别全部 51 种传统格局（中州派 51 格局），返回匹配的格局及其描述、古歌（Cổ Ca）、评注（Bình Chú）和优缺点（Ưu/Khuyết điểm）。
- 高质量图片渲染：生成美观、可打印的星盘图片，按五行对文字着色（木绿、火红、土黄、金灰、水蓝），为 Tuần 和 Triệt 提供自定义徽章框，并用几何连线突出命宫与身宫的关系。
- 运限分析（Vận Hạn）：计算流曜（Lưu tinh），并映射任意目标年、月、日的活跃大限（Đại Hạn）、小限（Tiểu Hạn）、月限（Nguyệt Hạn）和日限（Nhật Hạn）。
- 吉日吉时查询：评估任意日历日期的黄道/黑道（Hoàng Đạo/Hắc Đạo）、12 建除（12 Trực）、28 宿（28 Tú）、节气（Tiết Khí）、出行方位和吉时。
- 本地持久化（Python 库）：内置 SQLite 数据库工具（tuvi_mcp.database），供 Python 库使用者保存、检索、列出和删除星盘档案。MCP 工具本身无状态，不需要数据库。
- 灵活时辰映射：自动将日历时间（如 "14:30"）或字符串名称（如 "Ngọ"、"Tý"）映射到正确的地支时辰索引。
- 本地内联（独立）：内部包含核心 ansaotuvi 计算逻辑，并带有自定义的 Tuần/Triệt 双宫修正。
使用方式
可通过 PyPI 安装 tuvi-mcp-server。开发与贡献设置：创建虚拟环境（python3 -m venv .venv），以可编辑模式安装包（.venv/bin/pip install --upgrade pip 和 .venv/bin/pip install -e ".[test]"），运行测试（.venv/bin/pytest）。可通过 HTTP 运行服务器（默认端口 1850），也可覆盖主机和端口。
工具 API 参考
所有工具均在 MCP 环境本地运行，无需外部认证或网络速率限制。
generate_horoscope：根据原始出生信息生成完整紫微星盘，可选高质量星盘图片渲染。参数包括 name（姓名，默认 "Khách"）、day（出生日 1-31）、month（出生月 1-12）、year（出生年）、hour_val（出生时辰，如 "14:30"、"Ngọ"、"Tý" 或地支索引 1-12）、gender_val（性别 "Nam" 或 "Nữ"，不区分大小写）、is_solar（True 为阳历，False 为阴历，默认 True）、current_year（可选，查看流曜/运限的年份，默认当前年）、generate_image（可选，是否生成并返回高质量星盘图片，默认 True）、timezone（可选，出生地民用时区 UTC 偏移，接受整数如 7、-5 或 h:30 字符串如 "7:30"、"-5:30"，默认 7 即越南 ICT）。若 generate_image 为 True，返回包含 [Image, chart_data] 的列表；若为 False，直接返回原始 JSON 字典 chart_data，包含 thien_ban（人口统计、四柱、五行、命）和 dia_ban（12 宫及星曜）键。计算失败时返回 {"error": "error_message"}。
get_van_han：计算目标时段的流年流曜和活跃宫位（大限、小限、月限、日限）。注意：current_year、current_month 和（若提供）current_day 代表阴历年、月、日。若要查看阳历时段（如 2026 年 10 月），必须先使用 convert_calendar 转换。参数包括出生参数（name、day、month、year、hour_val、gender_val、is_solar）、current_year（目标阴历年，默认当前年）、current_month（目标阴历月 1-12，默认 1）、current_day（可选，目标阴历日 1-30，启用日限）、timezone（可选，同 generate_horoscope）。返回包含 person_details（干支）、target_period（解析后的年龄和目标）、transit_stars、dai_han、tieu_han、nguyet_han 以及（若提供 current_day）nhat_han 的字典。输入无效时返回 {"error": "error_message"}。
convert_calendar：在阳历（Dương lịch）和阴历（Âm lịch）之间转换日期。参数包括 day、month、year、from_solar（True 为阳历转阴历，默认；False 为阴历转阳历）、lunar_leap（仅当 from_solar 为 False 时使用，若输入阴历月为闰月则为 True）、timezone（时区偏移，接受整数小时如 7、-5、9 或 h:30 字符串如 "7:30"、"-5:30"、"9:30"，默认 7）。若 from_solar 为 True，返回包含 lunar_day、lunar_month、lunar_year、lunar_leap 和格式化字符串日期的字典；若为 False，返回包含 solar_day、solar_month、solar_year 和格式化字符串日期的字典。日期参数验证失败时返回 {"error": "error_message"}。
check_auspicious_date：评估给定日期的吉日、吉时、12 建除、28 宿、节气和出行方位。参数包括 day（可选，默认今天）、month（可选，默认当前月）、year（可选，默认当前年）、is_solar（可选，True 为阳历，默认；False 为阴历）、timezone（可选，同 generate_horoscope）。返回包含 duong_lich、am_lich、can_chi_ngay、ngay_hoang_dao、truc_ngay、nhi_thap_bat_tu、huong_xuat_hanh、gio_hoang_dao、tiet_khi_hien_tai、tiet_khi_tiep_theo 的字典。
Python 库 API
除 MCP 服务器外，tuvi-mcp-server 还提供类型化、易用的 Python API，可直接在脚本、笔记本或 Web 后端中使用。MCP 工具封装的就是同一个库，因此无论调用 Horoscope.from_birth(...).chart() 还是从 MCP 客户端调用 generate_horoscope 工具，行为完全一致。
适用场景
- 为 LLM 智能体提供越南紫微斗数星盘计算与解读能力。
- 开发者构建命理类应用、网站或聊天机器人。
- 需要批量生成、分析或管理星盘档案的场景。
- 查询吉日吉时以安排婚礼、开业、动土、出行等活动。
限制
- 时区：计算默认使用越南本地时区（GMT+7）。其他出生地需显式传入时区（timezone 接受整数如 8 或 h:30 字符串如 "8:30"），省略时默认为 7。天文引擎仅将提供的时区用于阳历↔阴历日期的边界取整，民用时辰（chi giờ）始终由用户提供的本地时钟时间推导。
- 日历边界：核心计算对现代出生年份稳定，但传统闰月（tháng nhuận）遵循标准越南阴历映射（Hoang Nam Dia 方法），在历史或遥远未来年份可能有所不同。
- 流派（Phái）：星曜分布遵循标准共识计算。不支持自定义星曜权重/分布（如南派、北派或自定义配置）。
- 准确性、方法论与传统免责声明：越南紫微斗数是一种非常丰富的占星方法论，存在多种传统流派（如南派与北派）。计算参数、星曜等级、五行判定和解读可能因具体传承或流派而异。本工具输出严格按标准共识计算逻辑生成，应视为计算参考，而非权威占星解读。
