Androidtvmcp

🚀 AndroidTVMCP - Android TV リモコンから MCP へのブリッジ

AIアシスタントやその他のMCPクライアントにAndroid TVのリモコン機能を提供する、Model Context Protocol (MCP) サーバーです。

🚀 クイックスタート

インストール

仮想環境を使用する（推奨）

# 仮想環境を作成
python -m venv androidtvmcp-env

# 仮想環境をアクティブ化
# Linux/macOSの場合:
source androidtvmcp-env/bin/activate
# Windowsの場合:
# androidtvmcp-env\Scripts\activate

# パッケージをインストール
pip install androidtvmcp

グローバルインストール

pip install androidtvmcp

基本的な使用法

1. MCPサーバーを起動します。

androidtvmcp --host localhost --port 8080

2. MCPクライアントをサーバーに接続するように設定します。
3. AIアシスタントを介してAndroid TVのコントロールツールを使用します。

コマンド例

• ナビゲーション: "Android TVで上に移動"
• 再生: "現在のビデオを一時停止"
• アプリ: "Android TVでNetflixを起動"
• ステータス: "Android TVで現在再生されているものは何ですか？"

✨ 主な機能

• デバイス検出：ローカルネットワーク上のAndroid TVデバイスを自動検出します。
• リモコン機能：完全なナビゲーションと再生制御機能を備えています。
• アプリ管理：Android TVアプリケーションの起動と切り替えが可能です。
• 状態監視：デバイスのステータスと現在の状態を照会できます。
• MCP統合：標準的なMCPプロトコルに準拠しており、簡単に統合できます。

📚 ドキュメント

設定

config.json 設定ファイルを作成します。

{
  "devices": {
    "discovery": {
      "enabled": true,
      "timeout": 10
    },
    "connection": {
      "timeout": 5,
      "retry_attempts": 3
    }
  },
  "mcp": {
    "host": "localhost",
    "port": 8080,
    "transport": "stdio"
  },
  "logging": {
    "level": "INFO",
    "file": "androidtvmcp.log"
  }
}

MCPツール

ナビゲーションツール

• atv_navigate：Android TVのインターフェースをナビゲートします（上、下、左、右、選択、メニュー、戻る、ホーム）
• atv_input_text：Android TVにテキスト入力を送信します。

再生ツール

• atv_playback：メディア再生を制御します（再生、一時停止、停止、早送り、巻き戻し）
• atv_volume：音量を調整します（上、下、ミュート）

アプリ管理ツール

• atv_launch_app：特定のアプリケーションを起動します。
• atv_get_apps：利用可能なアプリケーションを一覧表示します。
• atv_switch_app：実行中のアプリケーションを切り替えます。

デバイスツール

• atv_get_devices：検出されたAndroid TVデバイスを一覧表示します。
• atv_get_status：現在のデバイスのステータスと状態を取得します。
• atv_power：電源を制御します（オン、オフ、スリープ）

MCPリソース

デバイス情報

• device://[device_id]/info：デバイスの機能と情報
• device://[device_id]/status：現在のデバイスのステータス
• device://[device_id]/apps：利用可能なアプリケーション

現在の状態

• state://current_app：現在アクティブなアプリケーション
• state://playback：現在の再生ステータス
• state://volume：現在の音量レベル

開発

開発環境のセットアップ

仮想環境を使用する（推奨）

# リポジトリをクローン
git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp

# 仮想環境を作成してアクティブ化
python -m venv venv

# 仮想環境をアクティブ化
# Linux/macOSの場合:
source venv/bin/activate
# Windowsの場合:
# venv\Scripts\activate

# 開発依存関係を含めて開発モードでインストール
pip install -e ".[dev]"

別のセットアップ方法

git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp
pip install -e ".[dev]"

テストの実行

pytest

開発ツール

devtools/ ディレクトリには、手動テストと検証用のスタンドアロンスクリプトが含まれています。

cd devtools
python test_command_processor.py  # コマンドプロセッサの機能をテスト
python test_mcp_client.py         # MCPクライアントとサーバーの通信をテスト
python test_mcp_integration.py    # MCPサーバーの統合をテスト

各スクリプトの詳細情報については、devtools/README.md を参照してください。

コードフォーマット

black src/ tests/
isort src/ tests/

型チェック

mypy src/

アーキテクチャ

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│  AndroidTVMCP   │◄──►│   Android TV    │
│  (AI Assistant) │    │    Server       │    │   Devices       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

コンポーネント

• MCPサーバー：MCPプロトコルの通信を処理します。
• デバイスマネージャー：Android TVデバイスの検出と接続を管理します。
• コマンドプロセッサ：MCPリクエストをAndroid TVコマンドに変換します。
• ネットワーク層：Android TVプロトコルの通信を処理します。

要件

• Python 3.8以上
• 同じネットワーク上のAndroid TVデバイス
• デバイス検出のためのネットワーク接続性

トラブルシューティング

一般的な問題

1. デバイスが見つからない場合
   • Android TVが同じネットワーク上にあることを確認してください。
   • ファイアウォールの設定を確認してください。
   • デバイス検出が有効になっていることを確認してください。
2. 接続に失敗した場合
   • ネットワーク接続性を確認してください。
   • Android TVのリモコン機能が有効になっていることを確認してください。
   • Android TVデバイスを再起動してみてください。
3. コマンドが機能しない場合
   • デバイスが電源オンになっていることを確認してください。
   • デバイスがコマンドをサポートしていることを確認してください。
   • 接続ステータスを確認してください。

デバッグモード

デバッグログを有効にします。

androidtvmcp --log-level DEBUG

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. テストスイートを実行します。
6. プルリクエストを送信します。

📄 ライセンス

MITライセンス - 詳細については LICENSE ファイルを参照してください。

サポート

• GitHub Issues
• ドキュメント
• MCPプロトコルドキュメント

関連プロジェクト

• androidtvremote2 - Android TVリモコンライブラリ
• Model Context Protocol - プロトコル仕様