🚀 HomeyPro MCP 服务器
HomeyPro MCP 服务器是一个用于与 HomeyPro 家庭自动化系统进行交互的模型上下文协议（MCP）服务器。该服务器提供对设备、区域和流程的分页访问，并具备全面的管理能力。
✨ 主要特性
- 设备管理：支持列出、搜索和控制设备，具备完整的功能支持。
- 区域管理：浏览区域及其关联的设备。
- 流程管理：列出并触发自动化流程。
- 系统管理：获取和更新系统配置（位置、地址、语言、单位）。
- 人工智能提示：提供上下文感知的设备控制、故障排除和自动化指导。
- 资源缓存：通过智能缓存和陈旧数据回退机制实现高效的数据访问。
- 分页支持：基于游标分页，有效处理大型数据集。
- 实时数据：获取当前设备状态、功能和洞察信息。
- 错误处理：具备全面的错误处理机制，提供详细的错误信息。
📦 安装指南
本地开发
- 克隆仓库并进入项目目录：
cd python-homey-mcp
- 使用 uv 安装依赖：
uv sync
Docker
拉取预构建的 Docker 镜像：
docker pull ghcr.io/pigmej/python-homey-mcp:latest
使用 Docker 时无需额外的安装步骤。
📚 详细文档
配置
在运行服务器之前，你需要配置 HomeyPro 连接。
环境变量
设置以下环境变量：
export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"
获取 HomeyPro 令牌
- 打开 HomeyPro 网页界面。
- 转到“设置”>“常规”>“API”。
- 创建一个新的个人访问令牌。
- 复制令牌并将其设置为
HOMEY_API_TOKEN环境变量。
查找 HomeyPro IP 地址
你可以在以下位置找到 HomeyPro 的 IP 地址：
- HomeyPro 网页界面：“设置”>“常规”>“网络”。
- 你的路由器管理面板。
- HomeyPro 移动应用：“更多”>“设置”>“常规”>“网络”。
使用方法
运行服务器
使用 uvx（推荐）
使用 uvx 运行服务器是最简单的方法：
# 设置环境变量
export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"
# 使用 uvx 运行
uvx --from . homey-mcp
或者直接使用 FastMCP CLI 运行：
# HTTP 传输（推荐用于测试）
uvx fastmcp run main.py --transport http --host 0.0.0.0 --port 4445
# STDIO 传输（适用于 MCP 客户端）
uvx fastmcp run main.py --transport stdio
本地开发
# 使用 uv run
uv run fastmcp run main.py --transport http --host 0.0.0.0 --port 4445 --log-level DEBUG
# 或者使用旧方法
uv run fastmcp run -t http --host 0.0.0.0 -p 4445 -l DEBUG main.py
在 MCP 客户端中安装
你可以使用 FastMCP 直接在 MCP 客户端中安装此服务器：
# 在 Claude Desktop 中安装
uvx fastmcp install claude-desktop main.py \
--env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
--env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
# 在 Claude Code 中安装
uvx fastmcp install claude-code main.py \
--env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
--env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
# 在 Cursor 中安装
uvx fastmcp install cursor main.py \
--env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
--env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
# 生成 MCP JSON 配置
uvx fastmcp install mcp-json main.py \
--env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
--env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
Docker 容器
在 Docker 容器中运行 MCP 服务器：
docker run -p 4445:4445 \
-e HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS" \
-e HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN" \
ghcr.io/pigmej/python-homey-mcp:latest
或者使用 docker-compose：
version: '3.8'
services:
python-homey-mcp:
image: ghcr.io/pigmej/python-homey-mcp:latest
ports:
- "4445:4445"
environment:
- HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS
- HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
服务器将启动并连接到你的 HomeyPro 实例，你将看到连接确认消息。具体操作请参考 FastMCP 文档。
人工智能提示
服务器提供上下文感知的提示，帮助你更有效地与 HomeyPro 系统进行交互。这些提示会分析你当前的系统状态并提供针对性的指导。
可用提示
- 设备控制助手：为控制 HomeyPro 系统中不同类型的设备提供结构化指导。
- 上下文：当前设备数量、在线/离线状态、可用设备类型。
- 指导：照明、气候、安全和娱乐设备的控制模式。
- 最佳实践：设备状态检查、功能使用、故障排除技巧。
- 设备故障排除：为常见的 HomeyPro 设备问题提供系统的诊断指导。
- 系统健康：整体设备健康百分比和状态指标。
- 逐步流程：结构化的故障排除工作流程。
- 特定设备：针对离线和无响应设备的针对性解决方案。
- 高级诊断：网络、性能和系统级故障排除。
- 设备功能探索：帮助你发现和理解设备功能，避免信息过载。
- 功能类别：控制、传感器和状态功能。
- 值类型：布尔、数值、字符串和枚举功能格式。
- 使用模式：常见的功能组合和最佳实践。
- 设备类型模式：不同设备类别的功能模式。
- 流程创建助手：为创建 HomeyPro 自动化流程提供结构化指导。
- 流程框架：“何时（触发）”、“并且（条件）”、“然后（动作）”结构。
- 常见场景：安全、舒适、能源、便利和安全自动化。
- 系统上下文：可用区域、设备类型和现有流程。
- 模板：常见用例的即用型流程模板。
- 流程优化：为改进现有流程的性能和可靠性提供指导。
- 性能分析：流程执行模式和优化机会。
- 资源使用：设备和系统资源考虑因素。
- 最佳实践：流程组织、命名和维护策略。
- 流程调试：提供系统的方法来诊断和修复流程问题。
- 常见问题：流程执行失败、时间问题、设备冲突。
- 诊断工具：日志分析、条件测试、动作验证。
- 解决策略：逐步调试工作流程。
- 系统健康检查：提供全面的系统健康分析和建议。
- 健康指标：设备连接性、流程状态、系统性能。
- 状态概述：连接状态、系统配置、资源使用。
- 建议：维护建议和优化机会。
- 区域组织：为组织和优化区域结构提供指导。
- 区域规划：设备和区域的逻辑分组策略。
- 层次管理：父子区域关系。
- 设备分配：设备到区域映射的最佳实践。
提示特性
- 上下文感知：所有提示都会分析你当前的系统状态。
- 实时数据：信息基于当前设备和系统状态。
- 优雅降级：即使 HomeyPro 暂时不可用，提示仍然可以工作。
- 错误处理：提供清晰的错误消息和建议操作。
- 可操作指导：提供你可以立即采取的实际步骤。
资源缓存
服务器提供智能资源缓存功能，当 HomeyPro 暂时不可用时，会自动回退到陈旧数据。
可用资源
- 系统概述 (
homey://system/overview)：提供全面的系统概述，包括设备数量、区域数量和健康指标。- 内容：设备统计信息、区域摘要、系统健康百分比。
- 缓存 TTL：5 分钟。
- 用例：仪表板显示、系统监控、健康检查。
- 设备注册表 (
homey://devices/registry)：包含当前状态、功能和在线/离线指标的完整设备清单。- 内容：带有功能、状态和元数据的完整设备列表。
- 缓存 TTL：30 秒（动态数据）。
- 用例：设备管理界面、功能发现、状态监控。
- 区域层次结构 (
homey://zones/hierarchy)：包含设备关联和父子关系的区域结构。- 内容：区域树、设备分配、区域类型和统计信息。
- 缓存 TTL：5 分钟。
- 用例：区域管理、设备组织、空间自动化。
- 流程目录 (
homey://flows/catalog)：包含元数据、状态和执行统计信息的可用流程。- 内容：带有触发条件、条件、动作和执行数据的流程列表。
- 缓存 TTL：2 分钟。
- 用例：流程管理、自动化分析、调试。
缓存特性
- 智能 TTL：根据数据波动性设置不同的缓存持续时间。
- 陈旧数据回退：当 HomeyPro 不可达时返回缓存数据。
- 错误处理：带有详细错误信息的优雅降级。
- 连接弹性：在网络问题期间继续运行。
- 性能优化：减少 API 调用并提高响应时间。
缓存行为
- 新鲜数据：当缓存有效且 HomeyPro 可访问时返回当前数据。
- 陈旧数据：当 HomeyPro 不可达时返回带有陈旧指示的缓存数据。
- 错误响应：当没有缓存数据可用时返回结构化的错误信息。
- 自动刷新：当 HomeyPro 再次可用时自动刷新缓存。
API 工具
服务器提供全面的 API 工具，用于直接与 HomeyPro 进行交互。所有工具都支持分页和错误处理，并提供详细的响应信息。
设备工具
- 设备发现和信息
list_devices：列出所有设备，支持分页。- 可选的紧凑模式，减少数据传输。
- 自动排除隐藏设备。
- 包含每个设备的在线/离线状态。
get_device：获取特定设备的详细信息。- 完整的设备详细信息，包括功能和设置。
- 功能值和详细配置。
- 能源信息和用户界面设置。
get_devices_classes：列出所有可用的设备类别。- 有助于在搜索前了解设备类型。
- 返回支持的设备类别的完整列表。
get_devices_capabilities：列出所有可能的设备功能。- 全面的功能参考。
- 理解控制选项的必备信息。
- 设备搜索和过滤
search_devices_by_name：按名称搜索设备，支持分页。- 对设备名称进行模糊匹配。
- 包含备注字段信息，提供上下文。
- 支持大型结果集的分页。
search_devices_by_class：按类别/类型搜索设备。- 按特定类别（灯光、传感器等）过滤设备。
- 带元数据的分页结果。
- 设备控制和监控
control_device：控制设备功能。- 设置功能值（开/关、调光、温度等）。
- 支持 JSON 值解析和回退处理。
- 控制后返回当前设备状态。
get_device_insights：获取设备历史数据。- 多种时间分辨率（小时、天、周、月）。
- 支持自定义时间戳范围。
- 特定功能的洞察和趋势。
区域工具
- 区域管理
list_zones：列出所有区域，支持分页。- 完整的区域层次结构信息。
- 包含父子关系。
get_zone_devices：获取特定区域内的所有设备。- 基于区域的设备过滤。
- 可选的紧凑模式，提高性能。
- 每个设备的在线/离线状态。
- 区域监控
get_zone_temp：获取区域的平均温度。- 自动计算区域内温度传感器的平均值。
- 对没有温度传感器的区域进行优雅处理。
流程工具
- 统一流程管理
list_flows：列出所有流程（普通和高级），支持分页。- 自动合并普通和高级流程。
- 每个流程包含
flow_type字段（“普通”或“高级”）。 - 完整的流程元数据和配置。
- 跨合并结果的无缝分页。
trigger_flow：执行任何流程（自动检测类型）。- 自动检测流程是普通还是高级。
- 通过统一接口手动触发流程。
- 成功确认，包含流程详细信息和类型。
get_flow_folders：获取所有流程组织文件夹。- 流程组织结构。
- 用于更好管理的文件夹层次结构。
get_flows_by_folder：获取特定文件夹中的流程。- 基于文件夹的流程过滤。
- 流程组织管理。
get_flows_without_folder：获取未组织的流程。- 查找需要组织的流程。
- 清理和维护协助。
- 流程组织
get_flow_folders：获取所有流程组织文件夹。- 流程组织结构。
- 用于更好管理的文件夹层次结构。
get_flows_by_folder：获取特定文件夹中的流程。- 基于文件夹的流程过滤。
- 流程组织管理。
- 注意：仅返回文件夹中的普通流程。
get_flows_without_folder：获取未组织的流程。- 查找需要组织的流程。
- 清理和维护协助。
- 注意：仅返回没有文件夹的普通流程。
系统工具
- 系统信息
get_system_info：获取全面的系统概述。- 连接状态和系统健康。
- 设备、区域和流程数量。
- 在线/离线设备统计信息。
- 流程状态（启用/禁用/损坏）。
- 系统配置（地址、语言、单位）。
- 位置坐标和区域设置。
- 建议在其他操作之前首先调用。
工具特性
- 分页支持
- 基于游标的分页：有效处理大型数据集。
- 可配置的页面大小：根据用例进行优化。
- 总数跟踪：了解完整数据集的大小。
- 下一页指示：方便浏览结果。
- 数据格式
- 紧凑模式：为提高性能减少数据传输。
- 完整详细模式：需要时提供完整信息。
- JSON 值处理：自动解析并提供回退。
- 错误响应：带有详细信息的结构化错误信息。
- 性能优化
- 隐藏设备过滤：自动排除系统设备。
- 高效查询：优化对 HomeyPro 的 API 调用。
- 连接重用：持久连接以提高性能。
- 优雅降级：在部分故障时继续运行。
- 错误处理
- 详细错误消息：清晰的问题描述。
- 连接状态：网络和 API 健康指标。
- 回退响应：优雅处理 API 故障。
- 日志集成：全面的错误跟踪。
🔧 贡献方式
- 分叉仓库。
- 创建一个功能分支。
- 进行更改。
- 如有必要，添加测试。
- 提交拉取请求。
📄 许可证
本项目采用 MIT 许可证。