激光控制服务器

超越MCP

MCP服务器 穿山甲BEYOND 激光软件。通过OSC展示20个类别的117个工具，涵盖演出控制、线索管理、区域配置、几何校正、现场参数控制、效果、投影仪对齐、安全限制器等。

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

为什么存在

Pangolin BEYOND是行业标准的激光表演软件，但编程激光提示、调整区域和调整实时参数完全是手动的。操作员点击BEYOND UI，一次一个参数，跨越数十个区域和提示。

此MCP服务器允许AI助手通过OSC控制BEYOND。它可以触发提示、调整主亮度、静音区域、设置BPM、控制投影仪对齐、应用几何校正、管理安全限制器和控制实时参数——所有这些都可以通过一次对话完成。结合MA2 Agent、Resolume MCP和Companion MCP，AI助手可以编排整个节目控制堆栈。

快速开始

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

确保BEYOND在启用OSC输入的情况下运行（可通过以下方式配置 BEYOND_OSC_PORT，默认为12000）。

对于远程控制：

• 使用局域网或WireGuard，而不是公共互联网
• 允许UDP BEYOND_OSC_PORT
• 集 BEYOND_HOST 连接到远程计算机并将其包含在 BEYOND_ALLOWED_HOSTS

实时验证的构建说明

这个仓库已经在局域网上对一个真正的BEYOND实例进行了测试，而不仅仅是模拟的单元测试。

已验证版本上的实时确认工具：

• display_popup
• set_bpm
• select_next_page / select_prev_page
• select_next_tab / select_prev_tab
• start_cue_by_name / stop_cue_by_name
• set_master_brightness

构建特定注释：

• load_cue 发送干净，但在测试工作区中没有产生明显的可见状态变化。
• display_preview("main", ...) 发送得很干净，但 main 似乎不是已验证BEYOND设置的正确预览标识符。

完整注释： docs/live-validation.md

另请参见：

• docs/mcp-config-examples.md
• docs/operator-workflows.md

配置

建筑

graph TD
    A["Beyond MCP Server<br/><code>beyond_mcp</code><br/>117 tools · 20 categories · safety gate"] --> B
    B["OSC Client<br/>UDP fire-and-forget"] --> C
    C["Pangolin BEYOND<br/>OSC input on port 12000"]

    D["Safety Profiles<br/>lab · show-safe · read-only"] -.-> A
    E["Preview Engine<br/>Dry-run OSC inspection"] -.-> A
    F["Bundle Support<br/>Atomic multi-message delivery"] -.-> B

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

安全简介

BEYOND_SAFETY_PROFILE 给你一个理智的起点，而不必记住多个标志：

• lab
  • read_only = false
  • confirm_destructive = false
• show-safe
  • read_only = false
  • confirm_destructive = true
• read-only
  • read_only = true
  • confirm_destructive = true

如果您需要覆盖配置文件，显式环境标志仍然有效：

BEYOND_SAFETY_PROFILE=show-safe \
BEYOND_CONFIRM_DESTRUCTIVE=0 \
uv run python -m beyond_mcp

工具

系统

主控制

BPM/节拍

提示模式

点击行为

过渡

线索/细胞控制

工作区

页面/选项卡/类别导航

网格化管理

区域控制

实时控制参数（主范围）

现场控制：效果（主范围）

投影机控制

区域设置/几何校正

安全限制器

显示

DMX/通道输出

控制范围

虚拟LJ

克劳德桌面

{
  "mcpServers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

VS代码/光标

{
  "servers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

更多示例，包括针对局域网的设置： docs/mcp-config-examples.md

法典

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

{
  "mcpServers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

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

codex --mcp-config codex.json

安全生产

此服务器专为现场表演环境而设计，在这种环境中，意外命令可能会中断正在进行的激光表演。所有117个工具都包括完整的参数验证。

• UDP即发即弃 --BEYOND OSC控件使用UDP，这意味着命令在没有确认的情况下发送。没有回滚。每次工具调用都是对激光系统的实际操作。
• 主机分配 --只有 127.0.0.1, localhost，以及 ::1 默认情况下是允许的。通过以下方式显式添加LAN主机 BEYOND_ALLOWED_HOSTS.Set * 允许任何主机。
• 只读模式 --set BEYOND_READ_ONLY=1 以阻止所有写入操作。仅 get_server_config, health_check, preview_osc，以及 preview_osc_bundle 保持可用。
• 确认破坏性浇口 --set BEYOND_CONFIRM_DESTRUCTIVE=1 要求 confirm=true 破坏性操作，包括原始/捆绑发送破坏性OSC地址和破坏性命名工具，如 load_workspace, stop_zone，以及 stop_projector_by_name.
• 健康检查 -- health_check 通过DNS解析和UDP套接字测试验证BEYOND目标可达性，并报告解析的地址族/套接字目标。
• OSC捆绑包支持 -- send_osc_bundle 将多个OSC消息作为原子包发送，确保协调的多参数更改的全部或全部交付。
• 发送前预览 -- preview_osc 和 preview_osc_bundle 在不传输任何内容的情况下返回确切的数据包详细信息。在高风险现场操作之前使用它们。
• 输入验证 --所有117个具有记录参数范围的工具在构建任何OSC消息之前都会强制执行边界。亮度、缩放、扫描速率、大小、位置、旋转、颜色、BPM、速度、淡入淡出时间、效果槽、限制器类型、几何校正参数和非负索引都经过范围检查。无效输入返回结构化JSON错误，从不返回原始异常。
• 错误隔离 --所有工具都包裹在 _handle_errors.OSC发送失败、JSON解析错误、验证失败和意外异常返回 {"ok": false, "error": "...", "blocked": true} 而不是使MCP会话崩溃。
• 运输验证 --只有 stdio, sse，以及 streamable-http 运输被接受。无效的传输值在启动时立即升高。
• 端口验证 -- BEYOND_OSC_PORT 在配置加载时被验证为1-65535范围内的整数。
• 原始逃生舱口 -- send_osc_raw 允许任何OSC地址覆盖指定工具之外的范围，但需要显式的JSON数组输入，并在发送前验证结构。

建议的操作流程

首次在新的BEYOND机器上使用：

1. get_server_config
2. health_check
3. display_popup
4. set_bpm
5. 页面/标签导航
6. 非关键线索开始/停止
7. 主亮度等实时参数测试

更实用的序列： docs/operator-workflows.md

发展

uv sync
uv run python -m pytest -v

许可证

Apache 2.0