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

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

功能特性

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

安装

通过 PyPI 安装（推荐）

pip install heimanhome-mcp

环境要求

• Python >= 3.12

从源码安装

# 克隆项目
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

配置示例

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

使用

启动服务

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

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

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

在 MCP 客户端中配置

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

{
  "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 进行代码格式化和静态检查：

# 格式化代码
ruff format src/

# 运行静态检查
ruff check src/

# 类型检查
mypy src/

测试

# 运行测试
pytest

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

异常处理

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

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

许可证

MIT

致谢

• Model Context Protocol
• 海曼智能家居平台