智能家居设备控制 MCP 服务器

这个 MCP 服务器允许大模型通过 Model Context Protocol (MCP) 协议访问智能家居后端 API，实现设备控制和信息查询功能。

功能特点

• 提供设备控制接口，支持各种智能家居设备的操作
• 查询设备概览和详细信息
• 内置丰富的设备文档，指导大模型正确使用各类设备
• 支持通过命令行参数配置后端 API 地址和认证令牌

支持的设备类型及控制参数

1. 空调 (air_conditioner):

   • 设置温度 (set_temperature)
     • 参数: temperature (范围: 16-30°C)
     • 示例: control_device(device_id="5", action="set_temperature", parameters={"temperature": 24})
   • 开关控制 (switch)
     • 参数: state ("on"或"off")
     • 示例: control_device(device_id="5", action="switch", parameters={"state": "on"})

2. 冰箱 (refrigerator):

   • 设置温度 (set_temperature)
     • 参数: temperature (范围: -20到10°C)
     • 示例: control_device(device_id="8", action="set_temperature", parameters={"temperature": 4})
   • 开关控制 (switch)
     • 参数: state ("on"或"off")
     • 示例: control_device(device_id="8", action="switch", parameters={"state": "on"})

3. 灯 (light):

   • 设置亮度 (set_brightness)
     • 参数: brightness (范围: 0-100)
     • 示例: control_device(device_id="12", action="set_brightness", parameters={"brightness": 80})
   • 开关控制 (switch)
     • 参数: state ("on"或"off")
     • 示例: control_device(device_id="12", action="switch", parameters={"state": "on"})

4. 门锁 (lock):

   • 设置锁状态 (set_lock)
     • 参数: state ("lock"或"unlock")
     • 示例: control_device(device_id="15", action="set_lock", parameters={"state": "lock"})

5. 摄像头 (camera):

   • 控制录制 (set_recording)
     • 参数: state ("start"或"stop")
     • 示例: control_device(device_id="20", action="set_recording", parameters={"state": "start"})
   • 设置分辨率 (set_resolution)
     • 参数: resolution ("720p", "1080p"或"4k")
     • 示例: control_device(device_id="20", action="set_resolution", parameters={"resolution": "1080p"})

设备状态说明

• online: 设备在线正常工作
• offline: 设备离线
• error: 设备出现错误

使用方法

启动服务器

可以通过 python 环境运行脚本：

pip install fastmcp requests

python mcp_server.py --backend http://backend-api-address:8000/api/v1 --token <your_auth_token>

也可以从 Release 中下载对应平台的二进制可执行文件，直接运行：

mcp_server --backend http://backend-api-address:8000/api/v1 --token <your_auth_token>

your_auth_token 令牌需要在通过POST /auth/login登录到后端后获取

参数说明:

• --backend: 后端 API 地址，默认为 http://localhost:8000
• --token: 认证令牌，用于访问后端 API 的授权

对话测试

你可以使用 cursor 或者 cline(VSCode插件)与大模型对话，在其中调用MCP服务器。

{
  "mcpServers": {
    "cpm-smarthome": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "python",
      "args": [
        "/path/to/mcp_server.py",
        "--token",
        "your_auth_token",
        "--backend",
        "http://backend-api-address:8000/api/v1"
      ]
    }
  }
}

可用工具

服务器提供以下工具供大模型使用:

1. get_config(): 获取当前配置信息

   • 返回后端 API 地址和认证令牌配置状态
   • 注意：认证令牌不会返回明文

2. get_device_overview(): 获取所有设备的概览信息

   • 返回系统中所有设备的基本信息列表
   • 包括设备ID、名称、状态等信息

3. get_device_detail(device_id): 获取特定设备的详细信息

   • 返回指定设备的详细状态信息
   • 包括设备状态、功耗、运行时间、日志等

4. control_device(device_id, action, parameters): 控制特定设备执行操作

   • 用于向指定设备发送控制命令
   • 具体参数请参考上方设备类型说明

5. get_device_type_docs(device_type): 获取设备类型的控制文档

   • 不指定设备类型时返回所有设备类型的概览
   • 指定设备类型时返回该类型的详细控制文档

后端 API 接口

本服务器连接到以下后端 API 接口:

1. 控制设备: POST /devices/{device_id}/control/
2. 查询设备概要: GET /devices/overview/
3. 查询设备详情: GET /devices/{device_id}/detail/

注意事项

• 在使用任何工具前，请确保服务器启动时已提供正确的认证令牌
• 不同类型的设备支持不同的操作和参数，请参考设备文档了解详情
• 所有API调用都需要提供有效的认证令牌
• 设备控制操作会返回操作结果，请检查返回的 success 字段确认操作是否成功