# IoT 设备 MCP 工具说明

## 📋 工具清单

本服务提供 **4 个核心工具**，用于智能设备的查询、定位和控制。

---

## 🔧 工具详情

### 1. **iot_get_devices_by_location** - 根据位置获取设备

**功能**：查询指定位置/房间的所有智能设备

**使用场景**：
- "办公室有哪些设备"
- "会议室有什么设备"
- "客厅设备列表"

**参数**：
- `location` (必填)：位置/房间名称

**返回**：该位置的设备清单（设备ID、名称、类型、状态、控制命令等）

---

### 2. **iot_get_all_spaces_and_devices** - 获取所有空间位置信息

**功能**：获取系统中所有可用空间位置的列表（仅空间名称，不包含设备详情）

**使用场景**：
- "显示所有空间"
- "有哪些位置"
- "空间列表"
- "一共有多少个房间"

**参数**：无需参数

**返回**：
- 空间总数
- 所有空间名称的列表

**注意**：此工具只返回空间清单，如需查看某个空间的设备，请使用 `iot_get_devices_by_location` 工具

---

### 3. **iot_device_precise_controller** - IoT设备精确控制

**功能**：通过设备ID精确控制特定设备

**使用场景**：
- 控制特定的灯光、空调、门禁等
- 需配合查询工具获取设备信息后使用

**参数**：
- `entityId` (必填)：设备唯一ID
- `command` (必填)：操作命令（如 turn_on、turn_off、set_temperature）
- `params` (必填)：操作参数（根据命令类型提供，如温度值、亮度等）
- `userId` (可选)：用户ID

**返回**：设备操作结果（成功/失败、设备反馈）

---

### 4. **smart_space_device_locator_matcher** - 智能空间设备定位

**功能**：查询用户当前所属的空间/位置

**使用场景**：
- "我现在在哪"
- "当前位置是什么"
- "确认一下位置"

**参数**：
- `userId` (必填)：用户ID

**返回**：用户所属的空间名称

---

## 💡 典型使用流程

### 方式一：查看所有空间
```
1. 调用 iot_get_all_spaces_and_devices 获取所有空间列表
2. 选择感兴趣的空间
3. 调用 iot_get_devices_by_location 查看该空间的设备
```

### 方式二：查看特定位置的设备
```
1. 调用 iot_get_devices_by_location 指定位置
2. 查看该位置的设备清单和状态
```

### 方式三：控制设备（两步操作）
```
1. 调用 iot_get_devices_by_location 获取设备列表
2. 从结果中提取 entityId 和 command
3. 调用 iot_device_precise_controller 执行控制
```

### 方式四：定位用户
```
1. 调用 smart_space_device_locator_matcher
2. 获取用户当前所属空间
3. 基于位置查询或控制设备
```

---

## 📝 注意事项

1. **企业ID配置**：服务启动时需要配置 `ENTERPRISE_ID` 环境变量，系统会自动初始化向量库
2. **日志记录**：所有操作都会记录到日志文件 `lzwcai_mcp_iot.log`
3. **传输方式**：使用 stdio（标准输入输出）方式运行
4. **控制工具配合**：精确控制工具必须配合查询工具使用，不能单独随意填写参数

## 🔄 重要更新（v0.3.2）

**配置变更：**
- ❌ 废弃：`employeeId` 环境变量
- ✅ 新增：`ENTERPRISE_ID` 环境变量（必需）

**初始化流程优化：**
- 移除了通过员工ID查询企业ID的步骤
- 现在直接使用企业ID进行初始化
- 提高了服务启动效率

---

## 🎯 核心特性

- ✅ 支持位置筛选查询设备
- ✅ 支持获取所有可用空间列表
- ✅ 支持精确的设备ID控制
- ✅ 支持用户空间定位
- ✅ 自动格式化设备列表输出
- ✅ 完整的错误处理和日志记录