MA3 MCP Server

MA3-MCP

⚠️ 原型/概念验证\ 该项目是一个实验性实施，演示了通过MCP进行人工智能辅助照明控制。 它不打算用于生产用途。使用风险自负。

MCP服务器，用于通过AI助手（Claude Desktop、VS Code Copilot等）控制grandMA3照明控制台。

特性

• 直接执行MA3控制台命令
• 控制装置（调光器、颜色、位置、遮光板等）
• 使用时间和触发器存储和管理线索
• 播放控制（Go、Back、Off等）
• 执行器推子和按钮控制
• 查询序列、提示和程序员内容
• 读取DMX输出
• 批处理操作的组支持

项目结构

ma3_mcp/
├── config.py      # Configuration management
├── ma3_comm.py    # File-based IPC with grandMA3
├── server.py      # MCP tools (@mcp.tool() definitions)
└── __init__.py

plugin/
├── mcp_server.lua    # grandMA3 Lua plugin
└── MCP Server.xml    # Plugin configuration

快速开始

1.安装Python依赖项

poetry install

2.将Lua插件部署到MA3

复制 .env.example 到 .env 并配置您的路径：

cp .env.example .env
# Edit .env with your MA3 installation path

然后部署：

./deploy.sh

或手动复制 plugin/mcp_server.lua 到MA3插件文件夹：

• macOS: ~/MALightingTechnology/gma3_X.X.X/shared/resource/lib_plugins/mcp_server/
• 视窗: %USERPROFILE%\MALightingTechnology\gma3_X.X.X\shared\resource\lib_plugins\mcp_server\

3.在MA3中启动插件

1. 在MA3中，转到 Menu → 插件
2. 创建或选择“MCP服务器”插件
3. 启动插件（它将在后台轮询命令）

4.配置您的AI助手

对于VS代码（GitHub Copilot）：

工作区设置已配置。只需在VS Code中打开项目。

对于Claude Desktop：

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "grandMA3": {
      "command": "poetry",
      "args": ["run", "python", "-m", "ma3_mcp.server"],
      "cwd": "/path/to/MA3-MCP"
    }
  }
}

配置

所有配置都是通过环境变量完成的。复制 .env.example 到 .env:

# IPC paths (defaults work for most setups)
MA3_IPC_DIR=/Users/Shared/MA3

# Plugin deployment path
MA3_PLUGIN_DIR=~/MALightingTechnology/gma3_2.3.2/shared/resource/lib_plugins/mcp_server

# OSC reload settings
MA3_OSC_HOST=127.0.0.1
MA3_OSC_PORT=8000

平台默认值

通信架构

使用基于文件的IPC进行可靠的跨进程通信：

MCP Client (Python)                    grandMA3 (Lua Plugin)
       │                                       │
       ├── Write command ──────────────────────┤
       │   mcp_command.txt                     │
       │                                       ├── Poll & Execute
       │                                       │
       ├── Read response ◄─────────────────────┤
           mcp_response.txt                    │

可用工具

夹具控制

• ma3_list_fixtures -列出所有已修补的灯具
• ma3_select -按ID、范围或组选择设备
• ma3_set_attribute -在选择时设置属性
• ma3_set_color -在选择时设置RGB颜色
• ma3_set_position -在选择时设置平移/倾斜

线索管理

• ma3_store_cue -存储带有时间和名称的提示
• ma3_store_cue_part -储存球杆部件以适应复杂的计时
• ma3_set_cue_timing -修改现有的提示时间
• ma3_set_cue_trigger -设置提示触发模式（前进/时间/跟随）
• ma3_delete_cue -删除提示
• ma3_goto_cue -跳转到特定提示

回放控制

• ma3_playback -控制顺序（前进、后退、关闭、顶部）
• ma3_executor_fader -设置执行器推子级别
• ma3_executor_go -触发执行器操作
• ma3_assign_to_executor -为执行者分配序列（可选名称）
• ma3_label_executor -设置或更改执行者标签/名称

检测工具

• ma3_get_sequence_overview -按顺序列出所有线索
• ma3_get_cue_contents -获取线索细节和时间
• ma3_get_fixture_status -获取夹具编程器/输出值
• ma3_list_programmer_detailed -程序员详细内容

查询功能

• ma3_query -查询任何MA3对象
• ma3_get_property -获取对象属性
• ma3_get_all_properties -以JSON格式获取所有属性
• ma3_list_children -列出对象子项

发展

部署更改

使用部署脚本复制Lua插件并重新加载：

./deploy.sh

这将：

1. 复制 plugin/mcp_server.lua MA3
2. 发送OSC命令以重新加载插件

VS代码集成

该项目包括以下VS代码设置：

• MCP服务器配置
• MA3命令行和系统监视器的终端配置文件
• 自动批准部署脚本

插件重新加载设置

对于热重新加载插件的部署脚本，您需要在MA3中正确配置插件。 有关详细说明，请参阅此论坛帖子：

• grandMA3 VSCode工作流

许可证

该项目已获得许可 CC BY-NC-SA 4.0 （知识共享署名-非商业性相同方式共享4.0国际）。

您不得将此软件用于商业目的。