Androidtvmcp

🚀 AndroidTVMCP - Android TV 遠程控制到 MCP 橋接器

AndroidTVMCP 是一個模型上下文協議（MCP）服務器，它為 AI 助手和其他 MCP 客戶端提供 Android TV 遠程控制功能，能將 Android TV 控制無縫集成到基於 AI 的工作流程和自動化系統中。

🚀 快速開始

📦 安裝指南

使用虛擬環境（推薦）

# 創建虛擬環境
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 問題
• 文檔
• MCP 協議文檔

🌟 相關項目

• androidtvremote2 - Android TV 遠程控制庫
• 模型上下文協議 - 協議規範