shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

hc3_mcp

VS Code扩展，通过MCP协议集成Fibaro HC3智能家居系统，提供设备控制、场景管理、QuickApp开发和系统监控功能

article

README

🚀 HC3 MCP 服务器

这是一款VS Code扩展程序，为斐波那契家庭中心3（Fibaro Home Center 3，简称 HC3）智能家居系统提供模型上下文协议（Model Context Protocol，简称 MCP）服务器集成功能。借助该扩展，VS Code 中的 AI 助手能够通过自然语言命令与你的斐波那契 HC3 设备、场景及系统信息进行交互。

✨ 主要特性

  • 全面集成斐波那契 HC3 REST API：可访问所有主要的 HC3 端点。
  • 与 VS Code 扩展集成：能在 VS Code 中无缝注册为 MCP 服务器。
  • 配置管理便捷：可通过 VS Code 设置或环境变量轻松完成设置。
  • 广泛的 API 覆盖：拥有 66 种以上的工具，涵盖 HC3 管理的各个方面。
  • 支持 QuickApp 开发：具备完整的文件操作功能，助力 QuickApp 开发。
  • 插件管理完善：可进行完整的插件配置、UI 交互及生命周期管理。
  • 智能上下文分析：提供系统分析、自动化建议以及设备关系分析。
  • 编程文档丰富：内置 HC3 编程指南和示例。
  • 强大的错误处理：具备健壮的错误处理机制，能提供详细的错误信息。
  • 类型安全可靠：完全采用 TypeScript 实现，拥有恰当的类型定义。

📦 安装指南

安装扩展

  • 可从 VS Code 市场安装（即将推出）。
  • 也可使用 Extensions: Install from VSIX... 命令，从 .vsix 文件进行安装。

📚 详细文档

配置方法

方法一：通过 VS Code 设置（推荐）

  1. 通过命令面板配置：
    • 打开命令面板（Cmd + Shift + P / Ctrl + Shift + P）。
    • 运行 HC3 MCP: Configure Fibaro HC3 Connection 命令。
    • 按照提示输入你的 HC3 详细信息。
  2. 手动设置：
    • 打开 VS Code 设置。
    • 搜索 “HC3 MCP”。
    • 进行如下配置：
      • 主机：HC3 的 IP 地址（例如：192.168.1.57）。
      • 用户名：你的 HC3 用户名。
      • 密码：你的 HC3 密码。
      • 端口：HC3 端口（默认值：80）。

方法二：使用环境变量（备用方案）

在你的主目录下创建一个 ~/.env 文件，并添加以下内容：

HC3_URL=http://192.168.1.57
HC3_USER=your_username
HC3_PASSWORD=your_password

注意：如果未配置 VS Code 设置，扩展程序将自动使用环境变量作为备用方案。

测试配置

运行 HC3 MCP: Test Fibaro HC3 Connection 命令，验证是否成功连接到你的 HC3 系统。

GitHub Copilot 配置

若要让 GitHub Copilot 使用 MCP 服务器，你需要手动进行如下配置：

  1. 在 VS Code 中打开用户设置（JSON）：
    • 按下 Cmd + Shift + P / Ctrl + Shift + P。
    • 输入 “Preferences: Open User Settings (JSON)”。
  2. 添加 MCP 服务器配置：
{
  "github.copilot.chat.experimental.mcpServers": {
    "hc3-smart-home": {
      "command": "node",
      "args": ["/path/to/your/extension/out/mcp/hc3-mcp-server.js"],
      "env": {
        "FIBARO_HOST": "192.168.1.57",
        "FIBARO_USERNAME": "admin",
        "FIBARO_PASSWORD": "your_password",
        "FIBARO_PORT": "80"
      }
    }
  }
}
  1. 替换配置值：
    • 更新已编译的 MCP 服务器的路径。
    • 设置你的 HC3 IP 地址、用户名和密码。
    • 重启 VS Code。
  2. 在 Copilot Chat 中进行测试：
    • 重要提示：配置扩展后，需开启新的聊天会话。
    • 输入 “List my HC3 devices”。
    • 输入 “@hc3-smart-home get all devices”。

注意：如果 MCP 服务器工具未立即可用，请开启新的 GitHub Copilot 聊天会话，以便其发现 MCP 服务器。

扩展设置

此扩展提供以下设置：

  • hc3McpServer.host：斐波那契 HC3 的 IP 地址或主机名。
  • hc3McpServer.username：斐波那契 HC3 的用户名。
  • hc3McpServer.password：斐波那契 HC3 的密码（安全存储）。
  • hc3McpServer.port：斐波那契 HC3 的端口号（默认值：80）。

💻 使用示例

配置完成后，扩展程序将自动提供一个 MCP 服务器，供 AI 助手使用。你可以使用自然语言命令与你的 HC3 系统进行交互，示例如下：

基础设备控制

  • “显示客厅中的所有设备”
  • “打开厨房的灯”
  • “将卧室的调光器调至 50%”
  • “关闭家中所有的灯”

高级设备操作

  • “显示所有 Z-Wave 设备”
  • “获取设备 25 的详细信息”
  • “将 RGB 灯设置为蓝色”
  • “延迟 5 分钟后，开启花园洒水器 10 分钟”

场景管理

  • “列出主卧室中的所有场景”
  • “运行电影之夜场景”
  • “停止当前场景”
  • “显示所有支持 Alexa 的场景”

能源监控

  • “显示设备 15 的能源消耗”
  • “获取今日的总能源使用量”
  • “哪些设备耗电量最大？”

系统信息查询

  • “当前天气如何？”
  • “显示 HC3 系统信息”
  • “当前家庭状态如何？”
  • “将家庭模式设置为外出”

智能家居自动化

  • “创建一个自动化任务，当我离开时关闭所有灯光”
  • “显示所有运动传感器及其当前状态”
  • “每个房间的温度是多少？”

QuickApp 开发

  • “显示 QuickApp 926 的文件”
  • “获取设备 145 的 main.lua 文件内容”
  • “为 QuickApp 82 创建一个新的 helper.lua 文件”
  • “用新代码更新 QuickApp 67 的主文件”
  • “将 QuickApp 45 导出为加密文件，供特定网关使用”
  • “从 QuickApp 29 中删除 old_function.lua 文件”

插件管理与配置

  • “显示所有已安装的插件”
  • “获取设备 75 的配置界面”
  • “更新设备 45 上 button_1 的标签文本”
  • “触发设备 33 上 switch_main 的 onReleased 事件”
  • “为多通道开关 88 创建一个子设备”
  • “为设备 156 添加能源接口”
  • “重启设备 92 上故障的插件”
  • “更新设备 64 的温度属性”
  • “显示可供安装的 IP 摄像机类型”

可用工具

MCP 服务器提供 66 种以上的工具，分为以下几类：

核心系统管理

  • get_system_info - 获取基本的 HC3 系统信息。
  • get_devices - 列出所有设备，并支持过滤选项。
  • get_device - 获取特定设备的详细信息。
  • control_device - 控制设备的操作（如开启、关闭、设置值等）。
  • get_rooms - 列出所有房间和区域。
  • get_scenes - 列出所有场景。
  • get_scene - 获取特定场景的详细信息。
  • start_scene - 执行场景。
  • stop_scene - 停止正在运行的场景。

高级设备管理

  • get_device_actions - 获取设备可用的操作。
  • get_device_events - 获取设备的事件历史记录。
  • get_global_variables - 管理全局变量。
  • set_global_variable - 设置全局变量的值。
  • delete_global_variable - 删除全局变量。

气候与环境管理

  • get_climate_panels - 获取气候控制面板信息。
  • get_climate_zones - 获取气候区域和设置。
  • get_climate_schedules - 获取供暖/制冷时间表。
  • update_climate_schedule - 修改气候时间表。
  • get_weather_data - 获取当前天气信息。

安全与访问控制

  • get_alarm_partitions - 获取报警系统分区信息。
  • get_alarm_zones - 获取报警区域配置信息。
  • get_alarm_devices - 获取安全设备列表。
  • arm_alarm_partition - 布防特定的报警分区。
  • disarm_alarm_partition - 撤防报警分区。
  • get_users - 获取系统用户和权限信息。
  • get_user_locations - 获取用户位置跟踪信息。

网络与连接管理

  • get_network_status - 获取网络连接状态。
  • get_wifi_networks - 获取可用的 Wi-Fi 网络。
  • get_network_devices - 获取已连接的网络设备。

高级功能

  • get_sprinkler_zones - 管理灌溉系统。
  • control_sprinkler_zone - 控制洒水区域。
  • get_custom_events - 获取自定义事件定义。
  • emit_custom_event - 触发自定义事件。
  • get_system_backups - 管理系统备份。
  • create_system_backup - 创建新的系统备份。
  • get_system_diagnostics - 获取系统健康诊断信息。
  • get_ios_devices - 管理 iOS 设备。
  • get_quickapps - 管理 QuickApp。
  • get_quickapp_logs - 分析 QuickApp 日志。

系统智能与上下文分析

  • get_system_context - 获取全面的系统概述。
  • get_device_relationships - 获取设备关系和房间分配信息。
  • get_automation_suggestions - 获取 AI 驱动的自动化建议。
  • get_device_usage_patterns - 分析设备使用情况和模式。
  • explain_device_capabilities - 详细解释设备的功能。

HC3 编程文档

  • get_hc3_configuration_guide - 获取完整的 HC3 配置文档。
  • get_hc3_quickapp_programming_guide - 获取 QuickApp 编程参考。
  • get_hc3_lua_scenes_guide - 获取 Lua 场景编程文档。
  • get_hc3_programming_examples - 获取实用的代码示例和片段。

QuickApp 文件管理

  • list_quickapp_files - 获取 QuickApp 的所有源文件列表。
  • get_quickapp_file - 获取特定 QuickApp 文件的详细信息，包括内容。
  • create_quickapp_file - 为 QuickApp 创建新的源文件。
  • update_quickapp_file - 更新现有的 QuickApp 源文件。
  • update_multiple_quickapp_files - 一次性更新多个 QuickApp 文件。
  • delete_quickapp_file - 删除 QuickApp 源文件（主文件不可删除）。
  • export_quickapp - 将 QuickApp 导出为 .fqa 文件格式（开源或加密）。
  • import_quickapp - 从 .fqa / .fqax 文件导入 QuickApp（需要上传文件）。

插件管理与配置

  • get_plugins - 获取所有可用的插件，包括已安装和可用的插件。
  • get_installed_plugins - 获取系统上已安装的插件列表。
  • get_plugin_types - 获取所有插件类型及其分类信息。
  • get_plugin_view - 获取设备的插件视图/配置界面。
  • update_plugin_view - 更新插件视图组件的属性。
  • call_ui_event - 触发插件界面元素上的 UI 事件。
  • create_child_device - 为插件创建子设备（多通道设备）。
  • manage_plugin_interfaces - 为设备添加或移除接口。
  • restart_plugin - 重启插件/设备。
  • update_device_property - 直接更新设备属性的值。
  • publish_plugin_event - 通过插件系统发布各种系统事件。
  • get_ip_cameras - 获取可供安装的 IP 摄像机类型。
  • install_plugin - 按类型安装插件。
  • delete_plugin - 按类型删除/卸载插件。

每个工具都包含全面的输入验证、错误处理和详细的响应数据，有助于 AI 助手有效理解和操作你的斐波那契 HC3 系统。

开发相关

从源代码构建

# 克隆仓库
git clone <repository-url>
cd hc3-mcp-server

# 安装依赖
npm install

# 编译 TypeScript
npm run compile

# 打包扩展
npm run package

在开发环境中运行

  1. 在 VS Code 中打开项目。
  2. 按下 F5 运行扩展开发主机。
  3. 在新的 VS Code 窗口中测试扩展。

测试

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

🔧 技术细节

安全考虑

  • 本地网络通信：此扩展通过本地网络与你的 HC3 系统进行通信。
  • 凭证存储：密码存储在 VS Code 的安全凭证存储中。
  • API 访问：扩展使用 HC3 的 REST API，并采用标准的 HTTP 基本认证。
  • 无云端通信：所有通信均在 VS Code 和你的 HC3 系统之间直接进行。

故障排除

连接问题

  1. 验证 HC3 系统：确保你的 HC3 已通电，并可在网络上访问。
  2. 检查网络设置：验证 IP 地址、端口和网络连接。
  3. 测试凭证：确保用户名和密码正确，且用户具有 API 访问权限。
  4. 测试连接：使用 “HC3 MCP: Test Fibaro HC3 Connection” 命令验证设置。

配置问题

  1. VS Code 设置：检查 VS Code 设置中所有必填字段是否已填写。
  2. 环境变量：如果使用 ~/.env 文件，确保该文件存在且格式正确：
HC3_URL=http://192.168.1.57
HC3_USER=admin
HC3_PASSWORD=your_password
  1. 文件权限：确保 ~/.env 文件可读。
  2. 重启 VS Code：更改 ~/.env 文件后，需重启 VS Code。

MCP 服务器问题

  1. 检查扩展激活状态：验证扩展是否已启用并激活。
  2. 查看输出面板：在 VS Code 开发者控制台中查找错误消息。
  3. 验证 MCP 注册：确保 MCP 服务器显示在 AI 助手设置中。
  4. 重启 VS Code：有时重启可解决注册问题。

常见错误消息

  • “Fibaro HC3 not configured”：配置设置或检查 ~/.env 文件。
  • “Connection refused”：检查网络连接和 HC3 系统状态。
  • “Authentication failed”：验证用户名和密码。
  • “HTTP 404”：检查 HC3 固件版本和 API 可用性。
  • “Configuration incomplete”：确保提供了所有必需的设置。

已知问题

  • 尚不支持 IPv6 地址。
  • HTTPS 连接需要额外配置。
  • 某些高级设备类型可能需要特定的操作命令。

🤝 贡献说明

欢迎贡献代码！请按以下步骤操作：

  1. 分叉仓库。
  2. 创建功能分支。
  3. 进行更改。
  4. 如有必要，添加测试。
  5. 提交拉取请求。

版本发布说明

0.0.1

  • 初始版本发布。
  • 基本的 MCP 服务器集成。
  • 核心 HC3 设备和场景管理。
  • 配置和测试命令。

📄 许可证

MIT 许可证

支持与反馈

如有问题或疑问，请通过以下途径反馈：

尽情享受 AI 助手带来的智能家居控制体验！ 🏠🤖

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client