Smart Appliance MCP

Ein MCP-Server, der es jedem MCP-fähigen LLM-Client ermöglicht, intelligente Geräte im lokalen Netzwerk zu entdecken und zu steuern.

Die wichtigste Designentscheidung ist das adaptergesteuerte Routing:

1. discover_devices scannt mit jedem registrierten Adapter.

2. Jedes entdeckte Gerät speichert seinen provider.

3. Spätere Aufrufe verwenden nur deviceId; der Server schlägt das Gerät nach und leitet den Befehl an den bei der Entdeckung gefundenen Adapter weiter.

Das hält die Client-Prompts einfach. Der LLM-Client muss nicht wissen, ob ein Fernseher Roku, Home Assistant, Samsung, LG, Matter oder etwas anderes ist.

Werkzeuge

• discover_devices: findet Geräte und merkt sie sich für diese Server-Sitzung.

• diagnose_discovery: erklärt den Entdeckungszustand und wahrscheinliche Netzwerkblocker, ohne dass Benutzer technische Konfigurationen bearbeiten müssen.

• list_known_devices: gibt bereits gefundene Geräte zurück.

• get_device_controls: zeigt verfügbare Funktionen für ein Gerät.

• discover_apps: prüft App-Startziele, die ein entdecktes Mediengerät verfügbar macht.

• search_apps: durchsucht entdeckte Apps nach Name, Paket-ID, Kategoriehinweisen und Startbarkeit.

• pair_device: startet einmaliges Consumer-Pairing, wenn ein Provider es erfordert.

• complete_pairing: schließt das Pairing mit dem auf dem Gerät angezeigten Code ab.

• list_pairings: listet lokal gespeicherte Pairings auf.

• remove_pairing: entfernt ein lokal gespeichertes Pairing.

• control_device: führt Aktionen wie Lautstärke, Navigation, Ein/Aus, Suche und App-Start aus.

• search_content: durchsucht installierte Apps oder native Inhaltsanbieter, sofern unterstützt.

• suggest_content: gibt adapterbewusste Sehempfehlungen zurück.

• record_watch_event: merkt sich gesehene, gemochte, verworfene oder gestartete Inhalte.

• list_watch_history: zeigt den aktuellen lokalen Sehverlauf, der für Empfehlungen verwendet wird.

• recommend_content: ordnet, was als Nächstes angesehen werden soll, nach Kategorie, Aktualität, App, Sehverlauf und App-Startbarkeit.

• get_device_state: gibt den Zustand zurück, wenn ein Adapter dies unterstützt.

Enthaltene Adapter

• roku: entdeckt Roku-Fernseher und Roku-Streaming-Geräte über SSDP und steuert sie über Roku ECP.

• smart_appliance_companion: entdeckt die optionale TV-seitige Companion-App über mDNS und verwendet sie zum Auflisten installierter Apps und zum Starten per Paketnamen.

• google_tv_remote: entdeckt Google-TV-/Android-TV-Geräte über mDNS-Google-Cast-Signale und DIAL/SSDP und bildet dann den normalen Pairing-Ablauf im Fernbedienungsstil ab.

• home_assistant: optionale breite Gerätebrücke für Fernseher, Lampen, Schalter, Thermostate und mehr.

• google_tv: optionaler ADB-Rückgriff nur für Entwicklung/Tests. Mit ENABLE_ADB_ADAPTER=true aktivieren.

Schnellstart

npm install
npm run build
npm start

Für die lokale Entwicklung:

npm run dev

Client-Konfiguration

Bauen Sie das Projekt und fügen Sie dann einen Servereintrag wie folgt zu Ihrem MCP-Client hinzu:

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

Wenn Sie Home Assistant verwenden, fügen Sie Folgendes ein:

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

Für Google TV / Android TV verwenden Sie den Consumer-Pairing-Ablauf. Der Server entdeckt den Fernseher über lokale Netzwerksignale wie mDNS _googlecast._tcp.local und DIAL/SSDP und speichert die Adresse intern im Datensatz des entdeckten Geräts.

Der vorgesehene Benutzerablauf ist:

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

Entdeckte Google-TV-Geräte verwenden provider: "google_tv_remote". Der Pairing-Zustand wird lokal gespeichert und über dieselbe Adapter-Registry wie bei jedem anderen Provider geroutet.

Der Google-TV-Remote-Adapter umfasst lokale Entdeckung, Consumer-Pairing, Live-Fernbedienungssteuerung, App-Startuntersuchung und adaptergeroutete Befehlsausführung. Der ADB-Adapter und die GOOGLE_TV_REMOTE_DEVICES-Überschreibung bleiben nur als optionale Entwicklungsdiagnose verfügbar, nicht für die normale Benutzereinrichtung.

Auch die App-Entdeckung ist bewusst adaptergesteuert. Auf Google TV prüft discover_apps lokale Startmöglichkeiten, die der Fernseher bereitstellt, wie etwa DIAL-Endpunkte /apps/<name>. Wenn der Fernseher keine installierte App-Liste über die Consumer-Fernbedienung oder DIAL-Schnittstellen bereitstellt, meldet der Server dies deutlich, anstatt so zu tun, als sei ein geratener Paketname oder eine Browser-URL ein entdeckter App-Startpfad.

Installieren Sie für die beste Google-TV-Erfahrung die optionale Companion-App aus companion/google-tv. Die Companion-App läuft auf dem Fernseher, veröffentlicht _smart-appliance._tcp.local, listet installierte Leanback-Launcher-Apps mit dem Android-PackageManager auf und startet Apps lokal anhand des Paketnamens. Dies ist der normale Benutzerpfad für Apps wie Crunchyroll, die keine DIAL-Start-Endpunkte bereitstellen.

Empfehlungen

Die Empfehlungsschicht arbeitet lokal zuerst und adapterbewusst:

1. Der Sehverlauf des Adapters wird zuerst verwendet, wenn das entdeckte Gerät ihn bereitstellen kann.

2. record_watch_event speichert einen leichtgewichtigen lokalen Fallback-Verlauf, einschließlich App, Titel, Kategorien, Fortschritt und Status.

3. recommend_content führt den vom Fernseher stammenden Verlauf, lokalen Fallback-Verlauf, einen bereitgestellten Inhaltskatalog und Startzeilen zusammen.

4. Ergebnisse werden nach Aktualität, Kategorieüberschneidung mit kürzlich Gesehenem, App-Verfügbarkeit, Startbarkeit und bereits gesehenem/verworfenem Status bewertet.

5. Die Antwort trennt frische recommendations von alreadyWatched- und dismissed-Treffern.

6. Jede Empfehlung enthält userSummary/userReasons für saubere benutzerseitige Antworten sowie detaillierte Felder für die interne Planung.

7. Umsetzbare Empfehlungszeilen enthalten Artwork und Aktionen:

   • artwork.thumbnailUrl, posterUrl und backdropUrl für Bilder.

   • actions.preview für Trailer oder Vorschauclips, wenn ein Katalog previewUrl/trailerUrl liefert.

   • actions.primary als Ein-Klick-Aktion zum Ansehen, ausgedrückt als Nutzlast eines MCP-Toolaufrufs.

8. chatCards und format_recommendation_cards rendern dieselben Ergebnisse für Chat-Clients:

   • Bilder werden nur einbezogen, wenn der Katalog titelspezifisches Artwork liefert.

   • Vorschau-Links verwenden normale Web-URLs.

   • Ansehen-/Such-Links verwenden mcp://action?...-URLs, die den MCP-Toolaufruf für den Host-Client beschreiben, damit er ihn bestätigen und ausführen kann.

Wenn der aktuelle Adapter keinen TV-Sehverlauf bereitstellen kann, geben list_watch_history, recommend_content und format_recommendation_cards einen optionalen companionPrompt zurück. Das Consumer-Fernbedienungsprotokoll von Google TV legt keinen privaten Streaming-Verlauf pro App offen. Daher erfordert ein exakter Inhaltsverlauf eine Provider-Integration oder eine optionale TV-seitige Companion-Quelle.

Provider-Kataloge ändern sich ständig. Daher sollten Produktions-Clients frische Katalogzeilen aus einer Provider-Integration, einem Such-Konnektor oder einer benutzereigenen Medienquelle an recommend_content übergeben. Der MCP erhebt keinen Anspruch auf Live-Kataloge von Netflix/Crunchyroll, sofern nicht ein Adapter oder Konnektor sie bereitstellt.

Frontend-Warteschlange

Starten Sie eine lokale Benutzeroberfläche für umsetzbare Empfehlungen:

npm run ui

Öffnen Sie http://localhost:5177. Die UI rendert die MCP-Empfehlungsausgabe als Karten mit Artwork, Vorschau, Ein-Klick-Aktionen zum Ansehen, Filterung, Suche und einem Panel „Bereits gesehen“. Verwenden Sie die Schaltfläche {}, um eine recommend_content-Antwort aus einem beliebigen LLM-Client einzufügen.

Für chat-native Karten rufen Sie format_recommendation_cards mit denselben Eingaben wie recommend_content auf. Es gibt cards plus Markdown zurück und verwendet Links anstelle von Schaltflächen. Standardmäßig zeigen Links auf den lokalen UI-Aktions-Endpunkt. Lassen Sie daher npm run ui laufen:

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

Verwenden Sie linkMode: "mcp_scheme", wenn ein Host-Client mcp://action?...-Links direkt unterstützt.

Beispiel-Tool-Ablauf

Fragen Sie zuerst den Client:

Discover my smart appliances.

Dann:

Turn the living room TV volume up.

Der MCP-Server übernimmt das Routing intern:

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

Hinzufügen eines neuen Adapters

Erstellen Sie eine Klasse, die SmartApplianceAdapter implementiert:

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 };
  }
}

Registrieren Sie sie dann in src/index.ts:

registry.register(new SamsungTizenAdapter());

Die Entdeckung bleibt die maßgebliche Quelle. Sobald ein Samsung-Fernseher mit provider: "samsung_tizen" entdeckt wurde, werden alle zukünftigen Befehle für diese deviceId automatisch an den Samsung-Adapter weitergeleitet.

Hinweise

• Die Entdeckung im lokalen Netzwerk hängt davon ab, dass Ihr Netzwerk Multicast/SSDP zulässt.

• Einige TV-Ökosysteme erfordern vor der Steuerung ein Pairing; diese Adapter sollten einen Pairing-Ablauf als MCP-Tool oder -Ressource bereitstellen.

• Inhaltsempfehlungen sind adapterbewusst, können aber durch die Kombination von Gerätefunktionen mit dem Geschmacks-/Profilkontext des Host-LLM-Clients verbessert werden.