DualStream MCP 服务器

我们的第一个开源项目！ 官方 Model Context Protocol 服务器，服务于 DualStream——这款流媒体工作室能够从单一管线同时生成桌面（16:9）和移动端（9:16）直播流。

该服务器让 Claude 等 AI 助手能够操作你的 DualStream 工作室：切换场景、保存即时回放片段、从零搭建完整的场景布局、重新设计你的提醒和挂件，并对直播中发生的事情做出反应。一切都在你的本机上本地运行，需经你明确批准，且每次更改都会同时渲染到你的桌面和移动端画布上。

AI assistant (Claude Code, Claude Desktop, or any MCP client)
        |  MCP over stdio
        v
DualStream MCP server  (this package)
        |  JSON-RPC over WebSocket, 127.0.0.1 only
        v
DualStream desktop app

你可以提出哪些请求

连接后，你可以用自然语言与助手对话：

• “切换到我的 BRB 场景”

• “剪辑最近 30 秒”

• “创建一个名为 MAIN 的场景，把我的摄像头放在右下角，裁剪成圆形，主显示器全屏作为背景”

• “为慈善直播做一个即将开始的场景，用我的品牌色，两个画布都要”

• “按这个调色板重新设计我的提醒”

• “把摄像头稍微上移一点，并给它加一个柔和的阴影”

助手会识别你的实际硬件（摄像头、采集卡、显示器、窗口、麦克风），独立为桌面和移动端画布编排布局，并与你反复迭代，直到效果满意为止。

Related MCP server: ATEM MCP Server

开始之前

你需要安装三样东西。每一样都是普通的下载即运行安装程序：

1. DualStream 桌面应用（Windows 或 macOS）：本服务器所控制的工作室。

2. Node.js：选择绿色的大号 LTS 按钮（版本 22 或更高）。这是运行服务器的运行时；你无需直接与它交互。

3. 支持 MCP 的 AI 助手，例如 Claude Desktop 或 Claude CLI。

安装

第 1 步：将本项目下载到你的电脑上

点击本 GitHub 页面顶部的绿色 Code 按钮，选择 Download ZIP，然后将其解压到你记得住的位置，例如你的“文档”文件夹。（如果你熟悉 git，使用 git clone 也可以。）

第 2 步：构建

在解压后的文件夹中打开终端：

• Windows： 在文件资源管理器中打开该文件夹，点击地址栏，输入 cmd，然后按回车。

• macOS： 右键点击该文件夹，选择 New Terminal at Folder（或将文件夹拖到终端上）。

然后依次运行以下两条命令：

npm install
npm run build

每条命令都会打印一些文本并返回提示符。就这样；服务器已构建完成。

第 3 步：告诉你的助手

你需要第 1 步中文件夹的完整路径。在 Windows 文件资源管理器中，点击地址栏并复制（看起来像 C:\Users\you\Documents\DualStreamMCP）。在 macOS 上，右键点击文件夹，按住 Option 键，选择 Copy as Pathname。

Claude Desktop：打开 Settings → Developer → Edit Config，添加以下内容（将路径替换为你自己的；在 Windows 上，使用所示的双反斜杠）：

{
  "mcpServers": {
    "dualstream": {
      "command": "node",
      "args": ["C:\\Users\\you\\Documents\\DualStreamMCP\\dist\\index.js"]
    }
  }
}

Claude CLI：一条命令（将路径替换为你自己的）：

claude mcp add dualstream -- node "C:\Users\you\Documents\DualStreamMCP\dist\index.js"

任何其他 MCP 客户端都以相同方式工作：将 node <folder>/dist/index.js 作为 stdio 服务器运行。

第 4 步：打个招呼

重启你的助手，确保 DualStream 正在运行，然后提问：“我在 DualStream 中正在直播哪个场景？” 第一次时，DualStream 会弹出批准提示；这就是安全模型在起作用（见下文）。批准后，你就完成了。

首次连接与安全

DualStream 应用运行一个小型控制服务器，仅绑定到 127.0.0.1。网络上无法访问任何内容，且此 MCP 服务器必须与应用运行在同一台机器上。没有云组件：智能来自你所连接的 AI 助手，你的直播流始终在你的掌控之中。

配对是自动的。应用会在其配置目录中发布一个配对令牌，此服务器会自动获取它；你无需输入密码。当助手首次连接时，DualStream 会显示一个同意提示，标明客户端名称。你可以选择“允许”、“始终允许”或“拒绝”。在你批准之前，连接无法执行任何操作。你可以随时在应用的 Settings, General, External Control 下查看每个已连接的客户端、断开其中任何一个，并撤销已记住的批准。

如果你拒绝某个连接，服务器会将其关闭。如果你在应用设置中重置配对令牌，所有已连接的客户端都会被断开，必须重新配对。

工具

场景与片段

场景合成

逐个源构建和编辑场景。桌面（1920x1080）和移动端（1080x1920）画布上的布局独立控制，因此桌面上的小圆形摄像头在移动端可以是全宽方形摄像头。

配方

配方是 DualStream 的可共享场景模板：一个背景加上两个画布上已定位的源，以 JSON 形式保存在磁盘上。

挂件

AI 卡片

自动化

自动化将直播事件触发器（一次突袭、一笔大额打赏、一次 hype train 结束）与助手的常驻指令配对。当匹配的事件 发生时，DualStream 会将其连同你的指令一起中继给助手； 助手负责撰写并发布卡片。只有匹配已启用自动化的事件才会 离开应用，且助手只会在你有会话打开时监听。完整的文档格式、事件词汇表和排练流程见 contract/automations-v1.md。

一个典型的直播会话：告诉你的助手你要开播了；它会读取你的 自动化，然后在 wait_for_event 上循环；等待不消耗任何资源，每个 处理的事件就是一次简短的交互（欢迎突袭者、感谢大额打赏者、 发布卡片）。

工具错误是结构化 JSON，带有 retryable 标志，因此助手能区分“一秒钟后再试”（回放缓冲区仍在预热、连接正在等待你的批准）和“确实出了问题”。

配置

当应用和此服务器在同一用户账户下运行时，一切无需配置即可工作。以下环境变量适用于特殊场景：

Discovery 会从应用的配置目录中读取 ws-control.json（Windows 上为 %APPDATA%\app.dualstream.io\，macOS 上为 ~/Library/Application Support/app.dualstream.io/）。应用每次启动时都会写入该文件，时间在控制服务器报告就绪之前。

故障排查

工具返回 app_not_running。 DualStream 应用未打开，或尚未完成启动。请启动它；应用一上线，服务器就会自动重新连接。

工具返回 consent_pending。 连接正在等待你的操作。请在 DualStream 内的同意提示中批准它（或前往 Settings、General、External Control 下操作）。

工具返回 authentication_required 或 authentication_failed。 应用已启用认证，但此服务器无法获取令牌。请确保应用和服务器以同一用户身份运行。如果你最近重置了配对令牌，重新连接会自动处理；环境中过期的 DUALSTREAM_CONTROL_PASSWORD 也可能导致此问题。

其他异常。 先调用 get_connection_status；它可以区分"应用未运行"与认证、同意和协议问题。服务器会将单行 JSON 记录到 stderr；设置 DUALSTREAM_MCP_LOG_LEVEL=debug 可获取详细信息。

设计说明

• 本地优先设计。 控制平面仅限回环（loopback）访问。托管或远程连接器无法访问它，也不应该访问它。

• 事件驱动，无定时器。 进行中的请求仅在服务器响应或套接字关闭时结束，绝不依赖墙钟超时。重新连接由监视应用启动时重写的 discovery 文件触发；不存在轮询循环。

• stdout 是协议通道。 所有日志均以单行 JSON 形式输出到 stderr。

• 契约固定。 响应会对照内置的控制契约进行验证（参见 contract/）；使用更新协议版本的应用会以升级提示明确失败，而不是静默地行为异常。

• 同意在服务端强制执行。 审批门控位于 DualStream 应用内，而非本包中；修改过的客户端不会获得任何好处。

contract/ 目录还包含可供助手直接使用的编写参考：配方清单格式、场景合成指南（包括移动画布的布局模式）、自动化格式，以及 PROTOCOL.md：一份由契约夹具生成的完整方法、事件和错误码参考。

开发

npm run typecheck   # strict TypeScript over src and tests
npm test            # unit + full MCP round-trips against a wire-faithful mock of the app
npm run build       # emit dist/
npm run smoke       # live end-to-end against a running DualStream app
                    # (switches a scene and back, saves one 10-second clip pair)

test/ 中的模拟控制服务器实现了真实的线上协议，包括配对握手和同意流程，并使用独立实现的认证算法，因此测试套件能够真正交叉校验客户端。

关于 DualStream

DualStream 是一款面向同时在桌面和移动平台直播的创作者的流媒体工作室：一条管线、两块画布，每个场景和组件都为两者原生渲染。可在 dualstream.gg 下载 Windows 或 macOS 版本。

许可证

Apache-2.0