# 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

```bash
npm install
npm run build
npm start
```

For local development:

```bash
npm run dev
```

## Client Configuration

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

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

If you use Home Assistant, include:

```json
{
  "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:

```text
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:

```bash
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:

```md
[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:

```text
Discover my smart appliances.
```

Then:

```text
Turn the living room TV volume up.
```

The MCP server handles the routing internally:

```ts
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`:

```ts
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`:

```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.