androidtvmcp

🚀 AndroidTVMCP - Android TV 远程控制到 MCP 桥接器

AndroidTVMCP 是一个 Model Context Protocol (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：当前音量级别

🔧 技术细节

架构

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

组件

• MCP 服务器：处理 MCP 协议通信。
• 设备管理器：管理 Android TV 设备的发现和连接。
• 命令处理器：将 MCP 请求转换为 Android TV 命令。
• 网络层：处理 Android TV 协议通信。

开发

设置开发环境

使用虚拟环境（推荐）

# 克隆仓库
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/

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔍 故障排除

常见问题

1. 未找到设备
   • 确保 Android TV 与服务器在同一网络中。
   • 检查防火墙设置。
   • 验证设备发现功能是否已启用。
2. 连接失败
   • 检查网络连接。
   • 验证 Android TV 远程控制功能是否已启用。
   • 尝试重启 Android TV 设备。
3. 命令不起作用
   • 确保设备已开机。
   • 检查设备是否支持该命令。
   • 验证连接状态。

调试模式

启用调试日志记录：

androidtvmcp --log-level DEBUG

🤝 贡献

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 添加测试。
5. 运行测试套件。
6. 提交拉取请求。

🛠️ 支持

• GitHub 问题
• 文档
• MCP 协议文档

📚 相关项目

• androidtvremote2 - Android TV 远程控制库
• Model Context Protocol - 协议规范