# 智能家居设备控制 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 环境运行脚本：

```bash
pip install fastmcp requests

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

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

```bash
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服务器。

```json
{
  "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 字段确认操作是否成功