# 命盘 MCP Server

**简体中文（主文档）** | [English](README.en.md) | [日本語](README.ja.md)

[![Version](https://img.shields.io/badge/version-0.1.8-blue.svg)](https://github.com/ChesterRa/mingpan)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

**命盘（Mingpan）** 是一个开源的中华传统术数 MCP 计算引擎，为 AI 应用提供命理排盘与占卜起卦能力。BaziWei 同时维护可直接使用的官方远程服务。

## 立即使用官方 MCP

将下面的端点添加到支持 Remote MCP / Streamable HTTP 的 AI 客户端：

```text
https://mingpan.bzwai.com/mcp
```

无需安装 Node.js，也无需自行部署服务器。添加后可以直接尝试：

> 请帮我排一个八字命盘，1992年4月12日7点30分，男性

> 请帮我起一个奇门遁甲时盘，2024年6月21日10点

先访问 [Mingpan 开源项目网站](https://mingpan.bzwai.com) 可查看能力范围与连接说明。官方服务由 [BaziWei](https://bzwai.com) 维护；源代码与计算口径继续在本仓库公开，方便审阅、复现与共同改进。

## 特性

-  **MCP 原生**：无缝集成 Claude Desktop 及 Claude Code
- 🌏 **中文输出**：以简体为主，术语保持传统
- 📊 **结构化文本**：便于 AI 理解与分析的格式
- 🕐 **多时区支持**：海外出生/起卦时间自动换算为北京时间排盘

## 使用方式

| 形态 | 适用 | 用法 |
| ---- | ---- | ---- |
| **官方远程 MCP**（推荐） | 支持 Remote MCP / Streamable HTTP 的 AI 客户端 | 添加 `https://mingpan.bzwai.com/mcp` |
| **本地 stdio MCP** | 本地开发、离线使用或要求资料不离开设备 | 见下方可选配置 |

官方远程服务使用无状态纯计算：不建立命盘数据库，不缓存或记录出生参数与命盘结果。若要求资料完全不离开设备，可选择本地 stdio 形态。

## 本地运行（可选）

### Claude Desktop

找到配置文件并添加以下内容：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mingpan": {
      "command": "npx",
      "args": ["-y", "mingpan"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add mingpan -- npx -y mingpan
```

### 验证

配置完成后重启客户端，然后尝试：

> 请帮我排一个八字命盘，1992年4月12日7点30分，男性

> 请帮我起一个奇门遁甲时盘，2024年6月21日10点

## 工具列表

### 命理排盘

命理学基于出生时间推算人生运势，属于「命」的范畴。

#### 八字命理

| 工具           | 说明                                       |
| -------------- | ------------------------------------------ |
| `bazi_basic`   | 八字四柱排盘（干支纳音、天干/藏干十神、十二长生自坐、命宫/胎元、旬空、公农历对照；五行/格局/用神由 AI 分析） |
| `bazi_dayun`   | 大运列表（十年一运）                       |
| `bazi_liunian` | 流年列表（指定年份范围）                   |
| `bazi_liuyue`  | 流月列表（节气月，立春起算）               |
| `bazi_liuri`   | 流日列表（指定月份内每日）                 |

#### 紫微斗数

| 工具             | 说明                                     |
| ---------------- | ---------------------------------------- |
| `ziwei_basic`    | 紫微命盘排盘（十二宫、主星、辅星、五行局/命主/身主、四化） |
| `ziwei_daxian`   | 大限列表（十年一限）                     |
| `ziwei_xiaoxian` | 小限列表（每年一宫）                     |
| `ziwei_liunian`  | 流年列表（指定年份范围）                 |
| `ziwei_liuyue`   | 流月列表（农历月）                       |
| `ziwei_liuri`    | 流日列表（农历日）                       |

### 历法原语

历法计算是所有术数的公共地基，也可独立使用。

| 工具             | 说明                                         |
| ---------------- | ---------------------------------------------- |
| `jieqi_query`    | 二十四节气精确时刻查询（精确到秒，北京时间） |
| `calendar_convert` | 公历/农历互转（含闰月、干支年月日、生肖）  |

节气是天文事件（AI 无法推算，如 2025 年立春是 2 月 3 日 22:10 而非 2 月 4 日），
农历闰月分配无简单规律（AI 经常猜错）——两者是本产品确定性计算的核心价值。

### 占卜起卦

占卜术基于起卦时间或随机数推演卦象，属于「卜」的范畴。

#### 六爻

| 工具           | 说明                                                |
| -------------- | --------------------------------------------------- |
| `liuyao_basic` | 六爻排盘（本卦/变卦、纳甲、六亲、六神、世应、旬空、伏神/飞神、进退神、旺衰） |

六爻输入为六个爻值（自下而上）：
- 6 = 老阴（动爻，阴变阳）
- 7 = 少阳（静爻）
- 8 = 少阴（静爻）
- 9 = 老阳（动爻，阳变阴）

#### 梅花易数

| 工具           | 说明                                     |
| -------------- | ---------------------------------------- |
| `meihua_basic` | 梅花易数排盘（本卦/变卦/互卦、体用分析） |

支持两种起卦方式：
- 时间起卦：根据农历年月日时计算
- 数字起卦：根据两个数字计算

爻位统一**自下而上**编号 1–6；变卦反转指定动爻，互卦取本卦第 2、3、4 爻为下卦，第 3、4、5 爻为上卦。依据为《梅花易数》卷一的[八卦象例、爻以六除与互卦起例](https://zh.wikisource.org/wiki/梅花易數/卷一)。当前实现对乾、坤也按相同爻位取互；未采用原文另述的“乾坤无互，互其变卦”分支。

**0.1.8 修复**：[Issue #2](https://github.com/ChesterRa/mingpan/issues/2) 指出的爻序映射错误会影响旧版的变卦和互卦。按上述取互规则，64 卦 × 6 动爻中有 256 个变卦结果、64 卦中有 60 个互卦结果需要纠正。时间与数字起卦均受影响；本卦、动爻编号与本卦体用关系不变，输入参数和文本结构兼容。升级后，依赖旧互变卦的解读需重新计算后复核。

#### 大六壬

| 工具             | 说明                                             |
| ---------------- | -------------------------------------------------- |
| `daliuren_basic` | 大六壬排盘（天地盘、四课、三传、十二天将、神煞） |

大六壬为三式之首。**推荐直接输入公历起课时间**（year/month/day/hour），
节气、月将、日干支、时干支由系统自动推得（LLM 手推干支极易出错）。
也可显式指定 `jieqi`/`dayGanZhi`/`hourGanZhi`（专家模式，向后兼容）。

#### 奇门遁甲

| 工具            | 说明 |
| --------------- | ---- |
| `qimen_basic`   | 奇门遁甲排盘（九宫布局、三奇六仪、八门九星八神、格局检测） |
| `qimen_yongshen`| 奇门用神分析（按事类选取用神，含主客、旺衰、空亡、入墓等确定性信息） |

奇门遁甲为三式之一，盘式与规则主要参考张志春《神奇之门》，支持：时盘/日盘/月盘/年盘、转盘/飞盘、拆补法/茅山法。



## 输出示例（bazi_basic）

```text
=== 命主資料 ===
性別：男
公曆：1992-04-12 07:30:00
農曆：壬申年三月初十辰時

=== 八字命盤 ===
年柱：壬申（剑锋金）  月柱：甲辰（覆灯火）  日柱：戊午（天上火）  時柱：丙辰（沙中土）
日柱旬空：子丑
命宮：己酉　胎元：乙未
天干十神：年干水=偏財　月干木=七殺　時干火=偏印
藏干十神（※本氣）：年申[庚食神※ 壬偏財 戊比肩]　月辰[戊比肩※ 乙正官 癸正財]　日午[丁正印※ 己劫財]　時辰[戊比肩※ 乙正官 癸正財]
十二長生（自坐）：年长生　月衰　日帝旺　時冠带
```

只包含确定性排盘信息；五行强弱、格局、用神等解读由 AI 依据盘面自行分析。

## 输入参数

### 命理工具（八字/紫微）

| 参数      | 类型    | 必填 | 说明                         |
| --------- | ------- | ---- | ---------------------------- |
| year      | number  | ✓    | 出生年份（1900-2100）        |
| month     | number  | ✓    | 出生月份（1-12）             |
| day       | number  | ✓    | 出生日期（1-31）             |
| hour      | number  | ✓    | 出生时辰（0-23）             |
| minute    | number  |      | 出生分钟（0-59），默认 0     |
| gender    | string  | ✓    | `male` / `female`            |
| longitude | number  |      | 出生地经度，用于真太阳时校正 |
| isLunar   | boolean |      | 是否为农历输入，默认 false   |
| timezone  | string  |      | IANA 时区名（如 `America/New_York`），默认北京时间 |

### 时区说明（v0.1.4+）

- 输入时间默认按**北京时间**排盘
- 海外出生/起卦时提供 `timezone` 参数，系统将当地墙钟时间换算为北京时间后计算
- 输入侧使用 IANA 时区数据库（正确处理各国历史夏令时，如 1986-1991 年中国夏令时）
- 内部规范表示为 UTC+8 平太阳时，与历法换算口径一致

### 占卜工具（六爻/梅花/大六壬）

- 六爻/梅花：输入起卦时间（支持 `timezone`），爻值/卦数由调用方提供
- 大六壬：**推荐直接输入公历时间**，节气与干支自动推得；也可显式指定（专家模式）

### 奇门遁甲工具

| 参数         | 类型    | 必填 | 说明 |
| ------------ | ------- | ---- | ---- |
| year         | number  | ✓    | 起盘年份（1900-2100） |
| month        | number  | ✓    | 起盘月份（1-12） |
| day          | number  | ✓    | 起盘日期（1-31） |
| hour         | number  | ✓    | 起盘时辰（0-23） |
| minute       | number  |      | 分钟（0-59），默认 0 |
| isLunar      | boolean |      | 是否为农历输入，默认 false |
| timezone     | string  |      | IANA 时区名，默认北京时间 |
| panType      | string  |      | `时盘` / `日盘` / `月盘` / `年盘`，默认 `时盘` |
| panStyle     | string  |      | `转盘` / `飞盘`，默认 `转盘` |
| zhiRunMethod | string  |      | `chaibu`（拆补法）/ `maoshan`（茅山法），默认 `chaibu` |

## 月份基准说明

| 系统 | 月份基准           | 日期基准 |
| ---- | ------------------ | -------- |
| 八字 | 节气月（立春起算） | 公历日   |
| 紫微 | 农历月（初一起算） | 农历日   |

## 开发

```bash
git clone https://github.com/ChesterRa/mingpan.git
cd mingpan
npm ci
npm run check                 # 构建 + 完整测试
npm run deploy:worker:dry-run # 只验证 Worker 打包，不部署
npm run dev  # 监听变化
```

## 依赖

| 库                          | 用途             |
| --------------------------- | ---------------- |
| `@modelcontextprotocol/server` | MCP v2 服务端协议实现 |
| `@modelcontextprotocol/client` | MCP v2 协议集成测试   |
| `lunar-javascript`          | 农历/公历转换    |
| `iztro`                     | 紫微斗数计算引擎 |
| `zod`                       | 输入参数校验     |

## 路线图

- [x] 八字基础排盘与时运列表
- [x] 紫微基础排盘与时运列表
- [x] 六爻排盘
- [x] 梅花易数排盘
- [x] 大六壬排盘
- [x] 奇门遁甲排盘
- [x] 大六壬时间起课（自动推节气/干支）
- [x] 多时区支持（timezone 参数）
- [x] 奇门口径修正（拆补符头、地盘布局、转盘星门，参照《神奇之门》与 kinqimen 交叉验证）
- [x] 排盘完整性对称盘点（八字补纳音/藏干十神/十二长生/命宫胎元，紫微补五行局/命主/身主）
- [x] 输出契约测试全覆盖 + 权威用例金样本（历史人物记载、立春分钟级边界、iztro 适配保真）

## 版本历史

| 版本 | 说明 |
| ---- | ---- |
| [0.1.8](docs/release-notes-0.1.8.md) | **梅花正确性修复**：统一八卦爻序与反向映射，纠正变卦和互卦；独立位运算穷举 384 种变卦与 64 种互卦，补齐 MCP、HTTP 与构建后 stdio 回归；感谢 [@1270643866](https://github.com/1270643866) 的详细报告 |
| 0.1.7 | **官方托管服务**：`mingpan.bzwai.com` 产品站与 `/mcp` 同仓、同版本、同一 Worker 发布；生产域名、无状态隐私边界、Host/Origin、请求体、限流与现代 MCP 协议烟雾测试完成收口；测试 300 |
| 0.1.6 | **MCP SDK v2 迁移**（2026-07-28 无状态协议，原生支持 Cloudflare Workers，向后兼容旧客户端）；远程 HTTP 入口从 50 行简化为 20 行（createMcpHandler）；Workers 打包 gzip 638→606KB；测试 288 |
| 0.1.5 | **口径裁决**：子初换日（23:00 起日柱时柱同属次日，全五系统统一）；起运权威化（lunar 节气表 + 交运日历定位）；奇门年盘按《遁甲演义》典籍修正；真太阳时四柱全量生效；**新能力**：历法原语层（jieqi_query + calendar_convert）；测试 218→288 |
| 0.1.4 | **正确性修复**：八字立春换年、奇门四类口径修正、stdio 日志修复；**输出定位确立**：只输出确定性排盘量；大六壬时间起课、多时区；测试 117→218 |
| 0.1.3 | 奇门用神分析与择日 |
| 0.1.2 | 六爻、梅花易数、大六壬 |
| 0.1.0 | 首个发布：八字、紫微 |

## 许可证

Apache License 2.0