tvpilot

tvpilot

tvpilot は、ペアリング済みの Android TV または Google TV を操作します。ペアリング済みデバイスの一覧表示、リモートキーイベントの送信、アプリやインテントの起動、話し言葉風のタイトルから適切なストリーミングプロバイダーを特定して再生する操作、画面の表示内容の読み取りができます。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を提供します。

呼び出しは TVWizard リレーを経由し、WebSocket を介してテレビ上で動作するブリッジアプリに転送されるため、同一ネットワークへの接続、VPN、ポートフォワーディングの設定は不要です。ペアリングはブリッジアプリで一度だけ行います。アプリに表示されるコードを登録すると、テレビ用のベアラートークンを受け取れます。

設定

このツールは、次の 2 つの環境変数で設定します。

• TVWIZARD_TOKEN（必須）— テレビをペアリングしたときに発行されるベアラートークンです。設定されていない場合、すべての呼び出しはこの変数名を示すエラーで失敗します。認証なしでの呼び出しや、偽の結果はありません。
• TVWIZARD_MCP_URL（任意）— リレーのエンドポイントです。デフォルトは https://tv.djwizard.ai/api/mcp です。注：公開されている TVWizard のドキュメントではリレーのアーキテクチャとベアラー認証について説明されていますが、リレーの生の HTTP パスは公開されていません。そのため、このデフォルトのエンドポイントはドキュメントに基づく再構成です。リレーで別のパスが公開されている場合は、上書きしてください。

インストール

npx @reneturcios/tvpilot devices

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/tvpilot

コンテナはデフォルトで MCP サーバーとして動作します（下記参照）。CLI として使用するには、CLI の引数を渡してください。

CLI

tvpilot devices
tvpilot key POWER
tvpilot launch https://www.youtube.com/watch?v=jNQXAC9IVRw --package com.google.android.youtube.tv
tvpilot apps
tvpilot play Stranger Things --country US --season 2 --episode 3 --year 2016 --provider netflix
tvpilot observe

tvpilot --version

コマンドはリレーの JSON ペイロードを出力します。終了コード：成功時は 0、呼び出し失敗時（トークンの未設定や上流リレーのエラーを含む）は 1、使用方法のエラー時は 2 です。

tvpilot key で使えるキーは POWER、HOME、UP、DOWN、LEFT、RIGHT、OK、BACK、VOL_UP、VOL_DOWN です。--provider で指定できるプロバイダーは netflix、disney_plus、prime_video、max、hulu、apple_tv_plus、paramount_plus、peacock、fubo_tv、youtube、stremio です。

tvpilot observe の実行には、ブリッジアプリに Android AccessibilityService の権限を付与する必要があります。権限がない状態で初めて呼び出すと、テレビにセットアップのプロンプトが表示されたことを説明する accessibility_not_granted エラーが返されます。プロンプトをタップしてから、再試行してください。

MCP サーバー

1 つのバイナリで、どちらの機能も提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/tvpilot mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "tvpilot": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tvpilot", "mcp"],
      "env": { "TVWIZARD_TOKEN": "<your token>" }
    }
  }
}

ツール

ツール	入力	返される内容
tv.list_devices	（なし）	呼び出し元のトークンにペアリングされたテレビの一覧。それぞれに id と online フラグが含まれます。
tv.send_key	key（必須）	キーイベントを 1 つ送信します。使用できるキーは、上記の 10 種類です。
tv.launch_app	data（必須）、package（任意）	インテント URI、ディープリンク、または URL を開きます。必要に応じて、指定したパッケージで開きます。
tv.list_apps	（なし）	インストール済みアプリの一覧。package、label と、テレビ用ランチャーのアプリかどうかを示す leanback フラグが含まれます。
tv.play_title	title（必須）；country、season、episode、year、provider（任意）	タイトルをプロバイダーのディープリンクに解決して再生します。
tv.observe	（なし）	フォアグラウンドのパッケージ／アクティビティ、フォーカスされている要素、表示されているクリック可能なノードを返します。

上流での失敗（見つからないタイトル、選択した国でそのタイトルを配信するプロバイダーがない場合、リゾルバーが無効になっているリレー、アクセシビリティ権限がまだ付与されていない場合）は、リレー独自のメッセージを含むエラー結果として返されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。