HC3 MCP Server

HC3 MCP服务器

一种VS代码扩展，为Fibaro Home Center 3（HC3）智能家居系统提供模型上下文协议（MCP）服务器集成。此扩展允许VS Code中的AI助手通过自然语言命令与您的Fibaro HC3设备、场景和系统信息进行交互。

特性

• 完成Fibaro HC3 REST API集成：访问所有主要的HC3端点
• VS代码扩展集成：在VS Code中无缝注册为MCP服务器
• 配置管理：通过VS代码设置或环境变量轻松设置
• API全面覆盖：66多种工具，涵盖HC3管理的各个方面
• QuickApp开发：QuickApp开发的完整文件操作功能
• 插件管理：完整的插件配置、UI交互和生命周期管理
• 智能上下文：系统分析、自动化建议和设备关系
• 编程文档：内置HC3编程指南和示例
• 错误处理：具有详细错误消息的稳健错误处理
• 类型安全：具有正确类型的完整TypeScript实现

需求

• 菲巴罗家庭中心3：一个正在运行的具有网络访问功能的HC3系统
• VS代码：1.103.0或更高版本
• 网络接入：您的VS Code环境必须能够访问您的HC3系统
• HC3用户帐户：HC3系统的有效用户名和密码

安装和设置

1. 安装扩展:

- 从VS代码市场安装（即将推出） - 或从以下位置安装 .vsix 文件使用 Extensions: Install from VSIX... 命令

配置

方法1:VS代码设置（推荐）

1. 通过命令面板配置:

- 打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P) - 跑 HC3 MCP: Configure Fibaro HC3 Connection - 按照提示输入您的HC3详细信息

1. 手动设置:

- 转到VS代码设置 - 搜索“HC3 MCP” - 配置： - 主机：您的HC3的IP地址（例如。， 192.168.1.57) - 用户名：您的HC3用户名 - 密码：您的HC3密码 - 端口：HC3端口（默认值：80）

方法2：环境变量（回退）

创建一个 ~/.env 使用以下命令在主目录中创建文件：

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

备注：如果未配置VS代码设置，扩展将自动使用环境变量作为回退。

测试您的配置

• 跑 HC3 MCP: Test Fibaro HC3 Connection 命令
• 验证与HC3系统的连接是否成功

GitHub副本配置

为了让GitHub Copilot使用MCP服务器，您需要手动配置它：

1. 打开用户设置（JSON） 在VS代码中：

- 按 Cmd+Shift+P / Ctrl+Shift+P - 键入“首选项：打开用户设置（JSON）”

1. 添加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代码

1. 在Copilot聊天中测试:

- 重要：配置扩展后启动新的聊天会话 - “列出我的HC3设备” - “@hc3智能家居获取所有设备”

备注：如果MCP服务器工具不能立即使用，请启动一个新的GitHub Copilot聊天会话，以便它发现MCP服务器。

扩展设置

此扩展有助于以下设置：

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

用法

使用示例

配置后，扩展程序会自动提供人工智能助手可以使用的MCP服务器。您可以使用自然语言命令与HC3系统交互，例如：

基本设备控制

• “显示客厅中的所有设备”
• “打开厨房的灯”
• “将卧室调光器设置为50%”
• “把屋里的灯都关掉”

高级设备操作

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

场景管理

• “列出主卧室的所有场景”
• “播放电影夜景”
• “停止当前场景”
• “显示所有启用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的onRelease事件”
• “为多通道交换机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 -快速应用管理
• get_quickapp_logs -快速应用程序日志分析

系统智能与上下文

• get_system_context -全面的系统概述
• get_device_relationships -设备关系和房间分配
• get_automation_suggestions -人工智能驱动的自动化建议
• get_device_usage_patterns -设备使用分析和模式
• explain_device_capabilities -详细的设备性能说明

HC3编程文档

• get_hc3_configuration_guide -完整的HC3配置文档
• get_hc3_quickapp_programming_guide -快速应用程序编程参考
• get_hc3_lua_scenes_guide -Lua Scenes编程文档
• get_hc3_programming_examples -实用的代码示例和片段

QuickApp文件管理

• list_quickapp_files -获取QuickApp的所有源文件列表
• get_quickapp_file -获取特定QuickApp文件的详细信息，包括内容
• create_quickapp_file -为QuickApps创建新的源文件
• 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 -按类型删除/卸载插件

每个工具都包括全面的输入验证、错误处理和详细的响应数据，以帮助人工智能助手理解并有效地使用您的Fibaro HC3系统。

发展

从源头构建

# Clone the repository
git clone 
cd hc3-mcp-server

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package the extension
npm run package

在发展中奔跑

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

测试

# Run tests
npm test

# Run with coverage
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:测试Fibaro HC3连接”命令验证设置

配置问题

1. VS代码设置：检查是否在VS代码设置中填写了所有必填字段
2. 环境变量：如果使用~/.env，请确保文件存在并且格式正确：

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

1. 文件权限：确保~/.env文件可读
2. 需要重启：更改~/.env文件后重新启动VS代码

MCP服务器问题

1. 检查扩展激活：验证扩展是否已启用和激活
2. 检查输出面板：在VS代码开发人员控制台中查找错误消息
3. 验证MCP注册：确保MCP服务器出现在AI助手设置中
4. 重新启动VS代码：有时重新启动可以解决注册问题

常见错误消息

• “Fibaro HC3未配置”：配置设置或检查~/.env文件
• “连接被拒绝”：检查网络连接和HC3系统状态
• “身份验证失败”：验证用户名和密码
• “HTTP 404”：检查HC3固件版本和API可用性
• “配置不完整”：确保提供了所有必需的设置

已知问题

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

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

发布说明

0.0.1

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

许可证

MIT许可证

支持

对于问题和疑问：

• 菲巴罗社区

______________________________________________________________________

享受在人工智能辅助下控制智能家居的乐趣！ 🏠🤖