Smart Appliance MCP

An MCP server that lets any MCP-capable LLM client discover and control smart appliances on the local network.

The important design choice is adapter-driven routing:

1. discover_devices scans with every registered adapter.
2. Each discovered device stores its provider.
3. Later calls use only deviceId; the server looks up the device and routes the command to the adapter found during discovery.

That keeps client prompts simple. The LLM client does not need to know whether a TV is Roku, Home Assistant, Samsung, LG, Matter, or something else.

Tools

• discover_devices: finds appliances and remembers them for this server session.
• diagnose_discovery: explains discovery state and likely network blockers without asking users to edit technical config.
• list_known_devices: returns devices already found.
• get_device_controls: shows available capabilities for one device.
• discover_apps: probes app launch targets exposed by a discovered media device.
• search_apps: searches discovered apps by name, package id, category hints, and launchability.
• pair_device: starts one-time consumer pairing when a provider requires it.
• complete_pairing: completes pairing with the code shown on the appliance.
• list_pairings: lists locally stored pairings.
• remove_pairing: removes a locally stored pairing.
• control_device: performs actions such as volume, navigation, power, search, and app launch.
• search_content: searches installed apps or native content providers when supported.
• suggest_content: returns adapter-aware viewing suggestions.
• record_watch_event: remembers watched, liked, dismissed, or started content.
• list_watch_history: shows the recent local watch history used by recommendations.
• recommend_content: ranks what to watch next by category, freshness, app, watch history, and app launchability.
• get_device_state: returns state when an adapter supports it.

Included Adapters

• roku: discovers Roku TVs and Roku streaming devices over SSDP and controls them through Roku ECP.
• smart_appliance_companion: discovers the optional TV-side companion app over mDNS and uses it for installed app listing and package launch.
• google_tv_remote: discovers Google TV / Android TV devices through mDNS Google Cast signals and DIAL/SSDP, then models the normal remote-style pairing flow.
• home_assistant: optional broad appliance bridge for TVs, lights, switches, thermostats, and more.
• google_tv: optional ADB fallback for development/testing only. Enable with ENABLE_ADB_ADAPTER=true.

Quick Start

npm install
npm run build
npm start

For local development:

npm run dev

Client Configuration

Build the project, then add a server entry like this to your MCP client:

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

If you use Home Assistant, include:

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

For Google TV / Android TV, use the consumer pairing flow. The server discovers the TV through local-network signals such as mDNS _googlecast._tcp.local and DIAL/SSDP, then carries the address internally on the discovered device record.

The intended user flow is:

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

Discovered Google TV devices use provider: "google_tv_remote". Pairing state is stored locally and routed through the same adapter registry as every other provider.

The Google TV remote adapter includes local discovery, consumer pairing, live remote controls, app launch probing, and adapter-routed command execution. The ADB adapter and GOOGLE_TV_REMOTE_DEVICES override remain available only as opt-in development diagnostics, not normal user setup.

App discovery is intentionally adapter-driven too. On Google TV, discover_apps probes launch surfaces the TV exposes locally, such as DIAL /apps/<name> endpoints. If the TV does not expose an installed app list through the consumer remote or DIAL interfaces, the server reports that clearly instead of pretending a guessed package name or browser URL is a discovered app launch path.

For the best Google TV experience, install the optional companion app from companion/google-tv. The companion runs on the TV, advertises _smart-appliance._tcp.local, lists installed Leanback launcher apps with Android PackageManager, and launches apps locally by package name. This is the normal-user path for apps like Crunchyroll that do not expose DIAL launch endpoints.

Recommendations

The recommendation layer is local-first and adapter-aware:

1. Adapter watch history is used first when the discovered device can provide it.
2. record_watch_event stores lightweight local fallback history, including app, title, categories, progress, and status.
3. recommend_content merges TV-sourced history, local fallback history, a provided content catalog, and starter rows.
4. Results are scored for freshness, category overlap with recent viewing, app availability, launchability, and seen/dismissed state.
5. The response separates fresh recommendations from alreadyWatched and dismissed matches.
6. Each recommendation includes userSummary/userReasons for clean user-facing answers, plus detailed fields for internal planning.
7. Actionable recommendation rows include artwork and actions:
   • artwork.thumbnailUrl, posterUrl, and backdropUrl for images.
   • actions.preview for trailers or preview clips when a catalog supplies previewUrl/trailerUrl.
   • actions.primary as the one-click watch action, expressed as an MCP tool call payload.
8. chatCards and format_recommendation_cards render the same results for chat clients:
   • Images are included only when the catalog supplies title-specific artwork.
   • Preview links use normal web URLs.
   • Watch/search links use mcp://action?... URLs that describe the MCP tool call for the host client to confirm and execute.

If the current adapter cannot provide TV watch history, list_watch_history, recommend_content, and format_recommendation_cards return an optional companionPrompt. Google TV's consumer remote protocol does not expose private per-app streaming history, so exact content history requires a provider integration or an optional TV-side companion source.

Provider catalogs change constantly, so production clients should pass fresh catalog rows into recommend_content from a provider integration, search connector, or user-owned media source. The MCP does not claim live Netflix/Crunchyroll catalogs unless an adapter or connector supplies them.

Frontend Watch Queue

Run a local UI for actionable recommendations:

npm run ui

Open http://localhost:5177. The UI renders MCP recommendation output as cards with artwork, preview, one-click watch actions, filtering, search, and an already-watched panel. Use the {} button to paste a recommend_content response from any LLM client.

For chat-native cards, call format_recommendation_cards with the same inputs as recommend_content. It returns cards plus Markdown, using links instead of buttons. By default, links point at the local UI action endpoint, so keep npm run ui running:

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

Use linkMode: "mcp_scheme" if a host client supports mcp://action?... links directly.

Example Tool Flow

First ask the client:

Discover my smart appliances.

Then:

Turn the living room TV volume up.

The MCP server handles the routing internally:

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

Adding a New Adapter

Create a class that implements 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 };
  }
}

Then register it in src/index.ts:

registry.register(new SamsungTizenAdapter());

Discovery remains the source of truth. Once a Samsung TV is discovered with provider: "samsung_tizen", all future commands for that deviceId route to the Samsung adapter automatically.

Notes

• Local-network discovery depends on your network allowing multicast/SSDP.
• Some TV ecosystems require pairing before control; those adapters should expose a pairing flow as an MCP tool or resource.
• Content recommendations are adapter-aware but can be made stronger by combining device capabilities with the host LLM client's taste/profile context.