grandma2-toolkit

通过 MCP、CLI 和 Agent Skill 控制 grandMA2 onPC 与 MA3D。

• 双端连接：自动识别 onPC / MA3D，查询 Show、灯具和播放对象。

• 场景与编程：执行命令，调整灯具位置、安装方向和相机。

• 备份与验收：导出 XML、备份 Show、保存 MA3D 截图和操作记录。

快速开始

准备 Python 3.11+、uv，启动 onPC / MA3D 并启用 Telnet。在仓库目录运行：

uv sync --locked

$credential = Get-Credential -UserName administrator -Message 'MA2 Telnet 登录'
$env:MA2_USER = $credential.UserName
$env:MA2_PASSWORD = $credential.GetNetworkCredential().Password

uv run grandma2 connections

默认连接 127.0.0.1，探测 30000 / 30001，按运行时身份区分两端。默认只读。

Related MCP server: blender-studio-pro-mcp

使用方式

MCP

将 examples/mcp.json 中的配置加入 MCP 客户端，修改仓库路径，并为服务进程提供 MA2_PASSWORD。也可使用以下启动命令：

uv run --locked --directory G:/GitHub/grandma2-toolkit grandma2-mcp

Skill

入口：ma2-control / SKILL.md。支持项目 Skill 的客户端可直接发现，也可让 Agent 读取该文件。

使用 $ma2-control 同时连接 onPC 和 MA3D，只读检查当前 Show 与 Page 3。

使用 $ma2-control，保留 Page 3 编程，先备份，再调整指定地面灯的安装方向并截图验收。

CLI

# 查询、导出与截图
uv run grandma2 list 'Executor 3.1 Thru 3.8'
uv run grandma2 --target ma3d list 'Camera 50'
uv run grandma2 export 'Page 3'
uv run grandma2 capture --window-title 'MA 3D'

# 开启写入；将 Show 名称和对象编号替换为现场实际值
$env:MA2_ALLOW_WRITE = '1'
uv run grandma2 backup --expect-show codex
uv run grandma2 --target ma3d transform 'Camera 50' --expect-show codex --values '{"z":12.8,"rx":-2}'
uv run grandma2 execute --expect-show codex --commands-file examples/commands.readback.json

--target 放在子命令前，默认 onpc。位置单位为米、旋转为度、相机 FOV 为弧度。 更多命令见 命令参考。

配置

通过进程环境变量配置，无内置密码。

MCP 客户端不一定继承终端环境变量，请确认密码已传给服务进程。

使用须知

• 写入需匹配 Show：开启写入后仍需提供 expected_show。批次失败不会回滚，超时后应先查询状态再决定是否重试。

• 区分场景与编程：安装朝向不是 Cue 的 Pan/Tilt；MA3D 场景修改可能同步到 onPC。两端同名 Show 不代表已加入同一会话。

• 本机能力：文件导出、备份仅支持本机运行时；截图需要 Windows 上可见、未最小化的 MA3D 窗口，效果仍需查看图片确认。

• 控制网络：Telnet 明文传输，仅用于受信任网络。通用命令接口可执行 Lua、删除等操作，写入开关不是权限沙箱。

开发

uv sync --locked --group dev
uv run pytest
uv run ruff check .
uv build

AGPL-3.0