OXII智能家居MCP服务器
与FastAPI聊天机器人配对的设备控制MCP堆栈的现代文档。使用本指南的方式与使用聊天机器人文档的方式相同：它涵盖了独立MCP开发的设置、命令、工具和故障排除。
🔎 概述
| 目的 | 通过模型上下文协议（MCP）公开OXII智能家居控件（设备信息、开关、AC、cronjobs、一键式、房间场景）。 |
| 运输 | 端口上的服务器发送事件（SSE） 9031. |
| 运行时 | Python 3.10+， mcp.server.FastMCP 配备LangChain MCP适配器。 |
| 消费者 | FastAPI聊天机器人(chatbot/)或任何MCP兼容客户端。 |
mcp/oxii-server/
├── main.py # Boots the FastMCP process and registers tools
├── tools/ # Tool implementations (auth, device control, cronjobs…)
├── client.py # Quick demo client for manual testing
├── docker-compose.yml # Containerized runtime (exposes :9031)
└── .env.example # Sample environment for OXII credentials✅ 先决条件
- Python 3.10或更高版本（Poetry将管理依赖关系）， 或 Docker引擎20.10+
- 具有设备访问权限的OXII帐户凭据（电话、密码、国家/地区）
- 对中定义的OXII分段/产品API的网络访问
OXII_BASE_URL
⚙️ 环境配置
创建环境文件的工作副本并填写机密：
cp .env.example .env| 变量 | 描述 |
|---|---|
OXII_BASE_URL | OXII API的根URL（默认情况下提供分段）。 |
OXII_PHONE / OXII_PASSWORD / OXII_COUNTRY | 用于获取访问令牌的登录名。 |
PORT / HOST | MCP服务器监听位置的可选覆盖（默认 0.0.0.0:9031). |
DEBUG | 切换详细日志记录(true/false). |
🚀 运行服务器
选项1-本地诗歌工作流程
poetry install
poetry run python main.py这将在以下位置启动服务器 http://localhost:9031/sse.
选项2–Docker编写
cp .env.example .env # if you have not already
docker compose up --build -d组合堆栈公开端口 9031 在主机上。通过指向将其与聊天机器人结合起来 OXII_MCP_SERVER_URL 到 http://host.docker.internal:9031/sse 在聊天机器人容器内。
✅ 验证服务
1.使用捆绑客户端
poetry run python client.py从提示中选择一个工具，并提供所需的参数以确认端到端连接。
2.访问内置的文档UI
- 人性化文档：
http://host.docker.internal:9031/docx - 机器可读目录：
http://host.docker.internal:9031/docs.json
3.卷起SSE握手
curl -N http://localhost:9031/sse您应该看到一个描述MCP功能的初始JSON有效负载。
🧰 工具目录
下面是每个注册的MCP工具的快速参考。所有有效载荷都是通过MCP协议传递的JSON结构。
| 工具 | 目的 | 关键参数 |
|---|---|---|
get_device_list | 列出房屋、房间、设备和远程按钮。 | token |
switch_device_control | 切换SH1/SH2继电器设备。 | token, house_id, device_id, button_code, command (ON/OFF) |
control_air_conditioner | 全空调控制（模式、温度、风扇）。 | token, serial_number, mode, fan_speed, temperature等等。 |
create_device_cronjob | 添加/更新/删除交换机或AC的cronjobs | token, device_id 或 button_id, action, cron_expression, command |
one_touch_control_all_devices | 执行全屋预设（例如，“关闭所有设备”）。 | token, house_id, status |
one_touch_control_by_type | 按类型切换设备（LIGHT、CONDITIONER等）。 | token, house_id, device_type, status |
room_one_touch_control | 运行单人房预设。 | token, room_id, status |
ℹ️ 详细的模式存在于 tools/ 在每个功能旁边。查看这些模块的参数验证和API有效负载形状。🔄 使用聊天机器人
- 启动MCP服务器（本地或Docker）并确保端口
9031可以从聊天机器人环境访问。 - 在
chatbot/.env，setOXII_MCP_SERVER_URL=http://host.docker.internal:9031/sse在Docker中运行聊天机器人时。 - 重新启动聊天机器人容器(
docker compose restart app)应用env更改。 - 使用聊天机器人端点
POST /ai/agent-oxii使用有效的OXII令牌，代理将自动调用MCP工具。
🧪 测试和诊断
- 机组检查 –跑步
poetry run pytest如果添加测试（种子文件test_tools.py可用作模板）。 - 令牌验证 –使用
chatbot/test_folders/testing_api.py在调用工具之前获取新的令牌。 - 日志 –与
DEBUG=true，服务器为每个MCP调用打印详细的跟踪。在Docker中，使用docker compose logs -f oxii-server.
🛠 故障排除
| 症状 | 建议的解决方法 |
|---|---|
httpx.ConnectError: All connection attempts failed | 消费者指向 localhost 来自Docker内部。使用 host.docker.internal 或者在同一个Compose网络上运行这两个服务 |
| 身份验证失败 | 仔细检查 OXII_PHONE, OXII_PASSWORD，以及 OXII_COUNTRY.Tokens expired——如果请求开始返回401，则获取一个新的令牌。 |
| Cronjob负载被拒绝 | 确保cron表达式有6个字段(second minute hour day month weekday)并与设备类型（SH1/SH2 vs SH4）相匹配。 |
| 忽略AC命令 | 某些设备需要数字模式/风扇值。参见中的常量 tools/ac_control.py 对于有效范围。 |
| Docker重建缓慢 | 使用 docker compose build oxii-server --no-cache 依赖关系更改后，否则依赖缓存层。 |
📚 进一步阅读
- 模型上下文协议（MCP）规范
- LangChain MCP适配器
chatbot/README.md有关FastAPI侧集成指南。