Smart Appliance MCP

一个 MCP 服务器，让任何支持 MCP 的 LLM 客户端都能发现并控制本地网络上的智能家电。

重要的设计选择是适配器驱动的路由：

1. discover_devices 使用每个已注册的适配器进行扫描。

2. 每个已发现的设备都会存储其 provider。

3. 后续调用仅使用 deviceId；服务器查找设备并将命令路由到发现期间找到的适配器。

这使客户端提示保持简单。LLM 客户端无需知道电视是 Roku、Home Assistant、Samsung、LG、Matter 还是其他品牌。

工具

• discover_devices：查找家电并在此服务器会话中记住它们。

• diagnose_discovery：解释发现状态和可能的网络阻塞因素，无需用户编辑技术配置。

• list_known_devices：返回已找到的设备。

• get_device_controls：显示单个设备的可用能力。

• discover_apps：探测已发现媒体设备暴露的应用启动目标。

• search_apps：按名称、包 ID、类别提示和可启动性搜索已发现的应用。

• pair_device：当提供商要求时启动一次性消费者配对。

• complete_pairing：使用设备上显示的代码完成配对。

• list_pairings：列出本地存储的配对。

• remove_pairing：移除本地存储的配对。

• control_device：执行音量、导航、电源、搜索和应用启动等操作。

• search_content：在支持时搜索已安装应用或原生内容提供商。

• suggest_content：返回适配器感知的观看建议。

• record_watch_event：记住已观看、喜欢、忽略或开始的内容。

• list_watch_history：显示推荐使用的近期本地观看历史。

• recommend_content：按类别、新鲜度、应用、观看历史和应用可启动性对接下来要观看的内容进行排序。

• get_device_state：当适配器支持时返回状态。

包含的适配器

• roku：通过 SSDP 发现 Roku 电视和 Roku 流媒体设备，并通过 Roku ECP 控制它们。

• smart_appliance_companion：通过 mDNS 发现可选的电视端配套应用，并使用它进行已安装应用列表和包启动。

• google_tv_remote：通过 mDNS Google Cast 信号和 DIAL/SSDP 发现 Google TV / Android TV 设备，然后模拟正常的遥控器式配对流程。

• home_assistant：可选的广泛设备桥接，适用于电视、灯光、开关、恒温器等。

• google_tv：仅用于开发/测试的可选 ADB 回退。使用 ENABLE_ADB_ADAPTER=true 启用。

快速开始

npm install
npm run build
npm start

用于本地开发：

npm run dev

客户端配置

构建项目，然后将如下服务器条目添加到你的 MCP 客户端：

{
  "mcpServers": {
    "smart-appliance": {
      "command": "node",
      "args": ["/absolute/path/to/smart-appliance-mcp/dist/index.js"]
    }
  }
}

如果你使用 Home Assistant，请包含：

{
  "env": {
    "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
    "HOME_ASSISTANT_TOKEN": "your-long-lived-access-token"
  }
}

对于 Google TV / Android TV，使用消费者配对流程。服务器通过局域网信号（如 mDNS _googlecast._tcp.local 和 DIAL/SSDP）发现电视，然后在已发现设备记录上内部携带地址。

预期的用户流程是：

Discover my smart appliances.
Pair my living room TV.
Complete pairing with code 123456.
Turn the TV volume up.

已发现的 Google TV 设备使用 provider: "google_tv_remote"。配对状态存储在本地，并通过与所有其他提供商相同的适配器注册表进行路由。

Google TV 远程适配器包括本地发现、消费者配对、实时远程控制、应用启动探测和适配器路由的命令执行。ADB 适配器和 GOOGLE_TV_REMOTE_DEVICES 覆盖仅作为可选的开发诊断工具保留，而非正常用户设置。

应用发现也刻意采用适配器驱动。在 Google TV 上，discover_apps 探测电视本地暴露的启动表面，例如 DIAL /apps/<name> 端点。如果电视未通过消费者远程或 DIAL 接口暴露已安装应用列表，服务器会明确报告，而不是假装猜测的包名或浏览器 URL 是已发现的应用启动路径。

为了获得最佳 Google TV 体验，请从 companion/google-tv 安装可选的配套应用。该配套应用在电视上运行，广播 _smart-appliance._tcp.local，使用 Android PackageManager 列出已安装的 Leanback 启动器应用，并按包名在本地启动应用。这是针对 Crunchyroll 等不暴露 DIAL 启动端点的应用的正常用户路径。

推荐

推荐层是本地优先且适配器感知的：

1. 当已发现设备可以提供时，优先使用适配器观看历史。

2. record_watch_event 存储轻量级本地回退历史，包括应用、标题、类别、进度和状态。

3. recommend_content 合并电视来源的历史、本地回退历史、提供的内容目录和起始行。

4. 结果按新鲜度、与近期观看的类别重叠、应用可用性、可启动性以及已看/已忽略状态进行评分。

5. 响应将新鲜的 recommendations 与 alreadyWatched 和 dismissed 匹配分开。

6. 每条推荐都包含 userSummary/userReasons 以提供清晰面向用户的答案，以及用于内部规划的详细字段。

7. 可操作的推荐行包含插图和操作：

   • artwork.thumbnailUrl、posterUrl 和 backdropUrl 用于图片。

   • 当目录提供 previewUrl/trailerUrl 时，actions.preview 用于预告片或预览片段。

   • actions.primary 作为一键观看操作，表示为 MCP 工具调用负载。

8. chatCards 和 format_recommendation_cards 为聊天客户端渲染相同的结果：

   • 仅在目录提供标题特定图片时才包含图片。

   • 预览链接使用正常 Web URL。

   • 观看/搜索链接使用 mcp://action?... URL，描述 MCP 工具调用供主机客户端确认和执行。

如果当前适配器无法提供电视观看历史，list_watch_history、recommend_content 和 format_recommendation_cards 会返回可选的 companionPrompt。Google TV 的消费者远程协议不暴露私有的按应用流媒体历史，因此精确的内容历史需要提供商集成或可选的电视端配套来源。

提供商目录不断变化，因此生产客户端应从提供商集成、搜索连接器或用户拥有的媒体源将新鲜目录行传入 recommend_content。除非适配器或连接器提供，否则 MCP 不声称拥有实时的 Netflix/Crunchyroll 目录。

前端观看队列

运行本地 UI 以获取可操作的推荐：

npm run ui

打开 http://localhost:5177。UI 将 MCP 推荐输出渲染为卡片，包含插图、预览、一键观看操作、筛选、搜索和已观看面板。使用 {} 按钮粘贴来自任何 LLM 客户端的 recommend_content 响应。

对于聊天原生卡片，使用与 recommend_content 相同的输入调用 format_recommendation_cards。它返回 cards 以及 Markdown，使用链接而不是按钮。默认情况下，链接指向本地 UI 操作端点，因此请保持 npm run ui 运行：

[Watch on TV](http://127.0.0.1:5177/api/actions/run?payload=...)

如果主机客户端直接支持 mcp://action?... 链接，请使用 linkMode: "mcp_scheme"。

示例工具流程

首先询问客户端：

Discover my smart appliances.

然后：

Turn the living room TV volume up.

MCP 服务器在内部处理路由：

const device = registry.getDevice(deviceId);
const adapter = registry.adapterFor(device);
await adapter.control(device, request);

添加新适配器

创建一个实现 SmartApplianceAdapter 的类：

export class SamsungTizenAdapter implements SmartApplianceAdapter {
  readonly id = "samsung_tizen";
  readonly label = "Samsung Tizen TV";

  async discover(options: DiscoveryOptions): Promise<SmartDevice[]> {
    return [];
  }

  async control(device: SmartDevice, request: ControlRequest) {
    return { ok: true };
  }
}

然后在 src/index.ts 中注册它：

registry.register(new SamsungTizenAdapter());

发现始终是事实来源。一旦使用 provider: "samsung_tizen" 发现三星电视，该 deviceId 的所有后续命令都会自动路由到三星适配器。

备注

• 本地网络发现取决于你的网络是否允许多播/SSDP。

• 某些电视生态系统在控制前需要配对；这些适配器应将配对流程作为 MCP 工具或资源暴露。

• 内容推荐是适配器感知的，但可以通过结合设备能力与主机 LLM 客户端的品味/偏好上下文来增强。