# 明理 MCP 接口说明（v1.1）

> 八字 / 六爻 / 黄历三套能力，MCP + REST 双入口。
> 更新时间：2026-10-31

---

## 一、接入信息

| 项 | 值 |
|---|---|
| Base URL | `https://mingli.xiaoyi-ai.com` |
| MCP 端点 | `https://mingli.xiaoyi-ai.com/mcp` |
| MCP 传输 | **streamable-http**（POST，不是 SSE） |
| REST 前缀 | `https://mingli.xiaoyi-ai.com/api/` |
| 鉴权头 | `X-Api-Key: ml_1d8ebebdc6fed4fad31518fd7c624a4b6a4f39fbeaed578a` |
| 备选鉴权 | `Authorization: Bearer <同一个 Key>` |
| 端口 | 容器 9000，宿主 127.0.0.1:9010 |
| 数据 | 无数据库，纯计算 |

不带 Key 返回：

```json
{"code":40101,"message":"未授权：缺少或错误的 API Key","data":null}
```

---

## 二、MCP 客户端配置

```json
{
  "mcpServers": {
    "mingli": {
      "url": "https://mingli.xiaoyi-ai.com/mcp",
      "headers": {
        "X-Api-Key": "ml_1d8ebebdc6fed4fad31518fd7c624a4b6a4f39fbeaed578a"
      }
    }
  }
}
```

- 传输选 **streamable-http / HTTP**；
- 不要选 SSE，服务端没有 SSE 端点；
- `GET /mcp` 返回 **406** 属正常，健康检查请用 REST。

---

## 三、MCP 工具（8 个）

| 工具 | 说明 |
|---|---|
| `bazi_simple_calculate` | 四柱、五行分值、喜用神、大运、流年 |
| `bazi_liunian_calculate` | 逐流年（默认 10 年） |
| `bazi_remedy` | 颜色/方位/行业等补救建议 |
| `mingli_yearly_ai` | 单年度结构化年运 |
| `liuyao_scenes` | 56 个六爻场景 |
| `liuyao_divine` | 起卦、装卦、断卦 |
| `huangli_day` | 单日黄历 |
| `huangli_zeji` | 按事项择吉 |

---

## 四、REST 接口

所有接口均为 `POST`，请求体 JSON。

| 路径 | 对应工具 |
|---|---|
| `/api/bazi` | `bazi_simple_calculate` |
| `/api/bazi_liunian` | `bazi_liunian_calculate` |
| `/api/bazi_remedy` | `bazi_remedy` |
| `/api/mingli_yearly_ai` | `mingli_yearly_ai` |
| `/api/liuyao_scenes` | `liuyao_scenes` |
| `/api/liuyao_divine` | `liuyao_divine` |
| `/api/huangli_day` | `huangli_day` |
| `/api/huangli_zeji` | `huangli_zeji` |

### 4.1 八字排盘

```http
POST /api/bazi
X-Api-Key: <key>
Content-Type: application/json

{
  "birth_year": 1990,
  "birth_month": 1,
  "birth_day": 1,
  "birth_hour": 8,
  "gender": "男",
  "calendar_type": "solar",
  "birth_minute": 0,
  "city": "杭州",
  "province": "浙江"
}
```

返回主要字段：

```
birth_info
year_pillar / month_pillar / day_pillar / hour_pillar
wuxing_scores
ri_zhu_wuxing / ri_zhu_strength
xiyongshen
dayun_list
nianyun
solar_date / lunar_date
corrected_hour / longitude
```

说明：

- `gender` 只接受 `男/女`，也兼容 male/female；
- `calendar_type`：`solar` 或 `lunar`；
- 传 `city/province` 会做真太阳时校正；
- 23:00 出生按次日日柱处理。

### 4.2 流年

```json
{
  "birth_year": 1990, "birth_month": 1, "birth_day": 1,
  "birth_hour": 8, "gender": "男",
  "start_year": 2026, "num_years": 5
}
```

返回：`liunian[]`（每年含干支、十神、冲合、吉凶）、`nianyun[]`。

`num_years` 默认 10，最大建议 10。

### 4.3 补救建议

```json
{
  "day_master_wuxing": "火",
  "wangshuai": "偏弱",
  "yong_shen": ["木", "火"],
  "ji_shen": ["水", "金"]
}
```

返回：`basic`（颜色/方位/数字等）、`premium`（行业/饰品等）。

### 4.4 年度 AI 数据

```json
{
  "birth_year": 1990, "birth_month": 1, "birth_day": 1,
  "birth_hour": 8, "gender": "男", "target_year": 2026
}
```

返回中文结构：

```
命主基础 / 四柱 / 五行分值 / 喜忌 / 当年大运
流年数据 / 核心矛盾 / 原局冲刑害 / 健康提醒
```

### 4.5 六爻场景

```http
POST /api/liuyao_scenes
X-Api-Key: <key>
```

请求体可为空。返回：

```json
{"total": 56, "scenes": ["财运/求财", "事业/工作发展", "..."]}
```

### 4.6 六爻起卦

```json
{
  "yao_values": "1,2,3,0,1,2",
  "question": "今年求财如何",
  "scene": "财运/求财",
  "divine_date": "2026-10-31",
  "divine_hour": 12
}
```

**爻值必须是 0/1/2/3，不是 6/7/8/9：**

| 值 | 含义 |
|---|---|
| 0 | 老阴（动） |
| 1 | 少阳（静） |
| 2 | 少阴（静） |
| 3 | 老阳（动） |

返回：

```
ben_gua / hu_gua / bian_gua
yao_details[]（六亲、六神、世应、旺衰、动变）
yong_yao / shi_yao / ying_yao
verdict / analysis / suggestions / score / grade
geju_list / liushen_tips / yingqi / summary_points
```

### 4.7 黄历单日

```json
{"date_str": "2026-10-31"}
```

`date_str` 支持 `today/今天`、`tomorrow/明天`、`yesterday/昨天`、`YYYY-MM-DD`。

返回：`lunar/annual` 干支、`yi/ji`、`chong/sha`、`good_times`、`ji_shen/xiong_sha`、`level_label`。

### 4.8 择吉

```json
{
  "thing": "搬家",
  "start_date": "2026-11-01",
  "end_date": "2026-11-07",
  "zodiacs": "虎",
  "weekends_only": false
}
```

返回：

```
thing / start_date / end_date
total / daji_count / shangji_count / zhongji_count / xiaoji_count
days[]（日期、农历、干支、等级、吉时、宜）
```

> `total` 为区间内**筛出的吉日数**，不是区间总天数。

---

## 五、错误结构

MCP 工具参数错误时，返回 `isError=true`，错误文本形如：

```
Error executing tool bazi_simple_calculate: 性别 'x' 无效，仅允许 '男' 或 '女'
```

REST 参数/业务错误统一：

```json
{"code": 42201, "message": "性别 'x' 无效", "data": null}
```

| HTTP | code | 含义 |
|---|---|---|
| 401 | 40101 | 缺少/错误 API Key |
| 400 | 42201 | 参数错误 |
| 400 | 50001 | 请求体解析失败或内部异常 |
| 406 | — | GET /mcp，正常现象 |

---

## 六、限制

1. 无数据库，所有结果为即时计算；
2. 黄历按“节气月规则表”计算，不是按年快照；
3. `bazi_simple_calculate` 一次返回 100 年 `nianyun`，响应约 50KB；
4. `mingli_yearly_ai` 返回中文 key，与其他接口命名不统一；
5. 城市库缺失时静默跳过真太阳时校正；
6. REST 与 MCP 共用同一个 API Key，没有按调用方细分权限。

---

## 七、部署信息

| 项 | 值 |
|---|---|
| 服务器 | `121.43.251.164` |
| 目录 | `/opt/mingli-mcp` |
| 容器 | `mingli-mcp` |
| 端口 | `127.0.0.1:9010 → 9000` |
| 反向代理 | nginx `mingli.xiaoyi-ai.com` |
| 证书 | Let's Encrypt 自动续期 |
| 环境变量 | `/opt/mingli-mcp/.env` |

常用命令：

```bash
cd /opt/mingli-mcp
docker compose logs -f
docker compose restart
docker compose up -d --build
```