Metadata-Version: 2.4
Name: mingli-mcp
Version: 1.0.3
Summary: 命理MCP服务 - 支持紫微斗数、八字等多种命理系统
Author-email: spyfree <srlixin@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/spyfree/mingli-mcp
Project-URL: Repository, https://github.com/spyfree/mingli-mcp
Project-URL: Documentation, https://github.com/spyfree/mingli-mcp/blob/main/README.md
Project-URL: Issues, https://github.com/spyfree/mingli-mcp/issues
Keywords: mcp,ziwei,bazi,fortune,astrology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: py-iztro>=0.1.5
Requires-Dist: lunar_python>=1.4.7
Requires-Dist: bidict>=0.23.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Dynamic: license-file

# 命理MCP服务 (Mingli MCP Server)

一个支持多种命理系统（紫微斗数、八字、占星等）的 Model Context Protocol (MCP) 服务器，专为 AI 工具（如 Cursor IDE）设计。

## ✨ 特性

### 🎯 核心特性
- ✅ **多命理系统支持**: 采用插件化架构，轻松扩展新的命理系统
  - ✅ 紫微斗数（已实现）
  - ✅ 八字（已实现）⭐ **新增**
  - 🔄 西方占星（预留接口）
- ✅ **多传输方式**: 支持stdio、HTTP、WebSocket等多种传输协议
- ✅ **MCP标准兼容**: 完全兼容 MCP 协议规范
- ✅ **易于扩展**: 清晰的抽象层设计，添加新系统只需3步

### 🔮 紫微斗数功能
- ✅ **完整排盘**: 十二宫、主星、辅星、杂耀、四化等
- ✅ **运势查询**: 大限、流年、流月、流日、流时
- ✅ **宫位分析**: 深度分析特定宫位的星曜配置
- ✅ **多种历法**: 支持阳历和农历输入
- ✅ **格式化输出**: JSON和Markdown两种输出格式

### 🎴 八字功能 ⭐ **新增**
- ✅ **四柱排盘**: 年月日时四柱、天干地支详细信息
- ✅ **十神分析**: 比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印
- ✅ **五行分析**: 金木水火土分数、百分比、平衡度
- ✅ **地支藏干**: 详细的地支藏干信息
- ✅ **运势查询**: 大运、流年分析
- ✅ **缺失分析**: 自动识别五行缺失并给出建议
- ✅ **多种历法**: 支持阳历和农历输入

## 📋 可用工具

### 1. get_ziwei_chart
获取紫微斗数完整排盘信息

**参数**:
- `date` (string, 必需): 出生日期 YYYY-MM-DD，如 "2000-08-16"
- `time_index` (integer, 必需): 时辰序号 0-12
  - 0=早子时(23-01), 1=丑时(01-03), 2=寅时(03-05), 3=卯时(05-07)
  - 4=辰时(07-09), 5=巳时(09-11), 6=午时(11-13), 7=未时(13-15)
  - 8=申时(15-17), 9=酉时(17-19), 10=戌时(19-21), 11=亥时(21-23)
  - 12=晚子时(23-01)
- `gender` (string, 必需): 性别 "男" 或 "女"
- `calendar` (string, 可选): 历法 "solar"(阳历) 或 "lunar"(农历), 默认 "solar"
- `is_leap_month` (boolean, 可选): 是否闰月，默认 false
- `format` (string, 可选): 输出格式 "json" 或 "markdown", 默认 "markdown"

**示例**:
```json
{
  "date": "2000-08-16",
  "time_index": 2,
  "gender": "女",
  "calendar": "solar"
}
```

### 2. get_ziwei_fortune
获取紫微斗数运势信息

**参数**:
- `birth_date` (string, 必需): 出生日期
- `time_index` (integer, 必需): 时辰序号
- `gender` (string, 必需): 性别
- `calendar` (string, 可选): 历法类型
- `query_date` (string, 可选): 查询日期，不填则为今天
- `format` (string, 可选): 输出格式

### 3. analyze_ziwei_palace
分析紫微斗数特定宫位

**参数**:
- `birth_date` (string, 必需): 出生日期
- `time_index` (integer, 必需): 时辰序号
- `gender` (string, 必需): 性别
- `palace_name` (string, 必需): 宫位名称，可选值：
  - 命宫、兄弟、夫妻、子女、财帛、疾厄
  - 迁移、仆役、官禄、田宅、福德、父母
- `calendar` (string, 可选): 历法类型
- `format` (string, 可选): 输出格式

### 4. list_fortune_systems
列出所有可用的命理系统

### 5. get_bazi_chart ⭐ **新增**
获取八字（四柱）排盘信息

**参数**:
- `date` (string, 必需): 出生日期 YYYY-MM-DD
- `time_index` (integer, 必需): 时辰序号 0-12
- `gender` (string, 必需): 性别 "男" 或 "女"
- `calendar` (string, 可选): 历法 "solar"(阳历) 或 "lunar"(农历), 默认 "solar"
- `is_leap_month` (boolean, 可选): 是否闰月，默认 false
- `format` (string, 可选): 输出格式 "json" 或 "markdown", 默认 "markdown"

**示例**:
```json
{
  "date": "2000-08-16",
  "time_index": 2,
  "gender": "女"
}
```

**输出包含**:
- 四柱八字（年月日时）
- 天干地支详细信息
- 十神分析（比肩、劫财等）
- 五行分数统计
- 地支藏干信息
- 生肖、日主等基本信息

### 6. get_bazi_fortune ⭐ **新增**
获取八字运势信息

**参数**:
- `birth_date` (string, 必需): 出生日期
- `time_index` (integer, 必需): 时辰序号
- `gender` (string, 必需): 性别
- `calendar` (string, 可选): 历法类型
- `query_date` (string, 可选): 查询日期，不填则为今天
- `format` (string, 可选): 输出格式

**输出包含**:
- 当前年龄
- 大运信息（年龄范围、干支）
- 流年信息（年份、干支、生肖）
- 本命八字

### 7. analyze_bazi_element ⭐ **新增**
分析八字五行强弱

**参数**:
- `birth_date` (string, 必需): 出生日期
- `time_index` (integer, 必需): 时辰序号
- `gender` (string, 必需): 性别
- `calendar` (string, 可选): 历法类型
- `format` (string, 可选): 输出格式

**输出包含**:
- 日主及其五行属性
- 五行分数和百分比
- 最旺/最弱五行
- 缺失五行
- 平衡度评价
- 补救建议

## 🛠️ 安装和配置

### 环境要求
- Python 3.8+
- Cursor IDE 或其他支持MCP的工具

### 1. 克隆项目
```bash
cd /Users/lix18854/Documents/code
# 项目已在 ziwei_mcp 目录中
cd ziwei_mcp
```

### 2. 创建虚拟环境（推荐）
```bash
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows
```

### 3. 安装依赖
```bash
pip install -r requirements.txt
```

### 4. 配置环境变量（可选）
```bash
cp examples/config/.env.example .env
# 编辑 .env 文件根据需要调整配置
```

### 5. 测试运行
```bash
chmod +x mingli_mcp.py
python mingli_mcp.py
```

### 6. 配置 Cursor MCP

编辑或创建 `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mingli": {
      "command": "/Users/lix18854/Documents/code/ziwei_mcp/venv/bin/python",
      "args": ["/Users/lix18854/Documents/code/ziwei_mcp/mingli_mcp.py"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

> **注意**: 请根据实际路径调整 `command` 和 `args`

### 7. 重启 Cursor
重启 Cursor IDE 以加载新的 MCP 配置。

## 📁 项目结构

```
ziwei_mcp/
├── mingli_mcp.py              # MCP服务器主入口
├── config.py                  # 配置管理
├── requirements.txt           # Python依赖
├── pyproject.toml            # 项目配置
├── .gitignore                # Git忽略文件
├── README.md                 # 项目文档
│
├── core/                      # 核心抽象层
│   ├── __init__.py
│   ├── base_system.py        # 命理系统抽象基类
│   ├── birth_info.py         # 生辰信息数据模型
│   └── chart_result.py       # 排盘结果数据模型
│
├── transports/                # 传输层（支持多种传输方式）
│   ├── __init__.py
│   ├── base_transport.py     # 传输层抽象基类
│   └── stdio_transport.py    # stdio传输实现（默认）
│
├── systems/                   # 命理系统实现
│   ├── __init__.py           # 系统注册中心
│   ├── ziwei/                # 紫微斗数（已实现）
│   │   ├── __init__.py
│   │   ├── ziwei_system.py  # 系统实现
│   │   └── formatter.py     # 结果格式化
│   ├── bazi/                 # 八字（已实现）
│   │   ├── __init__.py
│   │   ├── bazi_system.py   # 系统实现
│   │   └── formatter.py     # 结果格式化
│   └── astrology/            # 占星（预留）
│       └── __init__.py
│
├── utils/                     # 工具函数
│   ├── __init__.py
│   ├── validators.py         # 参数验证
│   └── formatters.py         # 响应格式化
│
├── docs/                      # 文档
│   ├── README.md             # 文档索引
│   ├── guides/               # 用户指南
│   ├── deployment/           # 部署文档
│   ├── architecture/         # 架构设计
│   └── development/          # 开发文档
│
├── examples/                  # 示例配置
│   └── config/               # 配置文件示例
│       ├── .env.example
│       ├── codex_config.toml.example
│       └── cursor_mcp_config.example.json
│
├── scripts/                   # 脚本工具
│   ├── tests/                # 测试脚本
│   └── check_ready_to_publish.sh
│
└── tests/                     # 单元测试
    └── __init__.py
```

## 🚀 扩展新命理系统

本项目采用插件化架构，添加新命理系统只需3步：

### 步骤1: 创建系统类
在 `systems/` 下创建新目录，实现 `BaseFortuneSystem` 接口：

```python
# systems/bazi/bazi_system.py
from core.base_system import BaseFortuneSystem

class BaziSystem(BaseFortuneSystem):
    def get_system_name(self) -> str:
        return "八字"
    
    def get_chart(self, birth_info):
        # 实现八字排盘逻辑
        return {...}
    
    # 实现其他必需方法...
```

### 步骤2: 注册系统
在 `systems/__init__.py` 中注册：

```python
from .bazi import BaziSystem
register_system('bazi', BaziSystem)
```

### 步骤3: 添加MCP工具
在 `mingli_mcp.py` 的 `_handle_tools_list()` 中添加工具定义。

就这么简单！无需修改核心框架代码。

## 🔧 传输层扩展

当前默认使用 stdio 传输（适用于 Cursor）。未来可扩展：

### HTTP传输（预留）
```python
# transports/http_transport.py
class HttpTransport(BaseTransport):
    def __init__(self, host, port):
        # 实现HTTP服务器
        pass
```

### WebSocket传输（预留）
```python
# transports/ws_transport.py
class WebSocketTransport(BaseTransport):
    def __init__(self, host, port):
        # 实现WebSocket服务器
        pass
```

## 📚 使用示例

### 在 Cursor 中使用

1. **获取紫微排盘**:
```
帮我排一个紫微斗数盘：2000年8月16日，寅时，女性
```

2. **查询运势**:
```
查询2000年8月16日寅时出生的女性，今天的紫微运势
```

3. **分析宫位**:
```
分析上面这个人的命宫
```

### 编程调用

```python
from systems import get_system

# 获取紫微系统
ziwei = get_system('ziwei')

# 准备生辰信息
birth_info = {
    'date': '2000-08-16',
    'time_index': 2,  # 寅时
    'gender': '女',
    'calendar': 'solar'
}

# 获取排盘
chart = ziwei.get_chart(birth_info)
print(chart)

# 获取运势
from datetime import datetime
fortune = ziwei.get_fortune(birth_info, datetime.now())
print(fortune)

# 分析宫位
palace = ziwei.analyze_palace(birth_info, '命宫')
print(palace)
```

## 🧪 测试

```bash
# 运行测试（待实现）
pytest tests/

# 测试单个系统
python -m systems.ziwei.ziwei_system
```

## 📝 依赖说明

- **py-iztro**: 紫微斗数核心库，提供排盘算法
- **python-dotenv**: 环境变量管理
- **python-dateutil**: 日期处理

## 🗺️ 未来规划

- [ ] 完善八字系统实现
- [ ] 添加西方占星系统
- [ ] 实现合盘功能
- [ ] HTTP/WebSocket传输层
- [ ] 命理知识库集成
- [ ] AI解读功能
- [ ] 更多运势分析维度

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

## 📄 许可证

MIT License

## 🙏 致谢

- [iztro](https://github.com/SylarLong/iztro) - 紫微斗数 JavaScript 库
- [py-iztro](https://github.com/x-haose/py-iztro) - Python 移植版本
- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol 规范

---

**🔮 开始你的命理探索之旅！**
