# midea-mcp

面向美的空调的本地单用户 MCP Server。MVP 使用 Python 3.12、MCP Python
SDK `>=1.27,<2` 和 stdio，公开七个工具：

- `list_devices`
- `get_device`
- `get_device_log`
- `refresh_device`
- `set_device_state`
- `discover_lan_devices`
- `diagnose_device`

## 设备状态日志

所有 `set_device_state` 调用都会写入 `data/device-log.jsonl`，包括请求字段、
Provider、五种写入状态、核验结果和失败原因。每次真实设备状态读取都会与上一份
持久化快照比较，并分别记录：

- `state_change`：开关、模式、设定温度；
- `sensor_change`：室内温度；
- `availability_change`：在线状态；
- `state_snapshot`：首次读取时建立的基线。

每条记录同时包含 UTC 和北京时间。通过 midea-mcp 写入后的读回带有同一个
`request_id`；其他入口造成的变化标记为 `external_unknown`。`observed_via=cloud`
只表示变化是通过云端读取发现的，不能证明操作来自美居 App。

读取最近日志：

```text
get_device_log(limit=50)
get_device_log(limit=50, field="mode")
get_device_log(limit=50, event_type="state_change")
```

可过滤字段为 `power`、`mode`、`target_temperature`、`current_temperature` 和
`online`，`limit` 范围为 1–500。日志只在真实状态读取发生时发现外部变化；
midea-mcp 本身不会后台轮询设备。

## 安全与一致性保证

- 每台逻辑设备使用 midea-mcp 内部 UUID。
- Cloud ID、LAN ID 和 keyed SN fingerprint 分别保存为 bindings，绝不假设
  Cloud ID 与 LAN ID 相同。
- 写入只返回 `rejected`、`not_delivered`、`delivery_unknown`、`accepted`
  或 `verified`。
- LAN 或 Cloud 写入投递结果不明时，只通过原 Provider 读取实际状态进行核验，
  绝不切换 Provider 或重发。
- Token/Key 使用 AES-256-GCM 加密落盘；日志和工具响应不返回明文凭证或原始 SN。
- 路由选择为“可用 LAN 优先；没有可用 LAN binding 时使用 Cloud”。一旦开始写入，
  本次请求就锁定 Provider。
- Cloud 支持空调状态读取及开关、模式、目标温度写入，并使用云端状态读回核验。

## 安装

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

如果系统没有 `py` 命令，直接使用 Python 3.12 可执行文件创建虚拟环境。

默认数据目录是当前目录下的 `data/`，可通过 `MIDEA_MCP_DATA_DIR` 修改。
首次启动会生成 `data/master.key`。生产使用时应备份密钥并限制文件访问权限；也可以
使用 `MIDEA_MCP_MASTER_KEY` 注入一个 URL-safe base64 编码的 32 字节密钥。

## Phase 0

### 1. 局域网扫描

```powershell
.\.venv\Scripts\midea-mcp.exe phase0
```

跨子网或广播受限时可指定设备 IP 或广播地址：

```powershell
.\.venv\Scripts\midea-mcp.exe phase0 --target 192.168.1.255
```

### 2. 导入旧 HA V3 凭证

`midea_ac_lan` 的单设备文件通常位于：

```text
<HA config>/.storage/midea_ac_lan/<device_id>.json
```

可导入单个文件、整个 `midea_ac_lan` 目录，也可导入 HA
`.storage/core.config_entries`：

```powershell
.\.venv\Scripts\midea-mcp.exe import-ha C:\path\to\123456789.json
```

导入器仅接受设备类型 `0xAC`、协议版本 V3，并将 Token/Key 立即加密后保存。

### 3. 可选的 Cloud 库存及 Token/Key 补取

不要把账号密码写入命令行历史：

```powershell
$env:MIDEA_ACCOUNT = "your-account"
$env:MIDEA_PASSWORD = "your-password"
$env:MIDEA_CLOUD_NAME = "美的美居"
.\.venv\Scripts\midea-mcp.exe sync-cloud
```

旧 Token API 正在被美的关闭，因此该步骤可能无法取得新凭证。已有 HA 凭证优先且
不会被云端候选覆盖。Cloud/LAN 只有在 SN fingerprint 唯一匹配时才合并为同一设备。

`sync-cloud` 同时会登记 Cloud binding。部署在无法访问家庭局域网的服务器时，应在
启动 MCP Server 前至少执行一次该命令；之后 `refresh_device` 和
`set_device_state` 会通过 Cloud 路由工作。

### 4. 加密备份

```powershell
.\.venv\Scripts\midea-mcp.exe backup-credentials C:\safe\midea.backup.json
.\.venv\Scripts\midea-mcp.exe restore-credentials C:\safe\midea.backup.json
```

备份使用独立口令通过 scrypt 派生密钥，再使用 AES-256-GCM 加密。

## 启动 MCP Server

```powershell
.\.venv\Scripts\midea-mcp-server.exe
```

客户端配置示例：

```json
{
  "mcpServers": {
    "midea": {
      "command": "C:\\path\\to\\midea-mcp\\.venv\\Scripts\\midea-mcp-server.exe",
      "env": {
        "MIDEA_MCP_DATA_DIR": "C:\\path\\to\\midea-mcp\\data"
      }
    }
  }
}
```

## 控制参数

`set_device_state` 只接受：

```json
{
  "device_id": "midea-mcp-internal-uuid",
  "changes": {
    "power": true,
    "mode": "cool",
    "target_temperature": 26
  }
}
```

模式为 `off / auto / cool / dry / heat / fan_only`，目标温度默认限制
为 17–30°C，步长 0.5°C。`power=false` 不能与模式或温度同时提交。

## 当前不做

- 热水器、烤箱及其他设备品类
- 场景和 `execute_scene`
- Home Assistant Provider
- 多用户或公网认证

## 测试

```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
```

测试使用模拟 Provider，不会控制真实设备。实机写入只通过显式调用
`set_device_state` 发生。

本次 Phase 0 与实机验收结果见 [PHASE0.md](PHASE0.md)。项目已发现并登记
一台 V3 空调，通过云端 Token API 候选完成 LAN 认证，并实际验证开关、模式
和温度控制。验收结束后设备已恢复为关机、25°C。

## Acknowledgments

- [wuwentao/midea_ac_lan](https://github.com/wuwentao/midea_ac_lan) — LAN 协议参考，MIT
- [sususweet/midea_auto_cloud](https://github.com/sususweet/midea_auto_cloud) — 云端 API 和设备映射，Apache-2.0
- [hasscc/meiju](https://github.com/hasscc/meiju) — 协议研究，Apache-2.0
- [Do1e/mijia-mcp](https://github.com/Do1e/mijia-mcp) — MCP 架构参考

Unofficial community project, not affiliated with Midea Group.