______________________________________________________________________

标题：grandMA2 MCP description:grandMA2照明控制台的MCP服务器——通过Telnet提供218个MCP工具版本：1.1.0 创建时间：2026-04-02T00:00:00Z 最后更新时间：2026-04-04T00:00:00Z

grandMA2 MCP

MCP服务器 grandMA2 照明控制台。 将218个grandMA2操作暴露为模型上下文协议 AI助手（Claude Desktop、VS Code等）可以通过Telnet驱动照明控制台。包括一个内置的编排器、任务分解器和用于完全自主照明控制的长期存储器。

Agent Harness218 MCP tools covering every grandMA2 operation — playback, programming, user management, show files, busking, and more. Connect any MCP-compatible AI assistant and start controlling the console immediately. Embedded Agent CoreOrchestrator, task decomposer, working + long-term memory, and a skill registry with self-improvement suggestions. Inject a real LLM client and it becomes a fully autonomous lighting agent that plans, executes, remembers, and learns. Layered safety gateThree risk tiers enforced before any command reaches the console: SAFE_READ (always allowed), SAFE_WRITE (standard mode), DESTRUCTIVE (blocked until confirm_destructive=True). Line-break injection rejected at the transport layer. A closed learning loopEvery tool call recorded to tool_invocations. SkillImprover surfaces repair suggestions from failure patterns and promotion candidates from high-quality sessions. Skills are versioned playbooks with full lineage tracking. RAG-powered knowledgeThree indexed sources: this repo, ~1,043 grandMA2 help pages, and the MCP SDK. Semantic search via GitHub Models embeddings; falls back to keyword search without an API token.

快速开始 · 建筑 · 218 MCP工具 · 资源 · 提示 · 技能 · 安全系统 · RAG管道

______________________________________________________________________

快速开始

# 1. Install
git clone https://github.com/drohi-r/grandma2-mcp && cd grandma2-mcp
uv sync

# 2. Configure
cp .env.template .env        # then edit with your console IP

# 3. Install git hooks (auto-updates RAG index on every commit)
make install-hooks

# 4. Run
uv run python -m src.server  # starts MCP server (stdio transport)

对于本地浏览器UI：

uv run python -m src.ui

然后打开 http://127.0.0.1:8092.

对于实时控制台目标，使用与MCP服务器相同的连接环境变量运行UI：

GMA_HOST=192.168.20.179 GMA_PORT=30000 GMA_AUTH_BYPASS=1 uv run python -m src.ui

浏览器UI是一个操作员控制台，用于：

仪表板和控制台会话状态
单槽执行器查找
直接顺序检查
按设备类型分组的补丁浏览
期望分析和代理计划/运行流程

重要行为说明：

执行器查找故意只使用单个插槽；默认情况下，UI不批量扫描执行器范围
直接序列ID比基于执行器的序列解析更可靠
空的执行器插槽可以产生正常的MA2 NO OBJECTS FOUND FOR LIST 控制台上的警告
从实时解析Patch视图上的夹具分组 list fixture 输出，不是从完整执行器扫描中推断出来的

\[！提示\] 语义搜索： 添加 GITHUB_MODELS_TOKEN=ghp_... 到 .env，然后运行 uv run python scripts/rag_ingest.py --provider github 一次重建索引真正的嵌入。这 search_codebase MCP工具将自动使用语义排名当令牌存在时。

建筑

graph TD
    H["🤖 Agent Core Layer
src/server_orchestration_tools.py
34 tools (IDs 110–144, excluding 130) · orchestrator · skills"] --> A
    A["🎭 MCP Server Layer
src/server.py
184 server tools · safety gate"] --> B
    B["🧭 Navigation Layer
src/navigation.py
cd · list · scan · set_property"] --> C
    C["🔧 Command Builders
src/commands/
198 pure functions → strings"] --> D
    D["📡 Telnet Client
src/telnet_client.py
async · auth · injection prevention"]

    E["📖 Prompt Parser
src/prompt_parser.py
prompt detection · list parsing"] -.-> B
    F["🛡️ Vocabulary & Safety
src/vocab.py
157 keywords · risk tiers"] -.-> A
    G["🔍 RAG Pipeline
rag/
crawl → chunk → embed → query"] -.-> A
    I["🧠 Memory & Planning
src/agent_memory.py · src/orchestrator.py
WorkingMemory · LTM · TaskDecomposer"] -.-> H
    J["📊 OpenSpace
src/telemetry.py · src/skill.py · src/skill_improver.py
invocation recorder · skill registry · improvement loop"] -.-> H

    style H fill:#1a1a2e,stroke:#e94560,color:#fff
    style A fill:#1a1a2e,stroke:#e94560,color:#fff
    style B fill:#1a1a2e,stroke:#0f3460,color:#fff
    style C fill:#1a1a2e,stroke:#16213e,color:#fff
    style D fill:#1a1a2e,stroke:#533483,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
    style I fill:#0f3460,stroke:#0f3460,color:#fff
    style J fill:#0f3460,stroke:#0f3460,color:#fff

所有网络I/O都隔离在 telnet_client.py.命令构建器是返回字符串的纯函数。导航层使用解析的telnet反馈来编排cd/list工作流。

Agent Harness与Agent Core

grandMA2 MCP是一款 分层混合动力 --边界在代码中是明确的：

图层	它是什么	关键文件
底部184个服务器工具	特工装备 --将核心MCP工具表面暴露于外部AI；推理循环存在于Claude Desktop、VS Code等中。	`src/server.py`
排名前34位的编排工具	嵌入式代理核心 --编排器、任务分解器、长期记忆、技能注册表	`src/server_orchestration_tools.py`, `src/orchestrator.py`

编排器接受 sub_agent_fn 注射点。没有它，工具调用将在进程内运行。在Claude API客户端和grandMA2 MCP中连线，成为一个完全自主的代理，可以规划、执行、记忆和自我改进。

模块概述

模块	角色
`src/server.py`	FastMCP服务器、184个交互式工具、安全门、环境配置
`src/server_orchestration_tools.py`	在FastMCP上注册的34个代理工具（ID 110–144，不包括130）
`src/orchestrator.py`	多智能体任务执行器：水合作用、风险层隔离、LTM； `_showfile_guard()`, `check_showfile()` 用于动态显示变化检测
`src/task_decomposer.py`	自然语言目标→ 有序子任务计划（基于规则）
`src/agent_memory.py`	WorkingMemory（临时）+LongTermMemory（SQLite会话日志）+显示文件基线跟踪(`baseline_showfile`, `showfile_changed()`)
`src/console_state.py`	ConsoleStateSnapshot：水合物19显示内存缺口； `parse_showfile_from_listvar()`
`src/pool_name_index.py`	内存池名称/ID注册表——零成本对象解析
`src/rights.py`	MA2本地权利执行+telnet反馈分类
`src/auth.py`	OAuth 2.1范围强制(`@require_scope`, `@require_ma2_right`)
`src/credentials.py`	OAuth层→ 控制台用户凭据解析器
`src/session_manager.py`	每个运营商的Telnet会话池（LRU、保活、自动重新连接）
`src/navigation.py`	cd+列表+扫描编排
`src/prompt_parser.py`	解析控制台提示和 `list` 表格输出
`src/vocab.py`	157个关键词， `RiskTier`, `FunctionalDomain`，安全分类
`src/commands/`	198个导出的命令生成器函数，按关键字类型分组
`src/commands/busking.py`	6个总线/性能构建器：效果分配、速率/速度、页面释放、推子零
`src/categorization/`	机器学习工具分类：K-Means聚类+自动标注
`src/telemetry.py`	每个工具调用记录器： `tool_invocations` 表、延迟、风险等级
`src/skill.py`	`Skill` 数据类+ `SkillRegistry`：带有沿袭+文件系统技能回退的版本化剧本(`_load_filesystem_skill`, `_list_filesystem_skills`)
`src/skill_improver.py`	`SkillImprover`：维修建议+晋升候选人（只读）
`src/tools.py`	全球GMA2 telnet客户端访问器-- `get_client()` 被所有工具使用

配置

创建一个 .env 文件（参见 .env.template):

# grandMA2 Console
GMA_HOST=192.168.1.100     # grandMA2 console IP (required)
GMA_USER=administrator     # default: administrator
GMA_PASSWORD=admin         # default: admin
GMA_PORT=30000             # default: 30000 (30001 = read-only)
GMA_SAFETY_LEVEL=standard  # standard (default), admin, or read-only
LOG_LEVEL=INFO             # default: INFO

# RAG Pipeline (optional)
GITHUB_MODELS_TOKEN=                          # GitHub PAT with models:read scope
RAG_EMBED_MODEL=openai/text-embedding-3-small # embedding model
RAG_EMBED_DIMENSIONS=1536                     # vector dimensions

\[！注意\] 使用以下工具获取GitHub PAT models:read 范围在 .

级别	行为
`read-only`	只有 `SAFE_READ` 允许的命令(`list`, `info`, `cd`)
`standard`	`SAFE_READ` + `SAFE_WRITE` 允许； `DESTRUCTIVE` 需要 `confirm_destructive=True`
`admin`	允许所有命令，无需确认

MCP工具

服务器暴露 218工具 MCP客户端，分为15类，外加一个代理编排层：

🧭 Navigation & Inspection — 4 tools

工具	说明
`navigate_console`	通过ChangeDest（cd）导航控制台对象树
`get_console_location`	无需导航即可查询当前控制台目标
`list_console_destination`	列出当前目的地的对象及其解析条目
`scan_console_indexes`	批量扫描任何树级别的数字索引

cd /            → go to root
cd ..           → go up one level
cd Group.1      → navigate to Group 1 (dot notation)
cd 5            → navigate by element index
cd "MySeq"      → navigate by name
list            → enumerate objects at current destination

点符号： MA2用途 [object-type].[object-id] 对于对象引用（例如。， Group.1, Preset.4.1, Sequence.3).

💡 Lighting Control — 7 tools

工具	说明
`set_intensity`	在灯具、组或通道上设置调光器级别
`set_attribute`	在设备/组上设置属性值（平移、倾斜、缩放等）
`apply_preset`	应用已存储的预设（颜色、位置、阴影、光束等）
`clear_programmer`	清除编程器状态（全部、选择、活动或顺序）
`park_fixture`	将夹具/通道停放在其当前值或指定值
`unpark_fixture`	松开固定装置/通道上的驻车锁
`fix_locate_fixture`	按默认值修复（停放）或定位选定/指定的灯具

🎯 Programmer / Selection — 8 tools

工具	说明
`modify_selection`	在编程器中选择、取消选择或切换夹具
`adjust_value_relative`	相对调整编程器值（+或-）
`manipulate_selection`	反转或对齐当前夹具选择/编程器值
`select_fixtures_by_group`	选择命名组中的所有设备
`select_executor`	为后续操作设置活动执行器（仅单选；使用取消选择=True清除）
`select_feature`	设置活动功能上下文（更新 `$PRESET`/`$FEATURE`/`$ATTRIBUTE`)
`select_preset_type`	激活预设类型上下文（预设类型1-9或按名称）
`if_filter`	应用IfOutput/IfActive滤波器来限制编程器范围

▶️ Playback & Executor — 9 tools

工具	说明
`execute_sequence`	传统序列播放：开始、暂停或转到提示
`playback_action`	完全播放：go、go_back、goto、fast_forward、fast_back、def_go、def_go_back、def_pause
`control_executor`	控制执行器（执行、暂停、停止、闪烁等）
`load_cue`	在执行器上预加载下一个或上一个提示，而不触发它
`get_executor_status`	查询执行者的状态（当前线索、级别、状态）
`set_executor_level`	在执行器上设置推子级别
`navigate_page`	导航到特定页面或页面+/-
`release_executor`	释放（停用）执行人
`blackout_toggle`	打开/关闭特级大师停电

playback_action — parameters & response fields

参数

参数	类型	说明
`action`	`str`	以下操作之一
`object_type`	`str \	None`	对象类型 `go`/`go_back` （例如。 `"executor"`, `"sequence"`)
`object_id`	`int \	list[int] \	None`	ID或ID列表--列表生成 `N + M + …` 语法
`cue_id`	`int \	float \	None`	需要 `"goto"`
`end`	`int \	None`	范围结束 `go`/`go_back` （构建 `thru N`)
`cue_mode`	`str \	None`	`"normal"`, `"assert"`, `"xassert"`，或 `"release"`
`executor`	`int \	list[int] \	None`	执行人ID `goto`/`fast_forward`/`fast_back` --列表生成 `N + M + …`
`sequence`	`int \	None`	序列ID `goto`/`fast_forward`/`fast_back`

行动

操作	命令已发送	备注
`"go"`	`go [object_type] [id]`	发射下一个信号； `object_id` 接受列表
`"go_back"`	`goback [object_type] [id]`	触发前一个提示； `object_id` 接受列表
`"goto"`	`goto cue N [executor/sequence]`	飞行前确认线索存在；回报 `blocked=True` 关于错误#72
`"fast_forward"`	`>>> [executor N]`	`executor` 接受列表
`"fast_back"`	`>> executor 2 + 4

Go back on the selected executor — response tells you which one fired

playback_action(action="def_go_back")

→ {"command_sent": "defgoback", "selected_executor": "5", "selected_cue_before": "3"}


select_executor — parameters & response fields

**仅限单选。** MA2电话网 `select executor N` 只接受一个执行人编号。没有列表语法——传递一个 `executor_id` 整数。

#### 参数

|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `executor_id` | `int` |必填|执行人编号（1–999）|
| `page` | `int \| None` | `None` |页码--生产 `select executor page.id` （例如。 `page=2, executor_id=5` → `select executor 2.5`) |
| `deselect` | `bool` | `False` |如果 `True`，发送裸机 `select` 清除当前选择(**未在grandMA2 telnet上验证** --检查 `raw_response`) |

#### 响应字段

|字段|始终存在|描述|
|-------|---------------|-------------|
| `command_sent` | ✓ | 发送的确切命令|
| `raw_response` | ✓ | 原始telnet回复|
| `confirmed_selected_exec` | ✓ | 价值 `$SELECTEDEXEC` 在命令后读取(`null` 如果不可用）|
| `risk_tier` | ✓ | `"SAFE_WRITE"` |
| `warning` |如果不匹配|出现时 `confirmed_selected_exec` 与请求的不匹配 `executor_id` |
| `note` |如果取消选择|出现时 `deselect=True` --警告说，裸 `select` 行为未经证实|

#### 页面限定地址

当 `page` 供应，MA2门店 `$SELECTEDEXEC` 仅作为执行人编号（不是页面限定表格）。确认检查与 `executor_id` 独自一人——没有虚假的警告。

#### 例子

Select executor 5 and confirm

select_executor(executor_id=5)

→ {"command_sent": "select executor 5", "confirmed_selected_exec": "5"}

Select executor 5 on page 2

select_executor(executor_id=5, page=2)

→ {"command_sent": "select executor 2.5", "confirmed_selected_exec": "5"}

Clear the current selection

select_executor(executor_id=1, deselect=True)

→ {"command_sent": "select", "note": "Bare 'select' sent … unverified …"}


💾 Programming / Store — 13 tools

|工具|说明|
|------|-------------|
| `create_fixture_group` |选择一系列装置并另存为命名组|
| `store_current_cue` |将程序员状态存储到提示中|
| `store_new_preset` |将编程器状态存储为新的预设|
| `store_object` |存储通用对象——宏、效果、世界等。 |
| `store_cue_with_timing` |使用明确的衰减/延迟时间存储提示|
| `update_cue_data` |用当前程序员值更新现有提示|
| `set_cue_timing` |编辑现有球杆的淡入淡出、延迟或触发时间|
| `set_sequence_property` |在序列上设置属性（例如循环、自动准备）|
| `assign_cue_trigger` |为提示指定触发类型（Go、Follow、Time）|
| `block_unblock_cue` |阻止或取消阻止线索以冻结/恢复其跟踪值|
| `clone_object` |将一个或多个对象克隆（与数据复制）为新ID|
| `remove_from_programmer` |从编程器中移除特定的夹具或通道|
| `run_macro` |按ID执行存储的宏|

> \[！警告\]
> 商店工具有 **破坏性的** --他们要求 `confirm_destructive=True`.

⏱️ Timecode & Timer — 3 tools

|工具|说明|
|------|-------------|
| `control_timecode` |启动、停止或跳过时间码节目|
| `control_timer` |启动、停止或重置计时器|
| `store_timecode_event` |将事件存储到当前时间的时间码节目中|

🔗 Assignment & Layout — 9 tools

|工具|说明|
|------|-------------|
| `assign_object` |指定对象、功能、淡入淡出或布局位置|
| `assign_executor_property` |在执行器上分配22个可设置选项中的任何一个（宽度、优先级、自动启动等）——页面限定|
| `get_executor_state` |通过以下方式读取一个执行器的所有32个字段 `List Executor page.id` （SAFE_READ）|
| `scan_page_executor_layout` |在页面上绘制执行器插槽占用情况图——在宽度扩展之前需要飞行前（SAFE_READ）|
| `discover_fixture_type_attributes` |通过EditSetup树导航（SAFE_READ）发现夹具类型属性名称|
| `label_or_appearance` |标记或设置对象的视觉外观|
| `edit_object` |编辑、剪切或粘贴对象|
| `cut_paste_object` |将对象剪切到剪贴板，或将剪贴板内容粘贴到某个位置|
| `remove_content` |从对象中删除内容——装置、效果、预设类型|
| `save_recall_view` |保存或调用屏幕视图配置|
| `set_executor_priority` |在执行器上设置播放优先级（超/高/正常/低/htp/swap）|
| `set_node_property` |通过点分隔树路径在任何节点上设置属性（DESTRUCCTIVE）|

📁 Show Management — 7 tools

|工具|说明|
|------|-------------|
| `save_show` |将当前节目文件保存到磁盘|
| `list_shows` |列出控制台上可用的显示文件|
| `load_show` |按名称加载节目文件|
| `new_show` |创建新的空节目|
| `delete_show` |从磁盘中删除节目文件|
| `export_objects` |将显示对象（组、预设、宏等）导出到文件|
| `import_objects` |将对象从文件导入到显示中|

> \[！小心\]
> `new_show` 没有 `preserve_connectivity=True` **禁用Telnet**，断开MCP连接。

🔌 Fixture Setup & Patch — 16 tools

|工具|说明|
|------|-------------|
| `list_fixture_types` |列出显示中加载的夹具类型|
| `list_layers` |列出补丁中的夹具层|
| `list_universes` |列出已配置的DMX宇宙|
| `list_library` |浏览MA2夹具库|
| `list_fixtures` |列出当前在节目中修补的装置|
| `browse_patch_schedule` |浏览DMX修补程序计划|
| `patch_fixture` |将设备连接到DMX世界并寻址|
| `unpatch_fixture` |删除设备的DMX补丁分配|
| `set_fixture_type_property` |在设备类型上设置属性|
| `manage_matricks` |管理MAtricks（夹具矩阵）对象|
| `create_matricks_library` |使用25种颜色编码生成组合MAtricks池|
| `store_matricks_preset` |组合套装+商店+标签MAtricks预设工作流程|
| `create_filter_library` |生成带有V/VT/E变体的颜色编码过滤器库|
| `import_fixture_type` |从MA2库导入夹具类型|
| `import_fixture_layer` |将夹具层XML文件导入到显示补丁中|
| `generate_fixture_layer_xml` |生成用于导入的grandMA2夹具层XML文件|

Fixture import workflow

1. Generate the XML file

generate_fixture_layer_xml( filename="my_dimmers", layer_name="Dimmers", layer_index=1, fixtures=[ {"fixture_id": 1, "name": "Dim 1", "fixture_type_no": 2, "fixture_type_name": "2 Dimmer 00", "dmx_address": 1, "num_channels": 1}, ], showfile="myshow", )

2. Import the fixture type from library

import_fixture_type( manufacturer="Martin", fixture="Mac700Profile_Extended", mode="Extended", confirm_destructive=True, )

3. Import the layer

import_fixture_layer(filename="my_dimmers", layer_index=1, confirm_destructive=True)


MAtricks combinatorial library

生成翼×组×块×交织（5⁴=625个项目）的每个组合 **25配色方案** 直接嵌入XML中：

|维度|控件|值|
|-----------|----------|--------|
| **翅膀** |色调|红色（0°）·黄绿色（72°）·青色（144°）·蓝色（216°）·品红色（288°）|
| **群组** |亮度|100%·80%·60%·45%·30%|
|块|--|0-4|
|交错|--|0-4|

颜色使用 `` 在XML中，导入是即时的，不需要telnet循环。

Full library (625 items)

python -m scripts.create_matricks_library --max-value 4

Quick test (16 items)

python -m scripts.create_matricks_library --max-value 1

XML only (no telnet import)

python -m scripts.create_matricks_library --xml-only

Re-apply colors via telnet (if needed)

python -m scripts.create_matricks_library --color-only


🔎 Info, Queries & Discovery — 15 tools

|工具|说明|
|------|-------------|
| `get_object_info` |查询任何对象（夹具、组、序列等）的信息|
| `query_object_list` |列出提示、组、预设、属性或消息|
| `get_variable` |获取控制台变量的当前值|
| `list_system_variables` |列出所有26个内置系统变量(`$TIME`, `$SHOWFILE`等等）|
| `list_sequence_cues` |按时间和标签顺序列出所有线索|
| `discover_object_names` |通过cd树发现池中的命名对象|
| `check_pool_availability` |检查对象池中哪些插槽已占用和空闲|
| `browse_preset_type` |浏览预设类型的特征/属性/子属性树|
| `list_preset_pool` |按类型列出全局预设池中的预设|
| `browse_effect_library` |浏览grandMA2效果库|
| `browse_macro_library` |浏览grandMA2宏库|
| `browse_plugin_library` |浏览grandMA2插件库|
| `highlight_fixtures` |切换选定装置的高亮显示模式|
| `list_undo_history` |列出最近的撤消历史记录条目|
| `discover_filter_attributes` |从修补的夹具中发现并显示特定的过滤器属性|

⚙️ Console & Utilities — 8 tools

|工具|说明|
|------|-------------|
| `send_raw_command` |直接发送任何MA命令（安全门控）|
| `copy_or_move_object` |在插槽之间复制或移动对象（使用合并/覆盖）|
| `delete_object` |按类型和ID删除任何对象|
| `manage_variable` |设置或添加控制台变量（全局或用户范围）|
| `undo_last_action` |撤消上次控制台操作|
| `toggle_console_mode` |切换控制台模式：盲模式、高亮模式、冻结模式、单人模式|
| `list_fader_modules` |列出连接的推子模块及其配置|
| `list_update_history` |列出编程更新历史记录|

👤 User Management — 5 tools

|工具|说明|
|------|-------------|
| `list_console_users` |列出控制台上配置的所有用户配置文件|
| `create_console_user` |使用名称和密码创建新的用户配置文件|
| `delete_user` |删除用户配置文件|
| `inspect_sessions` |检查活动的Telnet会话和连接的运营商|
| `assign_world_to_user_profile` |为用户配置文件分配一个世界（可见性范围）|

> \[！注意\]
> 需要 `GMA_SCOPE=gma2:user:manage` （管理层）。Bootstrap 5默认用户帐户
> 随着 `python scripts/bootstrap_console_users.py`.

🤖 ML-Based Tool Discovery — 4 tools

|工具|说明|
|------|-------------|
| `list_tool_categories` |通过K-Means聚类浏览自动发现的工具类别|
| `recluster_tools` |重新运行完整的ML管道（提取→ 嵌入→ 簇→ 标签）|
| `get_similar_tools` |通过特征空间中的欧几里德距离找到最相似的工具|
| `suggest_tool_for_task` |为自然语言任务描述提供建议工具|

🔍 Codebase Search / RAG — 1 tool

|工具|说明|
|------|-------------|
| `search_codebase` |索引代码库和MA2文档的语义搜索|

🤖 Orchestration & Console State — 34 tools

这些工具构成 **代理层** (`src/server_orchestration_tools.py`).它们使
使用内存、风险层隔离和零telnet状态查询执行多步任务
通过一个 `ConsoleStateSnapshot` 关闭19的缓存显示内存缺口。

对于中的高级代理线束 `src/server.py`，更喜欢 `plan_agent_goal` 预览
和 `run_agent_goal` 执行。使用 `decompose_task` / `run_task` 当你具体
希望在中使用较低级别的基于规则的编排界面 `src/server_orchestration_tools.py`.

#### 任务编排（工具110–118）

|工具|说明|
|------|-------------|
| `decompose_task` |将照明目标分解为有序的多智能体计划（执行前进行审查）|
| `run_task` |通过风险等级隔离、记忆和状态水合来执行完整的任务|
| `list_agent_sessions` |从长期记忆中列出最近的任务会话|
| `recall_agent_session` |从过去的会话还原WorkingMemory快照|
| `agent_token_report` |报告代理会话中的令牌消耗情况|
| `register_decomposition_rule` |在运行时注册自定义任务分解规则|
| `resolve_object_ref` |将池对象名称/ID解析为引用的MA2令牌（零telnet）|
| `list_pool_names` |列出内存索引中池类型的所有名称和ID|
| `hydrate_console_state` |触发新的ConsoleStateSnapshot保湿|

#### 控制台状态查询（工具119–129）

从缓存的快照中读取-- **无需telnet往返**.

|工具|说明|
|------|-------------|
| `get_console_state` |快照摘要、年龄和过期警告|
| `get_park_ledger` |所有当前停放的灯具|
| `get_filter_state` |活动过滤器ID和V/VT/E标志设置|
| `get_world_state` |活跃世界和可见性范围|
| `get_matricks_state` |写入跟踪的MAtricks状态（交织、块、翅膀等）|
| `get_programmer_selection` | `$SELECTEDFIXTURESCOUNT`, `$SELECTEDEXEC`, `$SELECTEDEXECCUE` |
| `hydrate_sequences` |深层水合物特定序列线索和部分|
| `get_sequence_memory` |快照中的序列属性和CueRecords|
| `assert_selection_count` |根据预期值验证夹具选择计数|
| `assert_preset_exists` |飞行前检查：确认预设插槽已占用|
| `get_executor_detail` |给定执行人ID的完整执行人状态|

#### 编排安全与诊断（工具131–137）

|工具|说明|
|------|-------------|
| `diff_console_state` |将当前快照与调用者提供的基线进行比较；返回已更改的字段|
| `get_showfile_info` |从快照（零telnet）返回显示文件名、版本、主机状态和活动用户|
| `watch_system_var` |轮询grandMA2系统变量，直到它发生变化或达到超时时间|
| `confirm_destructive_steps` |分解目标，只返回破坏性步骤供人工审查|
| `abort_task` |将正在运行的会话标记为已中止，并返回已完成/失败的步骤摘要|
| `retry_failed_steps` |从LTM重新加载过去的会话并重新运行原始目标|
| `assert_fixture_exists` |两层夹具补丁验证（快照索引→ 实时telnet回退）|

#### OpenSpace层——遥测、技能和改进（工具ID 110-144，不包括130）

|工具|范围|描述|
|------|-------|-------------|
| `get_tool_metrics` |DISCOVER | N天内任何工具的延迟+错误率统计数据|
| `list_skills` |发现|按姓名、描述或上下文搜索技能注册表|
| `get_skill` |发现|完整细节+单一技能的传承链|
| `promote_session_to_skill` |PROGRAMMER_WRITE|手动将已完成的会话提升为命名的版本化技能|
| `get_improvement_suggestions` |DISCOVER |维修建议（故障工具）+促销候选人（成功会话）|
| `approve_skill` |SYSTEM_ADMIN |人门：设置 `approved=True` 在特工使用之前，先掌握破坏性瞄准镜技能|
| `assert_showfile_unchanged` |DISCOVER |验证开放节目是否与水合基线相匹配——实时ListVar与缓存快照|

#### 合规性、补丁验证和跨场馆工具

|工具|范围|描述|
|------|-------|-------------|
| `detect_dmx_address_conflicts` |发现|扫描所有宇宙以查找重叠的设备DMX地址分配|
| `get_telemetry_report` |DISCOVER |将工具调用遥测数据导出为JSON或markdown审计日志|
| `generate_compliance_report` |发现| SB 132/会话遥测的安全审计合规报告|
| `validate_preset_references` |DISCOVER |扫描提示列表，查找已删除或丢失的预设池条目的引用|
| `list_macro_jump_targets` |DISCOVER |解析宏行并提取所有跳跃目标以进行指数变动规划|
| `check_pool_slot_availability` |DISCOVER |飞行前：在一定范围内哪些池位是空的，哪些是占用的|
| `remap_fixture_ids` |PROGRAMMER_WRITE|导入PSR后，将夹具引用从一个ID重新映射到另一个ID|

> \[！注意\]
> 呼叫 `hydrate_console_state` 在使用状态查询工具之前。快照缓存值
> 没有直接telnet回读（MAtricks状态、公园分类账、过滤VTE标志等）。
> 检查新鲜度 `get_console_state`.

🎛️ Busking & Performance — 6 tools

|工具|说明|
|------|-------------|
| `assign_temp_fader` |在当前选定的执行器上设置温度衰减器级别|
| `assign_effect_to_executor` |将效果模板绑定到执行器插槽（DESTRUCCTIVE--需要 `confirm_destructive=True`) |
| `modulate_effect` |设定费率(`EffectRate`)或速度(`EffectSpeed`)关于积极作用|
| `clear_effects_on_page` |释放页面范围内的所有效果执行器|
| `normalize_page_faders` |将页面上的所有推子设置为0而不释放|
| `classify_show_mode` |检查执行者分配，并将演出分类为 `busking`, `sequence`, `hybrid`，或 `empty` |

## MCP资源

可向任何MCP客户端公开的13个只读资源。在调用工具之前，将它们用于零telnet上下文。

|URI|描述|
|-----|-------------|
| `ma2://docs/rights-matrix` |OAuth作用域→ MA2Right映射矩阵（JSON）|
| `ma2://docs/vocab-summary` |包含RiskTier和类别的所有157个关键字（JSON）|
| `ma2://docs/tool-taxonomy` |ML集群工具分类法——218个工具分为14类（JSON）|
| `ma2://docs/responsibility-map` |架构决策的模块责任图（Markdown）|
| `ma2://docs/tool-surface-tiers` |每个工具的A/B/C级分类（Markdown）|
| `ma2://docs/volunteer-guide` |简明语言志愿者操作指南：三层访问模式+周日飞行前|
| `ma2://docs/sb132-compliance` |SB 132/CA电影税收抵免安全文件映射到遥测字段|
| `ma2://docs/rdm-workflow` |RDM发现、自动匹配和设备信息最佳实践|
| `ma2://docs/lua-scripting` |grandMA2 Lua 5.2脚本参考： `gma.*` 命名空间+常见模式|
| `ma2://skills/{skill_id}` |按ID的技能注入有效负载——返回格式化的用户消息，准备进行代理注入|
| `ma2://busking/patterns` |最佳实践街头表演模式：推子模式、歌曲宏协议、现场恢复|
| `ma2://busking/effect-design` |对执行器分配模式、速率与速度、MAtricks分层的影响|
| `ma2://busking/color-design` |HSB调色板策略、预设编号、单色约束、颜色锁定|

所有资源都是只读的，没有控制台副作用。

## MCP提示

十个工作流程提示，将工具编排成有指导的多步骤过程。

|提示|参数|描述|
|--------|------|-------------|
| `preflight_destructive_change` | `operation`, `target`, `reason` |在任何破坏性工具调用之前的安全飞行前检查表——检查权限、目标存在、盲模式和执行器状态|
| `inspect_console` | `focus` |引导式只读控制台状态检查-- `full`, `playback`, `fixtures`, `show`，或 `rights` |
| `plan_cue_store` | `sequence_id`, `cue_number`, `fixture_selection`, `preset_or_values` |计划带有飞行前和验证步骤的提示存储操作——不执行|
| `diagnose_playback_failure` | `executor_id`, `symptom` |结构化回放故障诊断——返回 `fault_class`, `root_cause`, `recommended_actions` |
| `load_show_safely` | `show_name` |安全显示加载检查表——防止因丢失而意外断开Telnet连接 `/globalsettings` |
| `bootstrap_rights_users` | *（无）* |指导六层MA2权限用户帐户的配置|
| `volunteer_sunday_preflight` | `show_name`, `campus_name` |志愿者操作员的SAFE_READ飞行前验证——服务前的绿色/琥珀色/红色表演验证|
| `generate_busking_template` | `target_page`, `fixture_strategy` |从当前补丁构建一个完整的总线模板——组、预设、效果、执行器布局|
| `pre_show_health_check` | `sequence_ids`, `strict` |完整的表演健康审计——表演文件、预设、执行器、提示、公园和DMX，并附有评分结果|
| `adapt_show_to_venue` | `source_show_description`, `new_venue_notes` |跨场馆演出适应——补丁比较、组重映射、预设验证|

## 代理技能

45个教学模块 `.claude/skills/` 作为用户消息注入到代理对话中。它们教代理特定领域的工作流程，而不在工具文档字符串中嵌入知识。

|技能|描述|
|-------|-------------|
| `ma2-command-rules` |MA2命令构建、对象解析、引用规则和安全升级|
| `telnet-feedback-triage` |使用以下工具对grandMA2 Telnet反馈进行分类和总结 `FeedbackClass` enum|
| `feedback-investigator` |员工手册：对Telnet反馈失败进行分类和调查|
| `cue-list-auditor` |员工手册：审核提示列表差距、标签、时间和健康状况|
| `operator-recovery-runbook` |对卡住的播放、污染的编程器、错误的世界/过滤器和类似的节目紧急情况的现场事件响应|
| `busking-lighting-performance` |现场表演——每个效果模型的推子、执行器布局、效果分层、现场恢复|
| `song-macro-page-design` |宋宏页面——第一按钮协议、执行器列布局、跳转目标安全|
| `constrained-color-design` |单色HSB调色板设计——预设编号、颜色锁定、歌曲到调色板映射|
| `preset-library-architect` |从原始属性值构建完整的调光器/位置/颜色/gobo预设池|
| `preset-impact-manager` |通过跟踪下游线索和显示文件引用，安全地评估预设更新或删除|
| `patch-and-group-builder` |修补夹具，按类型/位置构建组，并验证选择计数|
| `festival-stage-setup` |端到端的一次性节日工作流程，从修补好的钻机到准备好表演的演出文件|
| `fixture-swap-surgeon` |分析夹具替换并计划兼容的交换+迁移步骤|
| `chaser-builder` |基于步进的追逐器、通过MAtricks的运行灯、闪光灯——速度/速率/方向控制|
| `cue-tracking-and-timing` |跟踪与非跟踪、阻止/解除阻止、MIB、定时层、触发类型、更新与存储|
| `tracking-debugger` |诊断序列中的跟踪泄漏、意外块和线索继承问题|
| `cue-to-cue-rehearsal` |在排练过程中，通过状态总结和线索差异进行逐线索引导演练|
| `executor-configuration` |执行器优先级、触发类型、推子功能、速度控制、保护选项|
| `show-management-and-psr` |保存/加载/新建节目（保持连接）、PSR工作流程、导出/导入XML|
| `macro-advanced` |SetVar/SetUserVar、条件语句、CmdDelay、跳转目标、XML编写、存储组计时|
| `macro-linter-and-refactorer` |检查宏是否存在不安全的模式、中断的跳转和清理机会|
| `clone-and-data-transfer` |克隆夹具 `/selective`、复制/移动池对象、球杆范围复制、交叉显示PSR|
| `effect-programmer` |从头开始构建效果，图层速率/速度/相位，分配给执行者|
| `world-filter-designer` |创建世界、指定装置、配置过滤器对象、控制可见性|
| `timecode-show-programmer` |构建时间码显示，将事件分配给线索，启用/禁用曲目|
| `color-preset-creator` |存储RGB值的通用颜色预设——构建预设池|
| `color-palette-sequence-builder` |构建一个线索序列，其中每个线索都引用一个通用的颜色预设|
| `auto-layout-color-picker` |安全地预装并运行已安装的自动布局颜色选择器插件——组、范围、图像、布局和运行后验证|
| `hue-palette-creator` |使用HSB颜色模型存储96个通用色调预设（4.101–4.196）|
| `hue-sequence-builder` |从相邻的色调对构建16个线索序列——每个色调有8个饱和度变体|
| `sequence-executor-assigner` |为自由执行器分配一个序列，使其显示为播放推子|
| `rdm-workflow` |RDM发现→ 设备信息→ 通过MCP自动匹配工作流|
| `lua-and-plugins` |Lua 5.2脚本 `gma.*` 命名空间、插件调用和重新加载生命周期|
| `troubleshoot-no-output` |Grand Master的系统性无输出诊断，甚至包括DMX和夹具级故障|
| `companion-integration` |构建反映MA2执行器布局的Bitfocus Companion按钮页面|
| `showkontrol-bpm-sync` |将ShowKontrol的CDJ节奏同步到MA2速度大师中，以获得实时BPM锁定效果|
| `psr-show-migration` |PSR具有飞行前时隙检查、夹具ID验证和导入后差异|
| `compliance-documentation` |从会话遥测生成SB 132/保险审计报告——仅限SAFE_READ|
| `volunteer-operations` |三层访问模型、周日早间飞行前和非程序员事件响应|
| `view-and-layout-designer` |自定义控制台视图、执行器按钮放置、图像分配、图纸调用|
| `show-health-check` |演出前审计——演出文件、预设、执行器、提示、公园、DMX。返回绿色/琥珀色/红色|
| `busking-template-generator` |从任何修补的装备构建一个完整的总线模板——组、预设、效果、执行器页面|
| `cross-venue-adaptation` |使演出适应新的场地装备——补丁比较、组重新映射、预设范围验证|
| `training-mode` |为学生、教堂志愿者和IATSE培训项目提供带注释的SAFE_READ控制台之旅|
| `remote-monitoring` |连续SAFE_READ轮询——显示变化检测、警报条件、广播和架构协议|

技能通过以下方式按需加载 `ma2://skills/{skill_id}` 资源或由编排器注入。使用 `list_skills` / `get_skill` 在运行时浏览和检查它们的工具。

## 客户端设置

### 克劳德桌面版

添加到您的Claude桌面配置(`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上）：

{ "mcpServers": { "gma2": { "command": "uv", "args": ["--directory", "/path/to/grandma2-mcp", "run", "python", "-m", "src.server"], "env": { "GMA_HOST": "192.168.1.100", "GMA_USER": "administrator", "GMA_PASSWORD": "admin" } }, "time": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-time"] } } }


这 `time` 服务器为降价前端提供准确的ISO 8601时间戳——这是必需的 `.claude/rules/markdown-frontmatter.md`。它也通过以下方式自动注册到Claude Code CLI `.mcp.json` 对于VS Code，请通过 `vscode-mcp-provider/`.

### VS Code

这 `vscode-mcp-provider/` 目录包含一个VS Code扩展，该扩展注册了用于AI助手发现的grandMA2 MCP服务器。

cd vscode-mcp-provider npm install && npm run compile

Then install in VS Code (F5 to debug, or package with vsce)


看 [`vscode-mcp-provider/README.md`](vscode-mcp-provider/README.md) 了解全部细节。

### 法典

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


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

codex --mcp-config codex.json


## 安全系统

grandMA2 MCP执行 **三层模型** 其中有效权限是所有三者的交集——没有任何一层可以扩展权限：

scope ∩ policy ∩ ma2_rights = FINAL AUTHORITY


### 第1层——OAuth身份(`src/auth.py`)

六个范围层映射到由创建的控制台用户 `scripts/bootstrap_console_users.py`:

| `GMA_SCOPE` |控制台用户|MA2权限|可以|
|-------------|-------------|-----------|--------|
| `tier:0` | `guest` |无（0）|只读--列表、信息、光盘|
| `tier:1` | `operator` |播放（1）|开始、闪烁、关闭、时间码|
| `tier:2` | `presets_editor` |预设（2）|设置属性，应用/存储预设|
| `tier:3` | `programmer` |程序（3）|存储提示、组、序列、宏|
| `tier:4` | `tech_director` |设置（4）|补丁、夹具导入、控制台设置|
| `tier:5` | `administrator` |管理员（5）|用户管理，显示加载/删除|

### 第2层——策略门(`src/rights.py`)

每个工具都有注释 `@require_ma2_right(MA2Right.X)` 其在发送任何Telnet命令之前强制执行OAuth范围要求。这 `check_permission()` 实用程序提供了一个结合范围和权限检查的统一门：

result = check_permission("store_current_cue", granted_scopes, user_right)

scope ∩ MA2Right — both must pass

if not result.allowed: return result.as_block_response()


所有218个工具都已映射到 `doc/ma2-rights-matrix.json`.

### 第3层——MA2本机权限（控制台强制）

Telnet会话作为控制台用户运行，其本机权限由grandMA2本身强制执行。超出该用户权限级别的命令将被拒绝 `Error #72` --无论第1层或第2层允许什么，都存在不可撤销的底线。

> 需要Bootstrap：在新的节目中，运行 `python scripts/bootstrap_console_users.py` 作为管理员创建5个中间用户。仅 `Administrator` 和 `Guest` 原生存在。

### 风险等级（服务器端大门）

除了三层模型外，每个关键字还被分为以下三个风险层之一： `_handle_errors`:

|层级|描述|示例|
|------|-------------|----------|
| `SAFE_READ` |只读查询| `Info`, `List`, `CmdHelp`, `ChangeDest` |
| `SAFE_WRITE` |可逆状态变化| `Go`, `At`, `Clear`, `Park`, `SelFix` |
| `DESTRUCTIVE` |数据突变或丢失| `Delete`, `Store`, `Copy`, `Move`, `Shutdown` |

`DESTRUCTIVE` 工具需要 `confirm_destructive=True` 除了OAuth范围之外。

> \[！重要\]
> **命令注入预防：** 线路中断(`\r`, `\n`)在任何命令到达控制台之前都会被拒绝。
> telnet客户端还剥离了它们作为深度防御措施。

### 关键字分类

词汇表将所有 **157 grandMA2关键词** 分为以下几类：

|类别|计数|描述|示例|
|----------|-------|-------------|----------|
| `OBJECT` |56|控制台对象（名词）|通道、夹具、组、预设、执行器|
| `FUNCTION` |90 |动作（动词）|存储、删除、执行、终止、列出、信息|
| `HELPING` |5 |语法连接器| And、Thru、Fade、Delay、If|
| `SPECIAL_CHAR` |6 |运算符符号|加号 `+`，减 `-`，点 `.`，Slash `/` |

Object Keyword metadata

对象关键字携带来自实时telnet验证的其他元数据：

|字段|描述|
|-------|-------------|
| `context_change` |关键字是否更改 `[default]>` 提示上下文|
| `canonical` |控制台规范拼写（例如。， `DMX` → `Dmx`) |
| `notes` |实时telnet测试的行为记录|

在56个对象关键字中：53个更改默认提示上下文，3个不更改(`Full`, `Normal`, `Zero` --这些设置调光器值）。 `Channel` 和 `Default` 有 `context_change=True`；他们的笔记描述了重置 *默认关键字*，而不是提示上下文。

**控制台别名：**

|输入|解析为|
|-------|-------------|
| `DMX` | `Dmx` |
| `DMXUniverse` | `DmxUniverse` |
| `Sound` | `SoundChannel` |
| `RDM` | `RdmFixtureType` |

classify_token() example

from src.vocab import build_v39_spec, classify_token

spec = build_v39_spec()

result = classify_token("Delete", spec)

result.risk == RiskTier.DESTRUCTIVE

result.canonical == "Delete"

result.category == KeywordCategory.FUNCTION

result = classify_token("Channel", spec)

result.risk == RiskTier.SAFE_WRITE

result.category == KeywordCategory.OBJECT

result = classify_token("DMX", spec)

result.canonical == "Dmx" (alias resolution)


## RAG管道

graph LR A[Crawl] --> B[Chunk] --> C[Embed] --> D[Store SQLite] --> E[Query] --> F[Rerank]

style A fill:#264653,color:#fff style B fill:#2a9d8f,color:#fff style C fill:#e9c46a,color:#000 style D fill:#f4a261,color:#000 style E fill:#e76f51,color:#fff style F fill:#e63946,color:#fff

Ingest repository with real embeddings

uv run python scripts/rag_ingest.py --provider github -v

Semantic search

uv run python scripts/rag_query.py "store cue with fade" -v

Text-only keyword search (no token needed)

uv run python scripts/rag_query.py "store cue with fade"


|提供者|标记|需要|
|----------|------|----------|
|GitHub模型| `--provider github` | `GITHUB_MODELS_TOKEN` |
|零向量存根| `--provider zero` |无（用于测试）|
|自动检测| *（无旗）* |如果设置了令牌，则使用GitHub，否则使用零向量|

Pipeline stages

**摄取**

|阶段|模块|描述|
|-------|--------|-------------|
|爬行| `rag/ingest/crawl_repo.py` |浏览回购文件，尊重忽略模式|
|Chunk| `rag/ingest/chunk.py` |拆分为重叠的令牌绑定块|
|提取物| `rag/ingest/extract.py` |提取符号名称（函数、类、标题）|
|嵌入| `rag/ingest/embed.py` |通过GitHub模型API生成向量|
|商店| `rag/store/sqlite.py` |将块+向量写入SQLite|

**检索**

|阶段|模块|描述|
|-------|--------|-------------|
|查询| `rag/retrieve/query.py` |嵌入查询、余弦相似度搜索|
|重新排名| `rag/retrieve/rerank.py` |按相关性对结果进行排序和筛选|

Chunking strategies

|语言|策略|边界|
|----------|----------|----------|
|Python |基于AST |顶级 `def`/`class` 边界通过 `ast.parse` |
|Markdown |基于标题| `#` 航向线|
|其他|基于线条的|固定大小的重叠线条窗口|

默认值：最大1200个令牌/块，20行重叠。配置于 `rag/config.py`.

## 控制台导航

导航系统结合了三层，通过telnet发现控制台状态：

1. **命令生成器** (`changedest()`)生成具有MA2点符号的cd字符串
1. **远程登录客户端** 发送命令并捕获原始响应
1. **提示解析器** 从响应中提取当前位置

Prompt parsing patterns

|模式|示例|已解析|
|---------|---------|--------|
|支架提示| `[Group 1]>` |地点=`Group 1`，类型=`Group`，id=`1` |
|点符号| `[Group.1]>` |地点=`Group.1`，类型=`Group`，id=`1` |
|化合物ID| `[Preset.4.1]>` |地点=`Preset.4.1`，类型=`Preset`，id=`4.1` |
|尾随斜线| `[Sequence 3]>/` |地点=`Sequence 3`，类型=`Sequence`，id=`3` |
|角形支架| `Root>` |地点=`Root`，类型=`Root` |

List output parsing

在cd进入目的地之后， `list` 返回表格输出。解析器会自动检测标题并映射列。

|字段|描述|
|-------|-------------|
| `object_type` |类型名称（例如。 `Group`, `UserImage`) |
| `object_id` |父级中的数字ID|
| `name` |显示名称|
| `columns` |Dict将额外的标头名称映射到值|
| `raw_line` |手动检查的完整原始线路|

## 树木扫描仪

`scripts/scan_tree.py` 通过Telnet递归地遍历grandMA2对象树，构建每个节点的完整JSON映射。

Quick scan (depth 4)

uv run python scripts/scan_tree.py --max-depth 4 --output scan_test.json

Full scan (depth 20)

uv run python scripts/scan_tree.py --max-depth 20 --output scan_full.json

Resume an interrupted scan

uv run python scripts/scan_tree.py --max-depth 20 --output scan_full.json --resume


Scanner options

|标志|默认值|描述|
|------|---------|-------------|
| `--host` |从 `.env` |控制台IP地址|
| `--port` |30000 | Telnet端口|
| `--max-depth` |20 |最大递归深度|
| `--max-nodes` |0| N个节点后停止（0=无限制）|
| `--max-index` |60 |回退指数限制|
| `--failures` |3|连续丢失N个索引后停止分支|
| `--output` | `scan_output.json` |输出JSON文件路径|
| `--delay` |0.08 |命令之间的秒数|
| `--resume` |false |从进度文件恢复扫描|

Optimizations & resilience

**速度优化：**

- 已知叶型快捷方式--跳过已知叶型的cd+列表
- 智能间隙探测——仅填充已知ID之间≤5的间隙
- 重复检测——比较原始数据 `list` 跳过相同子树的签名
- 连续空叶提前退出——10个空槽后停止

**韧性：**

- 通过全路径恢复自动重新连接
- 每个根分支后逐步保存到JSONL
- 恢复跨会话的支持
- 心跳记录和分支超时

## 指挥建设者

命令生成器层(`src/commands/`)将grandMA2命令字符串作为纯函数生成——无网络I/O。 **198个导出函数** （206个导出，包括8个常量），涵盖导航、选择、播放、值、存储、删除、分配、标签等。

> grandMA2语法： `[Function] [Object]` --关键字是 **函数** （动词）， **对象** （名词），或 **帮助** （介词）。

Full command builder reference

### 导航

|功能|输出|
|----------|--------|
| `changedest("/")` | `cd /` |
| `changedest("..")` | `cd ..` |
| `changedest("Group", 1)` | `cd Group.1` |
| `changedest("Preset", "4.1")` | `cd Preset.4.1` |

### 对象关键字

|功能|输出|
|----------|--------|
| `fixture(34)` | `fixture 34` |
| `group(3)` | `group 3` |
| `preset("color", 5)` | `preset 4.5` |
| `cue(5)` | `cue 5` |
| `sequence(3)` | `sequence 3` |
| `executor(1)` | `executor 1` |
| `dmx(101, universe=2)` | `dmx 2.101` |
| `attribute("Pan")` | `attribute "Pan"` |

### 选择和清除

|功能|输出|
|----------|--------|
| `select_fixture(1, 10)` | `selfix fixture 1 thru 10` |
| `select_fixture([1, 3, 5])` | `selfix fixture 1 + 3 + 5` |
| `clear()` | `clear` |
| `clear_all()` | `clearall` |

### 商店

|功能|输出|
|----------|--------|
| `store("macro", 5)` | `store macro 5` |
| `store_cue(1, merge=True)` | `store cue 1 /merge` |
| `store_preset("dimmer", 3)` | `store preset 1.3` |
| `store_group(1)` | `store group 1` |

### 回放

|功能|输出|
|----------|--------|
| `go("executor", 3)` | `go executor 3` |
| `go_executor(3)` | `go executor 3` |
| `go_back("executor", 3)` | `goback executor 3` |
| `go_back_executor(3)` | `goback executor 3` |
| `goto(3)` | `goto cue 3` |
| `go_sequence(1)` | `go+ sequence 1` |
| `go_macro(2)` | `go macro 2` |
| `on_executor(3)` | `on executor 3` |
| `off_executor(3)` | `off executor 3` |
| `flash_executor(3)` | `flash executor 3` |
| `swop_executor(3)` | `swop executor 3` |
| `solo_executor(3)` | `solo executor 3` |
| `top_executor(3)` | `top executor 3` |
| `stomp_executor(3)` | `stomp executor 3` |
| `release_executor(3)` | `release executor 3` |
| `goto_cue(1, 5)` | `goto cue 5 sequence 1` |
| `pause_sequence(1)` | `pause sequence 1` |
| `goto_timecode(1, "00:01:30:00")` | `goto timecode 1 "00:01:30:00"` |
| `go_fast_forward()` | `>>>` |
| `go_fast_forward(executor=[1, 2, 3])` | `>>> executor 1 + 2 + 3` |
| `go_fast_back()` | ` \[！注意\]
> 外观RGB使用 **0–100** 百分比刻度（不是0-255）。HSB：色调0-360，饱和/明亮0-100。

### 进口/出口

|功能|输出|
|----------|--------|
| `export_object("Group", 1, "mygroups")` | `export Group 1 "mygroups"` |
| `import_object("mygroups", "Group", 5)` | `import "mygroups" at Group 5` |

### 变量

|功能|输出|
|----------|--------|
| `set_var("myvar", 42)` | `setvar "myvar" 42` |
| `set_user_var("speed", 100)` | `setuservar "speed" 100` |

## 项目结构

grandma2-mcp/ ├── src/ │ ├── server.py # FastMCP server (184 interactive tools) │ ├── server_orchestration_tools.py # Agentic layer (34 tools, IDs 110–144 excluding 130) │ │ │ │ # Orchestration & Memory │ ├── orchestrator.py # Multi-agent task runner + session memory │ ├── task_decomposer.py # NL goal → ordered SubTask plan │ ├── agent_memory.py # WorkingMemory + LongTermMemory (SQLite) │ ├── console_state.py # ConsoleStateSnapshot (19-gap hydration) │ ├── pool_name_index.py # Object name/ID registry (zero-cost resolve) │ ├── telemetry.py # Per-tool invocation recorder (tool_invocations table) │ ├── skill.py # Skill dataclass + SkillRegistry (versioned playbooks) │ ├── skill_improver.py # SkillImprover: repair suggestions + promotion candidates │ │ │ │ # Security & Auth │ ├── auth.py # OAuth 2.1 scope enforcement │ ├── credentials.py # OAuth tier → console credentials │ ├── rights.py # MA2 native rights + telnet feedback │ ├── session_manager.py # Telnet session pool (LRU + keepalive) │ │ │ │ # Core I/O & Parsing │ ├── telnet_client.py # Async Telnet (telnetlib3, injection prevention) │ ├── navigation.py # cd + list + scan orchestration │ ├── prompt_parser.py # Telnet prompt & tabular list parser │ ├── vocab.py # 157 keywords, risk tiers, functional domains │ │ │ │ # Command Builders & ML │ ├── commands/ # 198 exported command-builder functions │ │ ├── busking.py # Busking/performance builders (6 functions) │ │ ├── objects/ # Object keywords (9 modules) │ │ └── functions/ # Function keywords (17 modules) │ └── categorization/ # ML tool categorization (K-Means) │ ├── rag/ # RAG pipeline │ ├── ingest/ # crawl → chunk → embed → store │ ├── retrieve/ # query → rerank │ └── store/ # SQLite vector store (rag.db) ├── scripts/ │ ├── rag_ingest.py # Ingest repo (zero-vector or real embeddings) │ ├── rag_ingest_web.py # Crawl MA2 help docs (daily batches) │ ├── rag_query.py # Query RAG store from CLI │ ├── bootstrap_console_users.py # Create 5 console user accounts │ ├── create_matricks_library.py # MAtricks combinatorial library (625 items) │ ├── create_filter_library.py # Filter library XMLs (168 items with VTE) │ └── strategic_scan.py # Fast 4-phase console tree scan (~24 min) ├── tests/ ├── doc/ # Command builders ref + cd-tree docs ├── vscode-mcp-provider/ # VS Code MCP extension └── .claude/ # Skills (playbooks) + scoped rules ├── skills/ # 44 agent instruction modules └── rules/ # 5 scoped rule files (loaded on demand)


## 依赖项

|包装|用途|
|---------|---------|
| `mcp>=1.21.0` |模型上下文协议服务器框架|
| `python-dotenv>=1.0.0` |负载 `.env` 配置|
| `telnetlib3>=2.0.8` |异步Telnet客户端|
| `beautifulsoup4>=4.12.0` |RAG网络爬虫的HTML解析|
| `numpy>=1.26.0` |K-Means聚类用于工具分类|
| `pytest>=9.0.1` |测试（开发）|
| `pytest-asyncio>=1.3.0` |异步测试支持（开发）|

需要 **Python≥3.12**.

## 发展

Run all tests

make test # or: uv run python -m pytest -v

Run a subset

uv run python -m pytest tests/test_vocab.py # single file uv run python -m pytest tests/test_rag_*.py # RAG tests only

Start MCP server

uv run python -m src.server

Login test

uv run python scripts/main.py


## 故障排除

|问题|解决方案|
|---------|----------|
|连接失败|验证控制台IP/端口，检查Telnet是否已启用，检查防火墙|
|身份验证错误|确认用户名/密码，检查控制台上是否存在用户|
|命令不起作用|根据MA2用户手册验证语法，确保对象存在|
|RAG摄取401 |验证 `GITHUB_MODELS_TOKEN` 有 `models:read` 范围|
|RAG查询为空|运行 `scripts/rag_ingest.py` 首先，检查 `rag/store/rag.db` 存在|

## 许可证

[Apache 2.0](LICENSE)

Grandma2 MCP

快速接入

详细介绍

标题：grandMA2 MCP description:grandMA2照明控制台的MCP服务器——通过Telnet提供218个MCP工具 版本：1.1.0 创建时间：2026-04-02T00:00:00Z 最后更新时间：2026-04-04T00:00:00Z