Smart Appliance MCP

MCP対応のLLMクライアントがローカルネットワーク上のスマート家電を検出・制御できるようにするMCPサーバーです。

重要な設計上の選択は、アダプター駆動のルーティングです。

1. discover_devices は登録済みのすべてのアダプターでスキャンします。

2. 検出された各デバイスは自身の provider を保存します。

3. 以降の呼び出しは deviceId のみを使用し、サーバーはデバイスを検索して、検出時に見つかったアダプターにコマンドをルーティングします。

これにより、クライアントのプロンプトはシンプルに保たれます。LLMクライアントは、テレビがRoku、Home Assistant、Samsung、LG、Matter、その他のどれであるかを知る必要はありません。

ツール

• discover_devices: 家電を検出し、このサーバーセッション中は記憶します。

• diagnose_discovery: ユーザーに技術的な設定変更を求めることなく、検出状態と想定されるネットワーク上の問題を説明します。

• list_known_devices: すでに検出されたデバイスを返します。

• get_device_controls: 1台のデバイスで利用可能な機能を表示します。

• 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 TVとRokuストリーミングデバイスを検出し、Roku ECPを通じて制御します。

• smart_appliance_companion: オプションのTV側コンパニオンアプリを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ランチャーアプリを一覧表示し、パッケージ名でアプリをローカルに起動します。これは、DIAL起動エンドポイントを公開しないCrunchyrollなどのアプリ向けの通常ユーザー向けパスです。

レコメンデーション

レコメンデーションレイヤーはローカルファーストかつアダプター対応です:

1. 検出されたデバイスが提供できる場合は、まずアダプターの視聴履歴が使用されます。

2. record_watch_event は、アプリ、タイトル、カテゴリ、進捗、ステータスを含む軽量なローカルフォールバック履歴を保存します。

3. recommend_content は、TV由来の履歴、ローカルフォールバック履歴、提供されたコンテンツカタログ、スターター行をマージします。

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ツール呼び出しを記述します。

現在のアダプターがTVの視聴履歴を提供できない場合、list_watch_history、recommend_content、format_recommendation_cards はオプションの companionPrompt を返します。Google TVのコンシューマーリモコンプロトコルは、アプリごとのプライベートなストリーミング履歴を公開しないため、正確なコンテンツ履歴にはプロバイダー統合またはオプションの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());

検出が真実のソースであり続けます。Samsung TVが provider: "samsung_tizen" で検出されると、その deviceId に対する将来のすべてのコマンドは自動的にSamsungアダプターにルーティングされます。

注意事項

• ローカルネットワーク検出は、ネットワークがマルチキャスト/SSDPを許可しているかどうかに依存します。

• 一部のTVエコシステムでは、制御前にペアリングが必要です。そのようなアダプターは、MCPツールまたはリソースとしてペアリングフローを公開する必要があります。

• コンテンツレコメンデーションはアダプター対応ですが、デバイスの機能とホストLLMクライアントの好み/プロファイルコンテキストを組み合わせることで、より強力にできます。