mcp-vods

以下为使用指南（Markdown）

• 项目简介

  • 该项目实现了一个 MCP 服务器，聚合多个影视数据源，提供“搜索影视”、“影视详情”和“在电视/机顶盒上播放影视”的工具，便于将资源信息以结构化形式提供给大语言模型客户端进行对话式查询和操作。

• 主要功能点

  • vods_search：从配置的来源站点搜索影视资源，支持分页和缓存，返回可用于展示的列表。
  • vods_detail：根据源站点和影视 ID，获取影视详情及可播放地址，支持返回指定剧集的播放地址。
  • moon_search、moon_detail：对 MoonTV/LunaTV 的数据源进行搜索与详情查询。
  • mitv_play_media、tvbox_play_media：在小米电视（MitV）或 TvBox 设备上远程投屏/播放影视资源。
  • 服务器传输与部署：通过 FastMCP 提供 JSON-RPC 的接口，支持 HTTP、SSE、STDIO 等传输模式，具备跨来源数据整合能力。
  • 环境变量灵活性：通过 MITV/MOON/LUNA 等环境变量控制数据源、认证信息和设备目标。

• 安装步骤

  1. 准备运行环境：Python 3.9+，安装依赖（如 fastmcp、aiohttp、pydantic、yaml、cachetools 等）。
  2. 获取代码：将本仓库克隆到本地或服务器。
  3. 安装依赖：在项目根目录执行 pip install -r requirements.txt（若存在）或逐个安装所需依赖。
  4. 启动服务器：使用模块入口运行，例如执行 python -m mcp_vods（或等效的启动方式，详见 README 的启动方式）。
  5. 选择传输模式：默认 STDIO；若需要 HTTP/ SSE，请按 README 指定的方式通过 --http 参数启用，或使用 docker/uvx 启动方式。

• 服务器配置（给 MCP 客户端的连接信息） MCP 客户端需要至少配置服务器的启动命令及参数来建立连接。以下示例展示在不同场景下的配置信息：

  • 使用 uvx 启动的配置示例（客户端需要的关键信息为 server 名、命令和参数）: { "server": "vods", "command": "uvx", "args": ["mcp-vods"], "env": { "MITV_LIST_CFG": "客厅电视:192.168.1.11" } // 说明：通过 uvx 启动时，将本 MCP 服务器的包名作为服务名称，Vod 的数据源由环境变量 MITV_LIST_CFG 指定多台设备。 }

  • 使用 Docker 启动的配置示例（HTTP 暴露模式时的连接信息）: { "server": "vods", "url": "http://0.0.0.0:8821/mcp" // 说明：以 HTTP 流式暴露 MCP 服务，客户端通过该 URL 进行连接与调用。 }

  说明与注意事项

  • 服务器名在客户端配置中通常对应 mcpServers 的键，例如上述示例中的 vods。
  • 具体的环境变量用于选择可用的数据源与目标设备（如 MITV/MoonTV/LunaTV 的相关参数），请根据实际环境设置。
  • 服务器支持多源数据聚合，工具（Tool）会在 LLM 客户端的对话中暴露可调用的操作。

• 基本使用方法

  • 启动后，LLM 客户端可通过 MCP 的工具接口调用以下功能：影视搜索、影视详情、以及在电视/机顶盒上播放资源。
  • 常见工作流程示例（由客户端发起 JSON-RPC 调用对应工具）：
    • 搜索影视：调用 vods_search 获取与关键字相关的影视列表。
    • 查看详情：调用 vods_detail 获取选定影视的播放地址及剧集信息。
    • 远程投屏：调用 mitv_play_media 或 tvbox_play_media 将资源推送到对应设备进行播放。

• 额外信息

  • 项目内置的 moon、vods、mitv、tvbox 等工具均基于 FastMCP 的工具装饰器实现，便于通过统一的 JSON-RPC 形式暴露给前端/LLM 客户端使用。