Metadata-Version: 2.4
Name: heimanhome-mcp
Version: 0.1.1
Summary: 海曼智能家居平台 MCP (Model Context Protocol) 服务端实现
Author: Heiman Team
License: MIT
License-File: LICENSE
Keywords: heiman,iot,mcp,smart-home
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: starlette>=0.40.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 海曼智能家居平台 MCP 服务端

[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/heimanhome-mcp)](https://pypi.org/project/heimanhome-mcp/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 标准，将海曼智能家居平台的 RESTful API 能力封装为结构化的 MCP Tools，使 AI Agent 能够无缝调用海曼平台的用户管理、家庭管理、设备管理、场景联动、消息中心、分组管理等核心能力。

## 功能特性

- **完整 API 覆盖**：封装了海曼平台用户、家庭、房间、设备、场景、消息、分组、反馈等全部核心模块
- **多环境支持**：支持测试环境、国内环境、欧洲环境的灵活切换
- **标准化接口**：所有 API 均注册为 MCP Tools，具备清晰的命名、描述和输入参数 Schema
- **健壮性保障**：统一的异常处理、日志记录、超时重试机制
- **类型安全**：基于 Pydantic 的数据模型定义，确保请求和响应的类型安全

## 安装

### 通过 PyPI 安装（推荐）

```bash
pip install heimanhome-mcp
```

### 环境要求

- Python >= 3.12

### 从源码安装

```bash
# 克隆项目
git clone <repository-url>
cd heimanhome-mcp

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

# 安装依赖
pip install -e ".[dev]"
```

## 配置

### 环境变量

在项目根目录创建 `.env` 文件，或设置以下环境变量：

| 变量名 | 必填 | 说明 | 示例 |
|--------|------|------|------|
| `HEIMAN_TOKEN` | 是 | Bearer Token 认证令牌 | `eyJhbGciOiJIUzI1NiJ9...` |
| `HEIMAN_ENV` | 否 | 环境标识（test/cn/eu） | `cn`（默认） |
| `HEIMAN_TIMEOUT` | 否 | HTTP 请求超时（秒） | `30`（默认） |
| `HEIMAN_RETRIES` | 否 | 请求失败重试次数 | `3`（默认） |
| `HEIMAN_PAGE_SIZE` | 否 | 默认分页大小 | `50`（默认） |

### 环境说明

| 环境 | `HEIMAN_ENV` 值 | Base URL |
|------|------------------|----------|
| 测试环境 | `test` | `http://192.168.1.14:9900` |
| 国内环境 | `cn` | `https://api.heiman.cn` |
| 欧洲环境 | `eu` | `https://spapi.heiman.cn` |

### 配置示例

```bash
# .env
HEIMAN_TOKEN=your_bearer_token_here
HEIMAN_ENV=cn
HEIMAN_TIMEOUT=30
HEIMAN_RETRIES=3
```

## 使用

### 启动服务

```bash
# 方式1：使用 Python 模块启动
python -m heiman_mcp

# 方式2：使用 pip 安装后的命令行入口
heiman-mcp

# 方式3：直接运行 server 模块
python -m heiman_mcp.server
```

### 在 MCP 客户端中配置

在支持 MCP 的客户端（如 Claude Desktop、Cursor 等）中配置：

```json
{
  "mcpServers": {
    "heiman-mcp": {
      "command": "python",
      "args": ["-m", "heiman_mcp"],
      "env": {
        "HEIMAN_TOKEN": "your_bearer_token_here",
        "HEIMAN_ENV": "cn"
      }
    }
  }
}
```

## MCP Tools 列表

### 用户管理

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_get_user_list` | 分页查询用户列表 |
| `heiman_get_current_user` | 获取当前登录用户信息 |
| `heiman_update_user_info` | 更新用户信息（昵称、头像、推送设置等） |
| `heiman_get_user_by_account` | 根据账号查找用户 |
| `heiman_update_user_password` | 修改用户密码 |

### 家庭管理

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_get_home_list` | 获取用户家庭列表 |
| `heiman_create_home` | 创建新家庭 |
| `heiman_update_home` | 更新家庭信息 |
| `heiman_delete_home` | 删除家庭 |
| `heiman_get_home_detail` | 获取家庭详情 |
| `heiman_init_create_home` | 初始化创建家庭 |

### 房间管理

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_create_room` | 创建房间 |
| `heiman_update_room` | 更新房间信息 |
| `heiman_delete_room` | 删除房间 |
| `heiman_batch_delete_rooms` | 批量删除房间 |
| `heiman_get_room_list` | 查询房间列表 |
| `heiman_get_room_detail` | 查询房间详情 |
| `heiman_bind_devices_to_room` | 设备批量绑定到房间 |
| `heiman_get_room_area_list` | 获取房间区域枚举 |
| `heiman_get_room_type_list` | 获取房间类型枚举 |

### 设备管理

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_get_device_list` | 获取设备列表 |
| `heiman_bind_device` | 绑定设备到家庭 |
| `heiman_check_device` | 检测设备是否可以绑定 |
| `heiman_unbind_device` | 解绑设备 |
| `heiman_update_device` | 修改设备信息 |
| `heiman_set_device_nickname` | 修改设备昵称 |
| `heiman_get_device_detail` | 查询设备详情 |
| `heiman_get_device_info` | 查询设备信息 |
| `heiman_execute_device_network` | 发起设备配网 |
| `heiman_query_product_model` | 查询产品物模型 |
| `heiman_query_device_model` | 查询设备物模型 |

### 场景联动

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_create_scene` | 创建场景联动 |
| `heiman_update_scene` | 更新场景 |
| `heiman_delete_scene` | 删除场景 |
| `heiman_batch_delete_scenes` | 批量删除场景 |
| `heiman_get_scene` | 获取场景详情 |
| `heiman_switch_scene` | 启用/禁用场景 |
| `heiman_preview_scene` | 预览执行场景 |
| `heiman_get_scenes_by_device` | 根据设备查询场景 |

### 消息中心

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_query_push_messages` | 查询消息推送记录（告警日志） |
| `heiman_query_push_messages_by_device` | 根据设备查询消息 |
| `heiman_delete_message_records` | 删除消息记录 |
| `heiman_set_messages_read` | 设置消息已读 |
| `heiman_has_unread_messages` | 检查未读消息 |
| `heiman_query_system_notifies` | 查询系统通知 |

### 分组管理

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_create_group` | 创建分组 |
| `heiman_update_group` | 更新分组 |
| `heiman_delete_group` | 删除分组 |
| `heiman_get_group` | 获取分组详情 |
| `heiman_get_group_page` | 分页查询分组 |
| `heiman_reorder_group` | 重新排序分组 |

### 意见反馈

| Tool 名称 | 说明 |
|-----------|------|
| `heiman_create_feedback` | 新增意见反馈 |
| `heiman_update_feedback` | 更新反馈状态 |
| `heiman_delete_feedback` | 删除反馈 |
| `heiman_batch_delete_feedback` | 批量删除反馈 |
| `heiman_get_feedback_list` | 查询反馈列表 |
| `heiman_check_feedback_state` | 检查未读反馈 |

## 项目结构

```
src/heiman_mcp/
├── __init__.py          # 包初始化
├── __main__.py          # 模块入口
├── server.py            # MCP 服务主入口
├── config.py            # 环境配置管理
├── client/
│   ├── __init__.py
│   ├── base.py          # HTTP 客户端基类
│   └── heiman.py        # 海曼 API 客户端
├── models/
│   ├── __init__.py
│   └── common.py        # Pydantic 数据模型
├── tools/
│   ├── __init__.py
│   ├── user_tools.py    # 用户管理 Tools
│   ├── home_tools.py    # 家庭管理 Tools
│   ├── room_tools.py    # 房间管理 Tools
│   ├── device_tools.py  # 设备管理 Tools
│   ├── message_tools.py # 消息中心 Tools
│   ├── scene_tools.py   # 场景联动 Tools
│   ├── group_tools.py   # 分组管理 Tools
│   └── feedback_tools.py # 意见反馈 Tools
└── exceptions/
    ├── __init__.py
    └── errors.py        # 自定义异常类
```

## 开发

### 代码风格

项目使用 Ruff 进行代码格式化和静态检查：

```bash
# 格式化代码
ruff format src/

# 运行静态检查
ruff check src/

# 类型检查
mypy src/
```

### 测试

```bash
# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=heiman_mcp --cov-report=html
```

## 异常处理

服务实现了统一的异常处理机制：

- **`HeimanClientError`**：客户端基础异常
- **`HeimanNetworkError`**：网络请求异常（自动重试）
- **`HeimanAuthError`**：认证异常（Token 失效等）
- **`HeimanAPIError`**：API 业务异常（返回 status != 200）
- **`HeimanServerError`**：服务端异常（HTTP >= 500）

## 许可证

[MIT](LICENSE)

## 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [海曼智能家居平台](https://www.heiman.cn/)
