🚀 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
💻 使用示例
基础用法
- 启动 MCP 服务器：
androidtvmcp --host localhost --port 8080
- 配置你的 MCP 客户端以连接到服务器。
- 通过你的 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 文件。
🔍 故障排除
常见问题
- 未找到设备
- 确保 Android TV 与服务器在同一网络中。
- 检查防火墙设置。
- 验证设备发现功能是否已启用。
- 连接失败
- 检查网络连接。
- 验证 Android TV 远程控制功能是否已启用。
- 尝试重启 Android TV 设备。
- 命令不起作用
- 确保设备已开机。
- 检查设备是否支持该命令。
- 验证连接状态。
调试模式
启用调试日志记录：
androidtvmcp --log-level DEBUG
🤝 贡献
- 分叉仓库。
- 创建功能分支。
- 进行更改。
- 添加测试。
- 运行测试套件。
- 提交拉取请求。
🛠️ 支持
📚 相关项目
- androidtvremote2 - Android TV 远程控制库
- Model Context Protocol - 协议规范