Companion MCP服务器

配套MCP

MCP服务器 Bitfocus伴侣.公开了53个工具，涵盖了经过验证的按钮控制、样式、页面发现、运行时摘要、库存差异、检查点回滚/恢复工作流、预设管理、变量管理和批处理显示编程，因此AI助手可以通过Companion的当前API操作Stream Deck表面和其他Companion连接的设备。

为现场制作而建。与配对 grandMA2 MCP, Resolume MCP, MADRIX MCP，以及 超越MCP 完全由人工智能驱动的节目控制。

该仓库还包括一个轻量级的本地浏览器UI，供那些希望在不手动发出MCP工具调用的情况下获得相同验证流的人使用。

为什么存在

Companion是将实时生产堆栈连接在一起的物理按钮层。操作员按下Stream Deck按钮，它会发出grandMA2提示，触发Resolume片段，或启动激光序列。但是对这些按钮进行编程是手动的——你一次点击一个按钮，配置操作、标签和颜色。

这个MCP服务器允许AI完成这项工作。它可以读取您当前的按钮布局，在应用更改之前预览更改，并在几秒钟内对整个页面进行批处理。结合MA2 Agent和Resolume MCP，AI助手可以从一次对话中对整个节目控制界面进行编程。

快速开始

git clone https://github.com/drohi-r/companion-mcp && cd companion-mcp
uv sync
uv run python -m companion_mcp

浏览器用户界面

运行本地操作员UI：

uv run companion-mcp-ui

然后打开：

http://127.0.0.1:8088

UI首先是本地的。它与MCP工具位于相同的后端逻辑之上，因此经过验证的写入、快照、预设和回滚在浏览器中的行为与通过MCP的行为相同。

确保Companion正在目标主机和端口上运行。当前Companion版本使用：

• 用于按钮操作和样式写入的HTTP端点
• websocket-tRPC位于 /trpc 用于更丰富的读取、发现、预览和变量检查

配置

建筑

graph TD
    A["Companion MCP Server<br/><code>companion_mcp</code><br/>53 tools · safety gate"] --> B
    B["HTTP Client<br/>Button actions · style writes"] --> D
    A --> C
    C["WebSocket tRPC Client<br/>Discovery · preview · variables"] --> D
    D["Bitfocus Companion<br/>HTTP + WebSocket at /trpc"]

    E["Browser UI<br/><code>companion-mcp-ui</code><br/>Local operator console"] -.-> A
    F["Snapshot Engine<br/>Inventory · presets · rollback"] -.-> A
    G["Verification Layer<br/>Render polling · diff · transactions"] -.-> A

    style A fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style B fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style C fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style D fill:#1a1a2e,stroke:#0f3460,color:#fff
    style E fill:#0f3460,stroke:#0f3460,color:#fff
    style F fill:#0f3460,stroke:#0f3460,color:#fff
    style G fill:#0f3460,stroke:#0f3460,color:#fff

工具

发现和阅读

用于了解Companion当前状态的安全只读工具。

预览（写作前计划）

无需触摸Companion即可验证和预览操作。使用这些来检查批处理操作在提交之前会做什么。

按钮操作

要求 COMPANION_WRITE_ENABLED=1 （默认）。

按钮样式

批量操作

变量和系统

克劳德桌面版

{
  "mcpServers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

VS代码/光标

{
  "servers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

法典

创建一个 codex.json MCP配置文件：

{
  "mcpServers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

然后使用以下命令运行Codex：

codex --mcp-config codex.json

安全生产

此服务器专为现场表演环境而设计，意外写入可能会中断正在运行的生产。

• 主机分配 --只有 127.0.0.1, localhost，以及 ::1 默认情况下是允许的。通过以下方式显式添加LAN主机 COMPANION_ALLOWED_HOSTS.
• 写控制 --set COMPANION_WRITE_ENABLED=0 以阻止所有写入操作。读取和预览工具仍然可用。
• 应用前预览 --每个批处理操作都有一个相应的预览工具，可以验证输入并准确显示将要更改的内容，而无需触摸Companion。
• 已验证写入 --更喜欢 press_button_verified 和 set_button_style_verified 当你关心实际的可见或运行时状态变化时，而不仅仅是HTTP接受度。
• 快照和差异工作流 --使用 snapshot_page_inventory 批量更改前后，或让 set_page_style_verified 自动生成库存差异。
• 回滚路径 --使用以下命令捕获页面 snapshot_page_inventory 或 save_page_inventory_snapshot，检查恢复计划 preview_restore_page_style_from_inventory 或 preview_restore_page_style_from_snapshot，然后使用匹配还原工具将样式干净地回滚。
• 交易流程 — apply_page_style_transaction 在写入之前创建一个命名的回滚检查点。 rollback_page_style_transaction 从该命名快照恢复。
• 预设工作流程 --使用保存可重用的页面样式 save_page_style_preset，检查 preview_apply_page_style_preset，并使用进行部署 apply_page_style_preset.
• 输入验证 -页面、行、列、颜色十六进制、延迟边界和模板结构都在进行任何API调用之前进行验证。无效输入返回结构化JSON错误，从不返回原始异常。
• 错误隔离 --所有工具都包裹在 _handle_errors。返回网络故障、JSON解析错误和验证失败 {"ok": false, "error": "...", "blocked": true} 而不是使MCP会话崩溃。

现场行为记录

• 成功的HTTP写入并不总是意味着按钮会立即发生明显的变化。
• 当前的Companion版本可以先更新存储的样式状态，然后在短时间内重新绘制预览。
• set_button_style_verified 和 press_button_verified 包括有界轮询，以便MCP可以区分：
  • 已接受写入，但未观察到任何变化
  • 写入已接受，预览在短暂延迟后更改
  • 写入已接受，样式状态已更改，但可见渲染仍未更改

为什么UI有帮助

MCP后端已经是真正的产品了。UI不会取代它；它使人类更快、更安全：

• 点击页面网格中的按钮，而不是记住 page,row,column
• 在一个地方检查预览、样式、运行时摘要和上次验证的响应
• 保存和浏览快照和预设，而无需打开JSON文件
• 在节目准备期间从浏览器运行经过验证的样式更改和事务回滚
• 将系统交给不会手动键入MCP呼叫的操作员

发展

uv sync
uv run python -m pytest -v

许可证

Apache 2.0