StreamXpress MCP Server

基于 DekTec StreamXpress 的 MCP（Model Context Protocol）服务，让 AI 能够通过 SpRcApi 远程控制接口来操控 TS（Transport Stream）码流推送。

前置条件

• StreamXpress v3.x 已安装

• 一块 DekTec 输出适配器（如 DTU-315），其硬件中烧录了相应授权：

  • DTC-302-RC（远程控制授权，-rc 远程控制模式必需）
  • DTC-300-SP（播放许可）或 DTC-300-NICP（本机网卡 IP 推送许可）

  这些许可证固化在 DekTec 设备硬件中，插入设备后 StreamXpress 会自动识别（设备信息中可见 Remote-control license: Yes），无需单独激活或配置文件。

• Python 3.10+

关于 StreamXpress 的安装位置：StreamXpress 由 DekTec 安装程序安装，默认位于 C:\Program Files\DekTec\StreamXpress\，不在系统 PATH 中，不能直接在任意目录下执行 StreamXpress.exe。另外，可执行文件名可能是 StreamXpress.exe（v3.x）或 StreamXpress64.exe（部分版本），请以实际安装为准，用完整路径调用。

MCP 服务本身不需要配置 StreamXpress 的安装位置——它通过 SpRcApi（HTTP/SOAP）远程控制接口连接 StreamXpress，只需在 connect 工具中指定 StreamXpress 所在主机的地址和 -rc 监听端口（默认 http://localhost:5000）。MCP 与 StreamXpress 可以分处两台机器。

配置文件

MCP 支持通过项目根目录的 config.json 集中配置，在使用前填写：

1. 复制 config.example.json 为 config.json（config.json 已被 git 忽略，不会提交）。
2. 按需填写字段：

字段	说明
streamxpress_path	StreamXpress 可执行文件的完整路径（如 C:\Program Files\DekTec\StreamXpress\StreamXpress64.exe），launch 工具用它启动
sprc_api_path	SpRcApi 目录路径，默认留空（使用包内自带 wsdl）；若填写，运行时优先使用 <sprc_api_path>\WSDL\SpRc.wsdl 作为 wsdl 来源
rc_port	远程控制端口，默认 5000

查找顺序：环境变量 STREAMXPRESS_MCP_CONFIG 指定的文件 → 项目根 config.json → 默认值。配置文件缺失或字段留空时不报错，使用默认值。

若以非 editable 方式安装（pip install .），项目根定位不适用，请用环境变量 STREAMXPRESS_MCP_CONFIG 指定配置文件路径。

快速开始

MCP 客户端（WorkBuddy、Claude Desktop 等）会用配置里的 command（默认 python）启动本服务，而客户端解析到的 python 通常不是项目 venv 里的 python。因此最简单的方式是直接把包装到当前 Python 环境，不使用 venv：

# 1. 克隆并安装（装到当前 Python 环境，不使用 venv）
git clone <repo-url>
cd StreamXpress_MCP
pip install -e ".[dev]"

# 2. 以远程控制模式启动 StreamXpress
#    可执行文件不在 PATH 中；先在 config.json 里填好 streamxpress_path（见"配置文件"章节），
#    然后可用 MCP 的 launch 工具启动；也可手动用完整路径启动：
& "C:\Program Files\DekTec\StreamXpress\StreamXpress64.exe" -rc 5000

# 3. 运行 MCP 服务
python -m streamxpress_mcp

想用 venv 隔离？ 可以，但注意：MCP 客户端配置里的 command 必须指向 venv 里的 python.exe 绝对路径（如 C:\...\StreamXpress_MCP\.venv\Scripts\python.exe），不能写裸的 python——否则客户端会用系统 Python 启动进程，因找不到 streamxpress_mcp 模块而立即退出，表现为 ModuleNotFoundError 或 MCP error -32000: Connection closed。

MCP 客户端配置

在 MCP 客户端的配置文件中添加（如 WorkBuddy 的 mcp.json、Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "streamxpress": {
      "command": "python",
      "args": ["-m", "streamxpress_mcp"]
    }
  }
}

前提：command 里指定的 python 必须已安装本包（即执行过上面的 pip install -e "./[dev]"）。按上方“不使用 venv”的方式安装则保持 "python" 即可；若包装在 venv 里，则必须把 command 改为该 venv 的 python.exe 绝对路径。

可用工具

工具注册名如左（不带前缀）。MCP 客户端（WorkBuddy、Claude Desktop 等）通常会在工具名前加上 MCP server 名前缀，例如 connect 在客户端中显示为 streamxpress_connect。

这是破坏性变更：工具名已从 streamxpress_connect 等改为无前缀的 connect 等。升级后请在各 MCP 客户端（WorkBuddy、Claude Desktop 等）重新连接/重启会话以刷新工具列表，旧名不再注册。

新增的 launch 工具同样无前缀，客户端中显示为 streamxpress_launch。

工具	说明
launch	按 config.json 启动 StreamXpress（-rc 模式）并探测端口
connect	连接 StreamXpress RC 会话
disconnect	断开连接
scan_ports	扫描可用输出端口
select_port	选择输出端口
open_file	加载 TS 文件
start	开始播放
stop	停止播放
get_status	查询播放进度和状态
set_rate	设置 TS 码率（bps）
set_tsoip_params	配置 UDP/RTP TS-over-IP 输出参数
set_rf_params	设置 RF 频率和电平
set_asi_params	设置 ASI 重复用和包模式

AI 交互示例

用户: 把 C:\Streams\news.ts 以 25 Mbps 推送到组播地址 239.1.1.1:1234

AI 依次调用:
  1. launch() → 按 config.json 启动 StreamXpress，得到 port（默认 5000）
  2. connect(host="http://localhost", port=<launch 返回的 port>)
  3. scan_ports() → 选择一个 TS-over-IP 端口
  4. select_port(serial=..., port_num=1)
  5. set_tsoip_params(dest_ip="239.1.1.1", dest_port=1234, protocol="UDP")
  6. set_rate(rate_bps=25_000_000)
  7. open_file(filepath="C:\\Streams\\news.ts")
  8. start()
  9. get_status() → 监控播放进度
  10. stop()
  11. disconnect()

许可证

本项目封装了 DekTec SpRcApi。使用本软件配合 StreamXpress 进行码流推送，需要 DekTec 设备提供相应授权：DTC-300-SP/NICP（播放授权）与 DTC-302-RC（远程控制授权）。这些许可证固化在 DekTec 设备硬件中，插入设备即可使用，无需单独购买或激活许可证文件。