AndroidTVMCP - Android TV遥控器到MCP桥接

一个模型上下文协议（MCP）服务器，提供Android TV遥控器功能给AI助手和其他MCP客户端。

概述

AndroidTVMCP将Android TV遥控器能力与模型上下文协议连接起来，使Android TV控制能够无缝集成到由AI驱动的工作流程和自动化系统中。

特性

• 设备发现：自动检测本地网络上的Android TV设备
• 遥控器：完整的导航和播放控制能力
• 应用管理：启动并切换Android TV应用程序
• 状态监控：查询设备状态和当前状态
• MCP集成：符合标准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上当前播放的是什么？"

配置

创建配置文件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客户端     │◄──►│  AndroidTVMCP   │◄──►│   Android TV    │
│  (AI助手)       │    │    服务器       │    │   设备          │
└─────────────────┘    └─────────────────┘    └─────────────────┘

组件

• 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遥控库
• 模型上下文协议 - 协议规范