gma2 MCP

GMA2 MCP

MCP服务器，让AI助手通过Telnet控制grandMA2照明控制台。它通过模型上下文协议提供了41个高级工具，用于线索管理、夹具控制、预设管理、执行器控制、宏编辑、外观分配、批量操作、控制台状态查询、节目文件管理、读回验证、音乐节目工作流等。

目录

• 概述
• 特性
• 入门指南

- 先决条件 - 安装 - 配置 - MCP注册

• 用法

- MCP工具 - 指令产生器 - 直接电话网络接入

• 命令参考

- 帮助关键字 - 对象关键字 - 功能关键字 - 在关键字 - 复制和移动 - 分配 - 标签 - 外观 - 宏占位符

• 项目结构
• 发展
• 故障排除
• 许可证
• 贡献

概述

grandMA2控制台通过Telnet接受命令，但构建正确的命令字符串需要了解MA2语法规则——关键字排序、预设类型映射、选项标志和对象层次结构。该项目分两层处理这种复杂性：

1. 指令产生器 (src/commands/)--按照官方语法规则构造有效grandMA2命令字符串的Python函数。每个函数都是一个返回字符串的瘦包装器；它从不接触网络。
2. MCP服务器 (src/server.py)--一个FastMCP服务器，它公开了41个工具，涵盖了线索管理、夹具控制、预设、执行器、全局状态、标签、外观分配、宏编辑、批量线索操作、序列播放、控制台状态查询、节目文件管理、回读验证、音乐节目工作流和stdio传输上的原始命令。它管理到控制台的持久Telnet连接，并将命令构造委托给构建器层。
3. 响应解析器 (src/response_parser.py)--用于解析grandMA2 Telnet输出的纯函数（来自 List 命令）转换为结构化数据。读回工具使用它来返回解析后的字典，而不是原始文本。
4. GMA2客户端 (src/gma2_client.py)--一个高级编排类，它将多个命令生成器调用组合到工作流级方法中（例如，构建一个完整的提示列表，设置一个预设的夹具组，为音乐节目创建歌曲对象）。
5. 命令序列 (src/command_sequence.py)--一个构建器模式类，用于将多个命令组合成一个有序的批处理，该批处理可以作为一个单元进行预览和执行。

命令生成器涵盖了按类别组织的所有grandMA2命令行关键字：对象关键字（夹具、通道、组、预设、提示、序列、执行器）、功能关键字（存储、删除、复制、移动、跳转、标签、分配等）和帮助关键字（through、at、+）。

特性

• 41个MCP工具 --线索管理（存储/删除/转到、CMD分配）、夹具控制（设置值、设置属性、清除编程器）、预设管理（存储或应用）、执行器控制（开/关/去/杀死/切换、推子级别、序列分配）、全局状态（黑屏、高亮显示）、对象标签（通用+序列范围的线索标签）、外观分配（RGB、HSB、十六进制、源副本）、宏行编辑、跨序列范围的批量线索操作（存储、标签、外观）、序列回放、控制台状态查询（列表组/线索/预设/变量、读取对象注释、通用对象查询）、显示文件管理（保存/加载/新建/列表显示）、读回验证（读取宏行、提示信息、具有结构化解析的对象标签）、音乐表演工作流（创建歌曲对象、设置歌曲宏、构建集列表）和原始命令执行。
• 破坏性指挥安全警告 --删除工具包括有关下游效应（孤立的执行器句柄、丢失的线索编程）的信息警告，以帮助人工智能助手在确认之前了解影响。
• 完整的命令生成器 --200多个Python函数，涵盖了30多个模块中的所有grandMA2命令行关键字，每个函数都返回一个格式正确的命令字符串。
• 高级客户 -- GMA2Client 提供工作流级别的方法：构建提示列表、使用预设设置夹具组、快速查看编程、批处理执行器分配。使用grandMA2的内联命名语法来最大限度地减少Telnet往返。
• 命令链 -- CommandSequence 允许您组合多个命令，预览它们，并批量执行它们。
• 弹性Telnet客户端 --基于 telnetlib3 具有自动登录、持久连接、连接健康检查、带有界指数回退的自动重新连接、通过以下方式进行命令序列化 asyncio.Lock，以及优雅的关机。如果控制台重新启动或网络中断，客户端会检测到故障，并在下一个命令之前透明地重新连接。
• 连接错误浮出水面 --MCP工具捕获连接失败并返回人类可读的错误消息，而不是未处理的异常，因此AI助手知道命令何时未到达控制台。
• 可配置运输 --支持 stdio （默认，单客户端）和 streamable-http （多客户端、基于网络的访问）传输。HTTP主机和端口可以通过环境变量进行配置。
• 可通过环境配置 --通过设置主机、端口、用户、密码和传输设置 .env 或环境变量。

入门指南

先决条件

• Python>=3.12
• 启用Telnet访问的grandMA2控制台（或onPC）
• 紫外线 （推荐）或pip

在macOS上，如果您需要Telnet客户端进行手动测试：

brew install telnet

安装

git clone 
cd gma2-mcp

使用紫外线：

uv sync

使用pip：

python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

复制模板并填写您的控制台详细信息：

cp .env.template .env

GMA_HOST 应设置为运行grandMA2 onPC的计算机的IP地址。您可以在onPC网络设置或检查机器的网络配置中找到此信息。

端口30000是标准命令端口。端口30001是只读的（日志输出）。

要启用基于web或多客户端访问的HTTP传输：

MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0    # bind to all interfaces (default: 127.0.0.1)
MCP_PORT=3000        # custom port (default: 8000)

当使用 streamable-http，来自多个客户端的并发命令通过内部锁自动序列化，以防止交错的Telnet命令，因为grandMA2控制台按顺序处理命令。

MCP注册

将服务器添加到MCP客户端配置中。

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "gma2": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gma2-mcp",
        "run",
        "python",
        "-m",
        "src.server"
      ],
      "env": {
        "GMA_HOST": "2.0.0.1",
        "GMA_USER": "administrator",
        "GMA_PASSWORD": "admin"
      }
    }
  }
}

无紫外线 --直接指向virtualenv Python：

{
  "mcpServers": {
    "gma2": {
      "command": "/path/to/gma2-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/gma2-mcp",
      "env": {
        "GMA_HOST": "2.0.0.1",
        "GMA_USER": "administrator",
        "GMA_PASSWORD": "admin"
      }
    }
  }
}

克劳德代码（CLI/IDE扩展）

Claude Code通过自己的配置管理MCP服务器，与Claude Desktop分开。您可以使用CLI命令或直接编辑设置文件进行设置。

选项1：使用 claude mcp add 命令（推荐）

在终端中运行以下命令：

claude mcp add gma2 \
  -e GMA_HOST=2.0.0.1 \
  -e GMA_USER=administrator \
  -e GMA_PASSWORD=admin \
  -- uv --directory /path/to/gma2-mcp run python -m src.server

这将使用Claude Code注册MCP服务器。这 -e 标志设置服务器在启动时读取的环境变量。替换 /path/to/gma2-mcp 使用克隆存储库的实际路径，并调整 GMA_HOST, GMA_USER，以及 GMA_PASSWORD 值以匹配您的主机。

要仅为特定项目注册服务器（而不是全局注册），请添加 -s project 标志：

claude mcp add gma2 -s project \
  -e GMA_HOST=2.0.0.1 \
  -e GMA_USER=administrator \
  -e GMA_PASSWORD=admin \
  -- uv --directory /path/to/gma2-mcp run python -m src.server

选项2：手动编辑设置文件

将服务器条目添加到Claude Code设置文件中。文件位置取决于范围：

• 用户级别 （适用于所有项目）： ~/.claude/settings.json
• 项目级别 （仅在当前项目中可用）： .claude/settings.json 在项目根中

{
  "mcpServers": {
    "gma2": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gma2-mcp",
        "run",
        "python",
        "-m",
        "src.server"
      ],
      "env": {
        "GMA_HOST": "2.0.0.1",
        "GMA_USER": "administrator",
        "GMA_PASSWORD": "admin"
      }
    }
  }
}

验证设置

注册服务器后，验证其是否正常工作：

# List all registered MCP servers
claude mcp list

# Check the server details
claude mcp get gma2

当您启动新的Claude Code会话时，服务器会自动启动。您可以通过要求Claude列出其MCP工具或直接请求grandMA2操作（例如，“在控制台上切换停电”）来确认工具可用。

管理服务器

# Remove the server
claude mcp remove gma2

# Re-add with different settings
claude mcp add gma2 \
  -e GMA_HOST=192.168.1.100 \
  -- uv --directory /path/to/gma2-mcp run python -m src.server

用法

MCP工具

服务器公开了41个工具：

查询/反思工具

查询工具使用 send_command_with_response() 捕获grandMA2 Telnet输出并返回原始文本。grandMA2手册没有记录以下设备的确切Telnet有线格式 List 和 Info 响应，因此这些工具返回未处理的控制台输出，人工智能可以直接解释。

• list_groups, list_cues, list_presets --使用grandMA2 List 关键字检索显示数据。接受可选的ID范围（例如。， list_groups(group_id=1, end_group_id=10)). list_presets 在发送之前，根据9种已知类型验证预设类型。
• get_cue_annotation, get_group_annotation --使用grandMA2 Info 关键字，读取用户在对象上添加的描述性文本注释（通过设置 Info Group 3 "some note" 在控制台上）。这些不会返回对象属性，如淡入淡出时间或夹具组合——使用 list_cues 或 list_groups 为了这个。
• list_variables --路线至 ListVar （显示变量）或 ListUserVar （用户变量）基于 variable_type 参数。支持可选的过滤模式。
• query_object --专用工具未涵盖的任何grandMA2对象类型的通用查询。支持 mode="list" （默认）和 mode="annotation".

当控制台不返回数据时，所有查询工具都会返回描述性消息，而不是空字符串。

显示文件管理工具

• save_show_tool --保存当前节目文件。接受可选 show_name 以另存为特定名称。用途 /noconfirm 以抑制将阻止Telnet的覆盖确认弹出窗口。
• load_show_tool --按名称加载显示文件。这是一个破坏性的操作：对当前节目的未保存更改将丢失。接受 save_first=True 加载前保存当前节目。用途 /noconfirm 以抑制GUI弹出。
• new_show_tool --创建新的空节目。同样的破坏行为和 save_first 选项为 load_show_tool.
• list_shows_tool --列出控制台所选驱动器上的可用显示文件。接受可选的过滤器模式。

读回工具

回读工具使用 send_command_with_response() 捕获grandMA2 List 命令输出并将其解析为结构化字典 src/response_parser.py每个工具返回一个包含解析字段和 raw_response 调试字段。如果无法识别响应格式，工具将返回 parsed: False 原始输出。

• read_macro_lines --发送 List Macro {pool}.{id} 并解析每行的编号和CMD内容。退货 {"macro_id": N, "parsed": True, "lines": [{"line_number": 1, "cmd": "..."}], "raw_response": "..."}.
• read_cue_info --发送 List Cue {id} Sequence {seq} 并提取标签、CMD和淡入淡出时间。退货 {"sequence_id": N, "cue_id": N, "label": "...", "cmd": "...", "fade": "...", "raw_response": "..."}.
• read_object_label --发送 List {type} {id} 并提取对象的名称/标签。适用于任何池对象类型（序列、页面、组等）。对于宏 object_id 必须具有池资格（例如。， "1.5" 对于池1中的宏5）。

音乐表演工作流程工具

高级工具，自动化音乐节目编程的常见多步模式。这些代表 GMA2Client 工作流方法。

• create_song_objects --创建并标记具有相同ID和名称的序列+页面对。这是每首歌曲节目的标准模式（例如。， create_song_objects(song_id=101, song_name="Opening+Childhood") 发送2个命令）。
• setup_song_macro --创建带有标签的宏 SetVar 第1行上的命令，用于跟踪当前歌曲。接受可选 var_name （默认值： $song).发送3个命令：存储宏、标签、分配CMD。
• build_set_list --创建带有链接到歌曲宏的提示的集合列表序列。对于每首歌曲，存储一个以歌曲名称为标签的提示，并分配 Macro {id} 作为提示CMD。接受以下列表 {cue_id, macro_id, name} 字典。

delete_show 故意不将其作为MCP工具公开——它是不可逆的，对于人工智能发起的操作来说太危险了。这 Backup 命令也被排除在外，因为它在控制台上打开了一个GUI菜单（根据grandMA2手册第368页），该菜单在Telnet上无法运行。使用 save_show_tool 使用特定名称作为实际的备份机制。

指令产生器

这 src/commands/ 模块可以独立用于构建命令字符串：

from src.commands import fixture, at_full, store_group, label_group

fixture(1, end=10)              # "fixture 1 thru 10"
at_full()                       # "at full"
store_group(5)                  # "store group 5"
store_group(5, name="Front Wash")  # 'store group 5 "Front Wash"' (inline naming)
label_group(5, "Front Wash")    # 'label group 5 "Front Wash"' (separate label command)

GMA2Client（工作流编排）

这 GMA2Client 类提供了组合多个命令的高级工作流方法。这些方法使用grandMA2的内联命名语法来最小化Telnet往返次数：

from src.gma2_client import GMA2Client

async with GMA2Client.create("192.168.1.100") as client:
    # Build a cue list with names and fade times
    # Uses inline naming: 1 command per named cue (store cue N "Name"),
    # plus 1 command per fade time
    await client.build_cue_list(1, [
        {"id": 1, "name": "Preset", "fade": 0},
        {"id": 2, "name": "Look 1", "fade": 3.0},
        {"id": 3, "name": "Blackout", "fade": 2.0},
    ])

    # Select fixtures, store as named group, apply a preset (3 commands)
    # Uses inline naming: store group N "Name" in a single command
    await client.setup_group_with_preset(
        fixtures=(1, 10), group_id=1,
        group_name="Front Wash", preset_type="color", preset_id=3,
    )

    # Quick look: set fixtures to a value, optionally store as cue
    await client.quick_look(fixtures=(1, 20), value=75, store_as_cue=5)

    # Batch assign sequences to executors
    await client.assign_sequences_to_executors([(1, 1), (2, 2), (3, 3)])

    # Clone fixture programming (with /noconfirm for telnet)
    await client.clone_fixtures(source_fixture=1, target_fixture=11,
                                source_end=5, target_end=15, mode="overwrite")

    # Apply effect to a group with parameters
    await client.setup_effect_on_group(group_id=1, effect_id=5,
                                       bpm=120, form="sin", high=100, low=0)

    # Set up a full executor page
    await client.setup_executor_page(page=1, assignments=[
        {"executor_id": 1, "sequence_id": 1, "label": "Wash", "fader_level": 80},
        {"executor_id": 2, "sequence_id": 2, "label": "Spots"},
    ])

    # Label multiple objects at once
    await client.batch_label("group", {1: "Wash", 2: "Spots", 3: "Beams"})

    # Create and optionally run a macro
    await client.create_and_run_macro(
        macro_id=10, commands=["Go Sequence 1", "Go Sequence 2"],
        name="Start Show", run=True,
    )

    # Music show workflows: create song objects (sequence + page pair)
    await client.create_song_objects(song_id=101, song_name="Opening+Childhood")

    # Set up a song macro with SetVar on line 1
    await client.setup_song_macro(macro_id=101, song_name="Opening+Childhood")

    # Build a full set list with cue-to-macro links
    await client.build_set_list(
        sequence_id=100, sequence_name="Set List",
        songs=[
            {"cue_id": 1, "macro_id": 101, "name": "Opening+Childhood"},
            {"cue_id": 2, "macro_id": 102, "name": "Nostalgia"},
            {"cue_id": 3, "macro_id": 103, "name": "Finale"},
        ],
    )

命令序列（命令链）

这 CommandSequence 类允许您组合多个命令并将其作为批处理执行：

from src.command_sequence import CommandSequence
from src.commands import fixture_at, store_group, at_full

seq = CommandSequence()
seq.add(fixture_at(1, 50)).add(at_full()).add(store_group(1))

# Preview before sending
print(seq.preview())  # ['fixture 1 at 50', 'at full', 'store group 1']

# Execute all commands
result = await seq.execute(client)
# {'commands_sent': [...], 'count': 3, 'success': True}

直接电话网络接入

对于通过Makefile进行的手动测试：

make server    # Connect to grandMA2 command port (30000)
make log       # Connect to log output port (30001)

要退出Telnet会话：按 Ctrl + ]，然后键入 quit.

手动运行MCP服务器

uv run python -m src.server

命令参考

命令生成器遵循官方的grandMA2命令行语法。基本模式是 [Function] [Object]。所有对象都有默认函数，大多数函数都有默认对象类型。对象排列在层次树中。

1.助词（介词/连词）

用于创建函数和对象之间的关系。

2.对象关键字（名词）

在显示文件中分配对象。通常与数字、ID、名称或标签结合使用。

3.功能关键字（动词）

执行一项任务或功能，后面通常是它们所应用的对象。

4.在关键字（特殊）

At 同时作为功能关键字和帮助关键字。

5.复制和移动关键字

复制会创建重复项。Move会重新定位对象（如果目标被占用，则进行交换）。

复制选项： overwrite, merge, status, cueonly, noconfirm

6.指定关键字

定义对象、修补和特性指定之间的关系。

分配选项： break_, multipatch, reset, x, y, noconfirm, special, cue_mode, password

7.标签关键字

为对象命名。名称中的数字会自动枚举范围。

8.外观关键字

更改池对象的框架颜色和线索的背景颜色。

9.宏占位符（@Character）

这 @ 性格（不同于 At 关键字）用作宏中用户输入的占位符。

项目结构

gma2-mcp/
├── src/
│   ├── commands/               # Command builder module
│   │   ├── __init__.py         # Public API exports
│   │   ├── constants.py        # PRESET_TYPES, store option sets
│   │   ├── helpers.py          # Internal helper functions
│   │   └── functions/          # Function keywords by category
│   │       ├── advanced_edit.py    # Flip, CircularCopy, Import, Export
│   │       ├── assignment.py       # Assign keyword functions
│   │       ├── blackout.py         # Blackout, Freeze, Highlight, Solo
│   │       ├── blind.py            # Blind, Preview modes
│   │       ├── call.py             # Call keyword
│   │       ├── conditionals.py     # EndIf, IfActive, IfOutput, Or, With
│   │       ├── crossfade.py        # Crossfade, ManualXFade
│   │       ├── cue_timing.py       # Delay, Fade timing
│   │       ├── edit.py             # Copy, Move, Delete, Remove
│   │       ├── effect.py           # Effect, EffectBPM, EffectForm
│   │       ├── executor_control.py # Off, On, Kill, Flash, Swop
│   │       ├── fixture_control.py  # Align, Fix, Locate, Next, Prev
│   │       ├── flash_swop_ext.py   # FlashGo, SwopGo, StoreLook
│   │       ├── helping.py          # Helping keywords (Thru, +)
│   │       ├── info.py             # List and Info queries
│   │       ├── intensity.py        # Full, Zero, Load, Learn
│   │       ├── labeling.py         # Label and Appearance
│   │       ├── list_ext.py         # ListShows, ListOops, ListVar
│   │       ├── macro.py            # Macro placeholder functions
│   │       ├── matricks.py         # MAtricks keywords
│   │       ├── midi.py             # MIDI control functions
│   │       ├── navigation.py       # Down, Up, NextRow, Search
│   │       ├── network.py          # Remote, Telnet, JoinSession
│   │       ├── park.py             # Park/Unpark functions
│   │       ├── playback.py         # Go, GoBack, Goto, DefGo
│   │       ├── programmer.py       # Block, Clone, Default, Update
│   │       ├── rate_speed.py       # Rate, Speed control
│   │       ├── rdm.py              # RDM functions
│   │       ├── selection.py        # SelFix and Clear functions
│   │       ├── show_data.py        # CrashLog, Lua, PSR, Thru
│   │       ├── step_timing.py      # SnapPercent, StepFade, FadePath
│   │       ├── store.py            # Store functions
│   │       ├── system.py           # Backup, Setup, Shutdown, Login
│   │       ├── values.py           # At and value setting
│   │       └── variables.py        # Variable functions
│   ├── command_sequence.py     # CommandSequence for multi-command batching
│   ├── gma2_client.py          # High-level workflow orchestration client (15 methods)
│   ├── response_parser.py      # Parse grandMA2 Telnet output into structured data
│   ├── server.py               # MCP server (FastMCP, 41 tools, configurable stdio/streamable-http transport)
│   └── telnet_client.py        # Async Telnet client with health check, auto-reconnect, command lock, state tracking
├── tests/                      # Pytest test suite (one file per module)
├── doc/                        # grandMA2 user manual (PDF)
├── connect.sh                  # Telnet connection script with auto-login
├── Makefile                    # Utility commands (server, log, test)
├── pyproject.toml              # Project metadata and dependencies
└── .env.template               # Environment variable template

发展

运行测试

make test

或者直接：

uv run pytest -v

运行特定的测试文件：

uv run pytest tests/test_playback.py -v

依赖项

建筑

该项目有五层：

1. Telnet 客户端 (src/telnet_client.py)--与控制台的低级异步Telnet通信。包含 ConnectionState 跟踪（断开/连接/连接/重新连接）、健康检查探测、具有有界指数回退的自动重新连接（可配置的重试和延迟）、在快速命令序列中跳过冗余探测的健康检查TTL， asyncio.Lock-基于命令序列化实现并发访问安全，并通过服务器生命周期挂钩实现优雅关闭。
2. 指令产生器 (src/commands/)--构造命令字符串的纯函数。无法访问网络。
3. 响应解析器 (src/response_parser.py)--解析grandMA2 Telnet的纯函数 List 命令输出为结构化字典。退货 parsed: False 无法识别的格式。
4. 编排 (src/gma2_client.py, src/command_sequence.py)--高级工作流方法（包括音乐表演工作流在内的15种方法）和命令批处理，组成构建器+telnet。
5. MCP服务器 (src/server.py)--通过可配置传输公开41个工具的FastMCP服务器(stdio 或 streamable-http)，将构建器连接到Telnet客户端。

所有控制台通信都通过Telnet客户端层。

故障排除

连接失败 --验证控制台IP和端口。确保控制台上启用了Telnet。手动测试 make server.

会话中途连接中断 --Telnet客户端最多可重试3次自动重新连接（指数回退：1s、2s、4s）。如果所有重试都失败，工具将返回一条明确的错误消息。检查控制台是否正在运行且可访问。

身份验证错误 --在中检查用户名/密码 .env。确认控制台上存在用户帐户。登录区分大小写。

夹具设置被过时的连接锁定 --如果前一个会话在没有调用的情况下崩溃 disconnect()，控制台可能仍持有Telnet锁。重新启动控制台或等待其会话超时。MCP服务器现在调用 disconnect() 关闭以防止这种情况。

命令不起作用 --根据grandMA2手册验证语法。确保当前显示文件中存在引用的对象（装置、组、预设）。

许可证

此项目根据Apache许可证2.0获得许可。看 许可证 了解详情。

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/name)
3. 提交您的更改
4. 推送到分支并打开Pull Request

提交前运行测试： make test