tvpilot

Name: tvpilot
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords游戏娱乐01 周前更新

代码仓库

关于 tvpilot

tvpilot 是用于控制已配对 Android TV 和 Google TV 设备的命令行工具与 stdio MCP 服务。它通过 TVWizard 中继支持遥控输入、启动应用、播放影视内容和查看屏幕。

主要功能

01列出已配对电视和已安装应用
02发送遥控按键事件
03启动应用、Intent 和网址
04解析并播放流媒体影视内容
05查看前台界面元素

适用场景

01检查已配对电视是否在线
02远程操作电视界面
03在电视上打开应用或深层链接
04查找并播放平台上的影视内容

MCP 相关

向 MCP 客户端提供列出已配对设备和应用、发送按键、启动应用、播放影视内容及查看屏幕的工具。调用经由 TVWizard 中继转发。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-tvpilot": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/tvpilot"
      ]
    }
  }
}

启动命令npx -y @reneturcios/tvpilot

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/tvpilot0.1.0stdio

ocighcr.io/cloudcorprecords/tvpilot:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

此工具无需参数。

详细介绍

tvpilot

tvpilot 可控制已配对的 Android TV 或 Google TV：列出已配对的设备、发送遥控按键事件、启动应用和 Intent、将口语化的片名解析为合适的流媒体服务提供商并播放，以及读取屏幕上显示的内容。一个二进制文件同时提供命令行界面和 stdio MCP 服务。

调用会经过 TVWizard 中继服务，并通过 WebSocket 转发给运行在电视上的桥接应用，因此无需设置同一网络、VPN 或端口转发。只需在桥接应用中配对一次：应用会显示一个代码，你领取后即可获得电视的持有者令牌。

配置

两个环境变量用于配置此工具：

TVWIZARD_TOKEN（必需）——配对电视时签发的持有者令牌。未设置时，所有调用都会失败，并提示出错的变量；不会返回未经身份验证或伪造的结果。
TVWIZARD_MCP_URL（可选）——中继端点。默认值为 https://tv.djwizard.ai/api/mcp。注意：TVWizard 的公开文档介绍了中继架构和持有者身份验证，但没有公布中继的原始 HTTP 路径，因此此默认端点是根据文档推定的；如果中继公布了不同路径，请覆盖此值。

安装

npx @reneturcios/tvpilot devices

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/tvpilot

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

tvpilot devices
tvpilot key POWER
tvpilot launch https://www.youtube.com/watch?v=jNQXAC9IVRw --package com.google.android.youtube.tv
tvpilot apps
tvpilot play Stranger Things --country US --season 2 --episode 3 --year 2016 --provider netflix
tvpilot observe

tvpilot --version

命令会输出中继服务返回的 JSON 负载。退出代码：成功时为 0，调用失败时为 1（包括令牌缺失或上游中继错误），用法错误时为 2。

tvpilot key 的按键包括 POWER、HOME、UP、DOWN、LEFT、RIGHT、OK、BACK、VOL_UP 和 VOL_DOWN。--provider 可使用的服务提供商包括 netflix、disney_plus、prime_video、max、hulu、apple_tv_plus、paramount_plus、peacock、fubo_tv、youtube 和 stremio。

tvpilot observe 需要向桥接应用授予 Android AccessibilityService 权限。首次调用时若尚未授予权限，会返回 accessibility_not_granted 错误，说明电视上已显示设置提示；点击该提示后重试。

MCP 服务

一个二进制文件同时提供两种接口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/tvpilot mcp

MCP 客户端配置：

{
  "mcpServers": {
    "tvpilot": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tvpilot", "mcp"],
      "env": { "TVWIZARD_TOKEN": "<your token>" }
    }
  }
}

工具

工具	输入	返回内容
`tv.list_devices`	（无）	与调用者的令牌配对的电视列表，每台电视都包含 `id` 和 `online` 标记。
`tv.send_key`	`key`（必需）	发送一个按键事件：可使用上文列出的十个按键之一。
`tv.launch_app`	`data`（必需），`package`（可选）	打开 Intent URI、深层链接或 URL，也可指定要在哪个包中打开。
`tv.list_apps`	（无）	已安装应用列表，包含 `package`、`label`，以及标示是否适用于电视启动器的 `leanback` 标记。
`tv.play_title`	`title`（必需）；`country`、`season`、`episode`、`year`、`provider`（可选）	将片名解析为服务提供商的深层链接并播放。
`tv.observe`	（无）	前台包/活动、获得焦点的元素，以及当前可见的可点击节点。

上游错误——例如找不到片名、所选国家/地区没有提供该片名的服务提供商、中继服务禁用了解析器，或尚未授予无障碍权限——都会作为错误结果返回，并附带中继服务自身的错误消息。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx