tuya-iot-mcp-server

AI-student2024/tuya-iot-mcp-server

3.1

If you are the rightful owner of tuya-iot-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

涂鸦IoT MCP服务器是一个基于Model Context Protocol (MCP) 的平台服务器，专为涂鸦IoT设备提供全面的管理和控制功能。

涂鸦IoT MCP服务器

一个基于Model Context Protocol (MCP) 的涂鸦IoT平台服务器，提供设备管理、空间管理、联动规则和产品品类管理等功能的完整API接口。

🌟 功能特性

设备管理

  • ✅ 设备列表查询 - 获取项目下的所有设备，支持筛选和分页
  • ✅ 设备详情查询 - 获取设备的详细信息
  • ✅ 设备状态监控 - 实时获取设备当前状态（已优化API端点）
  • ✅ 设备规格属性 - 获取设备的完整规格属性（功能点和状态点）
  • ✅ 设备控制指令集 - 获取设备支持的控制指令集
  • ✅ 设备远程控制 - 支持下发指令到设备（已修复请求格式）

空间管理

  • ✅ 空间列表查询 - 获取项目下的空间结构
  • ✅ 空间详情查询 - 获取空间的详细信息
  • ✅ 空间设备列表 - 获取指定空间下的设备列表（⭐ 新增，支持递归查询）
  • ✅ 空间搜索功能 - 根据关键词搜索空间

联动规则管理

  • ✅ 联动规则查询 - 获取指定空间的联动规则
  • ✅ 智能规则查找 - 通过关键词智能查找和触发联动规则

产品品类管理 ⭐ 新增功能

  • ✅ 品类列表查询 - 获取涂鸦IoT平台支持的产品品类信息
  • ✅ 分类筛选功能 - 按分类筛选产品品类
  • ✅ 关键词搜索 - 支持关键词搜索产品品类
  • ✅ 可用分类列表 - 获取所有可用的产品分类
  • ✅ 单个品类添加 - 添加单个产品品类到数据库
  • ✅ 批量品类添加 - 批量添加多个产品品类
  • ✅ 品类统计信息 - 获取品类管理统计信息

🚀 快速开始

环境要求

  • Python 3.10+
  • 涂鸦IoT平台账号和API密钥

安装依赖

# 克隆项目
git clone <repository-url>
cd mcp-test/tuya-iot

# 激活虚拟环境
source .venv/Scripts/activate  # Windows
# source .venv/bin/activate     # Linux/Mac

# 安装依赖
pip install -e .

配置环境变量

创建 .env 文件并配置以下参数：

# 涂鸦IoT平台配置
TUYA_CLIENT_ID=your_client_id_here
TUYA_CLIENT_SECRET=your_client_secret_here

# 数据中心区域 (可选，默认CN)
# 可选值: CN(中国), US(美西), EU(中欧), IN(印度)
TUYA_REGION=CN

# 请求超时时间 (可选，默认30秒)
TUYA_TIMEOUT=30

# 调试模式 (可选，默认false)
TUYA_DEBUG=true

获取API密钥

  1. 登录 涂鸦IoT平台
  2. 创建或选择您的项目
  3. 在项目设置中获取 Client ID 和 Client Secret
  4. 将获取的信息填入 .env 文件

📖 API接口文档

设备管理接口

1. 获取设备列表
get_device_list(page_size=20, product_ids="", categories="", last_id="")

参数:

  • page_size: 每页数量，默认20，最大100
  • product_ids: 产品ID列表，用逗号分隔
  • categories: 设备类型筛选
  • last_id: 分页游标
2. 获取设备详情
get_device_detail(device_id)

参数:

  • device_id: 设备ID
3. 获取设备状态 ⭐ 已优化
get_device_status(device_id)

参数:

  • device_id: 设备ID 新特性:
  • 使用优化的API端点 /v1.0/iot-03/devices/{device_id}/status
  • 支持空调模式和风速的中文显示
  • 智能状态值映射（温度、湿度、开关状态等）

示例输出:

设备 vdevo168956543331751 当前状态:
  switch: [开启]
  temp_set: 25°C
  mode: 制冷模式
  fan_speed_enum: 健康模式
  switch_vertical: [开启]
  switch_horizontal: [开启]
  display: [是]
4. 获取设备功能
get_device_functions(device_id)

参数:

  • device_id: 设备ID
5. 获取设备规格属性
get_device_specification(device_id)

参数:

  • device_id: 设备ID 功能: 获取设备的完整规格属性，包括功能点(functions)和状态点(status)
6. 获取设备控制指令集
get_device_ctrlCommands(device_id)

参数:

  • device_id: 设备ID 功能: 获取设备支持的控制指令集，用于设备控制操作
7. 下发指令到设备 ⭐ 已修复
control_device_new(device_id, code, input_params)

参数:

  • device_id: 设备ID
  • code: 指令码（通常为"action"）
  • input_params: 输入参数，JSON字符串格式 功能: 向设备下发控制指令（已修复请求格式）

使用示例:

# 开启设备
control_device_new("device_id", "action", '{"switch":"true"}')

# 设置空调温度
control_device_new("device_id", "action", '{"temp_set":25}')

# 设置工作模式
control_device_new("device_id", "action", '{"mode":"cold"}')

# 设置风速
control_device_new("device_id", "action", '{"fan_speed_enum":"health"}')

空间管理接口

8. 获取空间列表
get_space_list(space_id="", only_sub=True, page_size=20, last_row_key="")

参数:

  • space_id: 目标空间ID，为空则查询根目录
  • only_sub: 是否仅查询直接子节点
  • page_size: 页面大小
  • last_row_key: 分页游标
9. 获取空间详情
get_space_detail(space_id)

参数:

  • space_id: 空间ID 功能: 获取空间的详细信息
10. 获取空间下的设备列表 ⭐ 新增功能
get_space_device_list(space_id, is_recursion=False, product_ids="", categories="", last_id="", page_size=20)

功能说明:

  • 查询指定空间ID下的所有设备
  • 支持递归查询子空间设备
  • 支持按产品ID和设备类型筛选
  • 支持分页查询

参数:

  • space_id: 空间ID（必填）- 如：160110452
  • is_recursion: 是否递归子空间，默认false
    • false: 仅查询当前空间下的设备
    • true: 查询当前空间及所有子空间下的设备
  • product_ids: 产品ID列表，以英文逗号分隔，不超过5个（可选）
  • categories: 设备的产品品类列表，以英文逗号分隔，不超过5个（可选）
  • last_id: 上一页返回的最后一个设备ID，第一页不传（可选）
  • page_size: 分页页面大小，最大20，默认20（必填）

返回数据:

  • 设备基本信息：名称、ID、UUID、类型、产品信息
  • 在线状态：实时在线/离线状态
  • 网络信息：IP地址、本地密钥
  • 位置信息：经纬度、时区、绑定空间ID
  • 时间信息：创建时间、激活时间
  • 其他信息：图标、子设备标识等

使用示例:

# 查询1号楼下的设备（不含子空间）
get_space_device_list("160110452")

# 查询1号楼及所有房间的设备（递归查询）
get_space_device_list("160110452", True)

# 查询101室下的设备
get_space_device_list("160110454")

# 指定产品ID筛选
get_space_device_list("160110452", False, "product1,product2")

# 指定设备类型筛选
get_space_device_list("160110452", False, "", "sp,dj")

空间层级示例:

1号楼 (160110452)
├── 101室 (160110454) - 温湿度传感器、空调、门磁
├── 102室 (160111045) - 温湿度传感器、空调、门磁
└── 公共区域 - 智能摄像机、灯、墙壁开关

注意事项:

  1. 空间ID必须是有效的空间标识
  2. 递归查询会返回所有子空间的设备，数量可能较多
  3. 建议根据实际需求选择合适的查询方式
  4. 设备信息包含敏感数据（如本地密钥），请注意安全

联动规则接口

11. 获取联动规则
get_scene_rules(space_id, page_size=20, page_no=1, rule_type="")

参数:

  • space_id: 空间ID（必填）
  • page_size: 页面大小
  • page_no: 页码
  • rule_type: 查询类型
12. 智能查找联动规则
find_and_trigger_scene_rule(space_keyword, rule_keyword)

参数:

  • space_keyword: 空间关键词
  • rule_keyword: 规则关键词

产品品类管理接口 ⭐ 新增功能

13. 获取产品品类列表
get_product_categories(category_filter="", search_term="", show_all=False)

功能说明:

  • 获取涂鸦IoT平台支持的产品品类信息
  • 支持按分类筛选、关键词搜索或显示全部
  • 从本地数据库查询，响应速度快

参数:

  • category_filter: 分类筛选，如"能源设备"、"安防设备"、"传感器设备"等
  • search_term: 关键词搜索，如"智能"、"灯"、"传感器"等
  • show_all: 是否显示全部品类，默认False

使用示例:

# 显示所有品类
get_product_categories()

# 查询能源设备
get_product_categories(category_filter="能源设备")

# 搜索智能设备
get_product_categories(search_term="智能")

# 搜索空调设备
get_product_categories(search_term="空调")

# 显示全部品类
get_product_categories(show_all=True)

常见分类:

  • 能源设备: 光伏、充电桩、电表等
  • 安防设备: 摄像头、门锁等
  • 传感器设备: 温湿度传感器、人体传感器等
  • 娱乐设备: 电视、音箱等
  • 楼宇自动化: BA系统、智能停车等
  • 工业设备: 工业网关、传感器等
  • 网关设备: 各种网关和控制器
14. 获取可用分类列表
get_available_categories()

功能说明:

  • 显示涂鸦IoT平台支持的所有产品分类
  • 包含每个分类的品类数量统计
  • 帮助用户了解可用的分类选项
15. 添加单个产品品类
add_product_category(code, name, category)

功能说明:

  • 添加新的产品品类到涂鸦IoT平台品类数据库
  • 支持16个预定义分类
  • 自动验证品类代码是否已存在
  • 验证分类是否有效

参数:

  • code: 品类代码，唯一标识符 (如: "mcs", "test_device")
  • name: 品类名称，中文描述 (如: "门磁设备", "测试设备")
  • category: 所属分类，必须是预定义分类之一

可用分类:

  • 能源设备: 光伏、充电桩、电表等
  • 娱乐设备: 电视、音箱、游戏设备等
  • 楼宇自动化: BA系统、智能停车等
  • 工业设备: 工业网关、传感器等
  • 网关设备: 各种网关和控制器
  • 传感器设备: 各种传感器和检测设备
  • 安防设备: 摄像头、门锁等
  • 其他设备: 其他杂项设备
  • 交通工具: 电动车、平衡车等
  • 控制器: 各种控制器
  • 商业设备: 商业相关设备
  • 户外设备: 户外相关设备
  • 安全设备: 安全相关设备
  • 工具设备: 工具类设备
  • 测试设备: 测试相关设备
  • 配件: 配件类设备

使用示例:

# 添加门磁设备
add_product_category("mcs", "门磁设备", "安防设备")

# 添加测试设备
add_product_category("test_device", "测试设备", "测试设备")

# 添加自定义传感器
add_product_category("custom_sensor", "自定义传感器", "传感器设备")
16. 批量添加产品品类
add_product_categories_batch(categories_json)

功能说明:

  • 批量添加多个产品品类到涂鸦IoT平台品类数据库
  • 支持JSON格式的品类列表
  • 自动跳过已存在的品类
  • 显示批量添加统计信息

参数:

  • categories_json: JSON格式的品类列表字符串

JSON格式示例:

[
    {"code": "mcs", "name": "门磁设备", "category": "安防设备"},
    {"code": "test_device", "name": "测试设备", "category": "测试设备"},
    {"code": "custom_sensor", "name": "自定义传感器", "category": "传感器设备"}
]

使用示例:

# 批量添加品类
add_product_categories_batch('[{"code":"mcs","name":"门磁设备","category":"安防设备"}]')
17. 获取品类管理统计信息
get_category_management_stats()

功能说明:

  • 显示涂鸦IoT平台品类数据库的统计信息
  • 包含总品类数量和分类统计
  • 帮助了解数据库当前状态

🧪 测试

运行完整功能测试

python test_standalone.py

测试设备状态API端点

python test_device_status.py

测试特定设备控制

python control_101_ac.py

测试空间设备列表接口

# 基础测试
python test_space_device_list.py

# 使用指定空间ID测试
python test_space_device_list.py "your_space_id_here"

测试将验证所有MCP工具接口的功能。

🔧 使用示例

基本设备操作

# 获取设备列表
devices = await get_device_list(page_size=5)
print(devices)

# 获取设备状态
status = await get_device_status("device_id_here")
print(status)

# 获取设备控制指令集
commands = await get_device_ctrlCommands("device_id_here")
print(commands)

# 下发指令到设备
result = await control_device_new("device_id_here", "action", '{"switch":"true"}')
print(result)

空调设备控制示例

# 获取空调设备状态
ac_status = await get_device_status("vdevo168956543331751")
print(ac_status)

# 开启空调
await control_device_new("vdevo168956543331751", "action", '{"switch":"true"}')

# 设置温度到25℃
await control_device_new("vdevo168956543331751", "action", '{"temp_set":25}')

# 设置为制冷模式
await control_device_new("vdevo168956543331751", "action", '{"mode":"cold"}')

# 设置风速为健康模式
await control_device_new("vdevo168956543331751", "action", '{"fan_speed_enum":"health"}')

# 开启上下摆风
await control_device_new("vdevo168956543331751", "action", '{"switch_vertical":"true"}')

空间和联动操作

# 获取空间列表
spaces = await get_space_list()
print(spaces)

# 获取空间详情
space_detail = await get_space_detail("space_id_here")
print(space_detail)

# 获取空间下的设备列表
space_devices = await get_space_device_list("space_id_here")
print(space_devices)

# 获取空间下的设备列表（递归子空间）
recursive_devices = await get_space_device_list("160110452", True)
print(recursive_devices)

# 指定产品ID筛选设备
filtered_devices = await get_space_device_list("160110452", False, "product1,product2")
print(filtered_devices)

# 获取联动规则
rules = await get_scene_rules("space_id_here")
print(rules)

产品品类管理示例

# 获取所有产品品类
categories = await get_product_categories()
print(categories)

# 按分类筛选品类
energy_categories = await get_product_categories(category_filter="能源设备")
print(energy_categories)

# 关键词搜索品类
smart_categories = await get_product_categories(search_term="智能")
print(smart_categories)

# 获取可用分类列表
available_categories = await get_available_categories()
print(available_categories)

# 添加单个品类
result = await add_product_category("mcs", "门磁设备", "安防设备")
print(result)

# 批量添加品类
categories_json = '[{"code":"mcs","name":"门磁设备","category":"安防设备"}]'
result = await add_product_categories_batch(categories_json)
print(result)

# 获取品类统计信息
stats = await get_category_management_stats()
print(stats)

空间设备查询示例

# 查询1号楼公共区域的设备
public_devices = await get_space_device_list("160110452")
print(public_devices)

# 查询1号楼所有设备（包括101室、102室）
all_devices = await get_space_device_list("160110452", True)
print(all_devices)

# 查询101室的设备
room_101_devices = await get_space_device_list("160110454")
print(room_101_devices)

# 查询102室的设备
room_102_devices = await get_space_device_list("160111045")
print(room_102_devices)

# 筛选特定类型的设备
camera_devices = await get_space_device_list("160110452", True, "", "sp")
print(camera_devices)

📁 项目结构

tuya-iot/
├── tuya-iot.py              # 主服务器文件
├── test_standalone.py       # 独立测试脚本
├── control_101_ac.py        # 101房间空调控制脚本
├── pyproject.toml           # 项目配置
├── uv.lock                  # 依赖锁定文件
├── .python-version          # Python版本文件
├── .gitignore               # Git忽略文件
├── .env                     # 环境变量配置（需要创建）
├── README.md               # 项目文档
├── docs/                   # 文档目录
│   ├── tuya_云签名算法/     # 涂鸦云签名算法文档
│   └── tuyaAPI_docs/       # 涂鸦API文档
├── categories-db/          # 品类数据库目录 ⭐ 新增
│   ├── tuya_categories.db  # SQLite数据库文件
│   ├── add_category.py     # 品类添加脚本
│   ├── query_tuya_categories.py # 查询演示脚本
│   ├── create_tuya_categories_db.py # 数据库创建脚本
│   ├── README_categories_db.md # 详细使用说明
│   ├── README_add_category.md # 添加品类说明
│   └── README_categories.md # 品类管理文档 ⭐ 已移动
├── __pycache__/            # Python缓存目录
└── .venv/                  # 虚拟环境目录

更新日志

v1.5.0 (当前版本) ⭐ 最新更新

  • ✅ 新增产品品类管理功能 - 完整的品类查询、添加和管理功能
  • ✅ 本地数据库支持 - 使用SQLite数据库存储品类信息，查询速度快
  • ✅ 分类筛选功能 - 支持按16个预定义分类筛选产品品类
  • ✅ 关键词搜索 - 支持关键词搜索产品品类
  • ✅ 单个品类添加 - 支持添加单个产品品类到数据库
  • ✅ 批量品类添加 - 支持批量添加多个产品品类
  • ✅ 品类统计信息 - 提供品类管理统计信息
  • ✅ 可用分类列表 - 获取所有可用的产品分类
  • ✅ 完善错误处理 - 增强错误处理和用户提示

v1.4.0

  • ✅ 修复空间设备列表接口 - 修复 get_space_device_list 接口的签名问题
  • ✅ 完善函数描述 - 添加详细的使用示例、空间层级示例和注意事项
  • ✅ 支持递归查询 - 支持查询当前空间及所有子空间的设备
  • ✅ 优化参数处理 - 修复URL参数排序问题，解决sign invalid错误
  • ✅ 增强用户体验 - 提供更清晰的返回信息和错误提示

v1.3.0

  • ✅ 新增空间设备列表接口 - 添加 get_space_device_list 接口，支持查询指定空间下的设备列表
  • ✅ 优化空间管理功能 - 完善空间相关的API接口和错误处理
  • ✅ 增强用户体验 - 添加空间名称显示和友好的错误提示

v1.2.0

  • ✅ 修复设备状态查询 - 优化API端点，使用 /v1.0/iot-03/devices/{device_id}/status
  • ✅ 增强状态显示 - 添加空调模式和风速的中文映射
  • ✅ 修复设备控制 - 修正 control_device_new 请求体格式

📚 相关文档

  • - 产品品类数据库的使用说明
  • - 涂鸦API签名算法详解
  • - 涂鸦IoT平台API文档

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

�� 许可证

本项目采用MIT许可证。