HomeLink → Alexa → 小智 MCP

一个独立的 Node.js 桥接器，让小智语音助手调用 HomeLink 已关联到 Alexa 的家电。关键链路来自一次 ESP32 实机接入：上方灯关闭、下方灯开启均由用户确认。

你说话 → ESP32 → 小智智能体 → MCP 工具
                                  ↓
                            本机桥接程序
                                  ↓
                          Alexa → HomeLink
                                  ↓
                          智能灯 / eRemote 空调

本程序主动连接小智的云端 MCP 接入点，不开放公网家电控制端口。ESP32 继续使用原来的官方小智语音通道；厂商适配在电脑端完成。

当前范围：日本 Amazon 账号、macOS/Linux、已声明 power 能力的设备开/关。 HomeLink 与 Alexa 的账号关联是官方能力；本程序访问 Alexa 使用非官方 alexa-remote2，接口变化可能需要重新适配。调温、亮度、颜色和场景没有接入。

快速开始

需要 Node.js 22.13 或以上、可联网的电脑，以及已在 HomeLink 中正常工作的设备。先在 Alexa App 启用 HomeLink 技能、完成账号关联，确认 Alexa App 也能控制设备。官方关联说明

git clone https://github.com/owenshen0907/homelink-xiaozhi-mcp.git
cd homelink-xiaozhi-mcp
npm ci

1. 取得 Alexa 会话

npm run login

终端显示一个本机浏览器地址。由你本人登录已经关联 HomeLink 的日本 Amazon 账号，完成验证码，然后回到终端。程序通过 alexa-cookie2 的本机代理取得所需会话；它不是官方第三方 OAuth 授权应用，也不会自动复用浏览器里的 Amazon 购物网站登录。

登录代理只绑定 127.0.0.1，完成、取消或超时后关闭。日本登录所需的 OAuth 命名空间修正保留了原登录主机、PKCE 与回调，不关闭 TLS 验证。

2. 确认设备

npm run devices

复制输出中目标设备的 id。只操作 actions 中列出的能力；传感器项可以出现在目录里，但没有开关权限。

node bin/cli.mjs rename DEVICE_ID 上方灯
node bin/cli.mjs control DEVICE_ID turn_on
node bin/cli.mjs control DEVICE_ID turn_off

DEVICE_ID 是占位符，必须换成你自己的目录输出。控制命令退出码：0 为 Alexa 回报成功，1 为失败，2 为结果未确认。请观察设备真实响应；reported 只是 Alexa 回报，红外空调始终保留 unconfirmed，不能据此宣称空调已经收到红外。

3. 接入小智

在小智控制台选择 ESP32 当前使用的智能体，找到扩展能力中的 MCP 接入点，复制地址。

npm run configure

直接在终端粘贴接入点并回车，输入不回显。不要把带令牌的地址放到命令行参数、聊天或 Git。此命令只保存配置，不联网注册工具。

4. 保持桥接运行

npm start

显示 MCP 状态：ready 后，用实物语音助手试一句明确指令，例如“关闭上方灯”。按 Ctrl+C 停止。电脑与程序需保持运行，互联网、Alexa、HomeLink 和小智连接均正常时才有完整链路。

同一份数据只允许一个程序实例写入。运行其他命令前先停止 start。需要独立环境时，在命令前加 --data-dir：

node bin/cli.mjs --data-dir "$HOME/.local/share/homelink-test" configure
node bin/cli.mjs --data-dir "$HOME/.local/share/homelink-test" start

Related MCP server: ESP32 MCP Server

提供的工具与执行边界

目标不清楚时应先询问用户。执行端保留有效期、取消、重复请求检查、一次厂商写入和重启不补发；忙时拒绝新操作，不堆积指令。已发送的指令不能保证撤回。MCP 同连接的相同 RPC 编号去重；跨连接无法判断两个新调用是否表达了同一条语音，请不要让模型自动重试家电写入。

如果接入自己的后台，可以使用 src/smart-home.mjs 的 smartHome()，或组合 alexaAdapter() 与 smartHomeMcp()。MCP 工具和 CLI 共用家电执行逻辑；嵌入方需自行提供管理接口的认证、授权、CSRF 和单写入者协调。本仓没有 HTTP 管理服务器。

私有数据与退出

默认数据目录：~/.local/share/homelink-xiaozhi-mcp。

runtime-lock.json                 单实例锁（PID，不含账号信息）
smart-home/session.json           Amazon 会话
smart-home/voice.json             小智 MCP 接入点
smart-home/settings.json          自定义名称及最近 100 条控制结果
smart-home/registration-cache.json 登录代理注册缓存

这些文件属于使用者，保存在仓库外，权限0700/0600；会话是明文私有文件，不能发给他人或放在共享目录。停止程序不撤销 Amazon 服务端会话；需要彻底停用时，也应到 Amazon 账号中撤销对应注册。

异常断电或强制结束可能留下进程锁。确认没有进程再使用这份数据后，才移除 runtime-lock.json；程序不会自动删除旧锁并重复操作设备。安全说明与已知依赖告警

验证与目前的限制

npm run check
npm run format:check
npm test
npm run audit:dependencies

测试使用合成会话、模拟 Alexa 和真实本地 WebSocket，覆盖私有文件、期限、取消、幂等、重启、登录修正、MCP 工具及 CLI。CI 在 GitHub 托管 runner 上测试 Node 22/24，不使用个人授权。

原 Home Hub 集成已经通过 ESP32 实物语音控制两盏灯；独立提取版的自动测试不能代替你的真实设备验收，也不证明所有 HomeLink 型号都兼容。原实测后 ESP32 曾持续响声、失联，断电恢复但没有取得故障现场堆栈；本仓没有修改或修复固件。

版本由 package.json 管理。这次只公开源码，没有发布 npm 包、后台部署或固件更新。

接入实录与来源

• 我把 HomeLink 接进了小智：完整接入实录

• HomeLink 官方 FAQ

• alexa-remote / alexa-cookie

• Homebridge Alexa Smart Home：Alexa GraphQL 请求结构参考

• 小智官方 MCP 示例

MIT 开源，保留原来源版权声明，见 LICENSE 和 THIRD_PARTY_NOTICES。与 LinkJapan、Amazon 或小智的官方产品没有隶属关系。