GMA2 MCP
Telnet을 통해 AI 어시스턴트가 grandMA2 조명 콘솔을 제어할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다. 이 서버는 Model Context Protocol을 통해 큐 관리, 장치 제어, 프리셋 관리, 실행기(executor) 제어, 매크로 편집, 외관 할당, 일괄 작업, 콘솔 상태 조회, 쇼 파일 관리, 리드백 검증, 뮤직 쇼 워크플로우 등 101가지의 고수준 도구를 노출합니다.
목차 (Table of Contents)
개요 (Overview)
grandMA2 콘솔은 Telnet을 통해 명령어를 수락하지만, 정확한 명령어 문자열을 구축하려면 MA2 구문 규칙(syntax rules)—키워드 순서 지정, 프리셋 유형 매핑, 옵션 플래그 및 객체 계층 구조에 대한 지식이 필요합니다. 이 프로젝트는 이러한 복잡성을 계층화된 컴포넌트들로 처리합니다:
- Command Builder (
src/commands/) -- 공식 문법 규칙을 따르는 유효한 grandMA2 명령어 문자열을 구성하는 Python 함수들입니다. 각 함수는 문자열을 반환하는 얇은(thin) 래퍼이며, 네트워크에 절대 접근하지 않습니다.
- MCP Server (
src/server.py) -- 큐 관리, 피처 제어(fixture control), 프리셋, 실행기(executors), 전역 상태(global state), 레이블링, 외관 할당(appearance assignment), 매크로 편집, 대량 큐 작업, 시퀀스 재생, 콘솔 상태 조회, 쇼 파일 관리, 리드백 검증, 뮤직 쇼 워크플로우 및 stdio 전송을 통한 원시 명령어(raw commands)를 포괄하는 101개의 도구를 노출하는 FastMCP 서버입니다. 이 서버는 콘솔에 영구적인 Telnet 연결을 관리하며, 명령어 구성은 빌더 계층(builder layer)에 위임합니다.
- Response Parser (
src/response_parser.py) -- grandMA2 Telnet 출력을 파싱하기 위한 순수 함수(pure functions): 표 형식의 List 데이터를 구조화된 딕셔너리(dict)로 변환하고, 검증된 실행 경로에 대한 인라인 Error #NN: REASON 실패(ANSI 제거 포함)를 처리합니다.
- Execution Core (
src/execution.py) -- ExecutionResult와 원시 Telnet 응답을 구조화된 {ok, echo, error_code, error_text, raw}로 변환하는 순수 함수인 build_result()를 포함합니다. 변경 가능한(Mutating) 도구들은 GMA2TelnetClient.execute()를 통해 경로 지정되어 성공을 임의로 생성하는 대신 콘솔의 실제 결과를 보고합니다.
- GMA2Client (
src/gma2_client.py) -- 여러 명령어 빌더 호출을 워크플로우 수준의 메서드로 조합하는 고수준 오케스트레이션 클래스입니다 (예: 전체 큐 리스트 구성, 프리셋과 함께 피처 그룹 설정, 뮤직 쇼용 노래 객체 생성).
- CommandSequence (
src/command_sequence.py) -- 여러 명령어를 순서가 지정된 배치(batch)로 조합하기 위한 빌더 패턴 클래스로, 단일 단위로 미리 보고 실행할 수 있습니다.
명령어 빌더는 카테고리별로 정리된 모든 grandMA2 명령줄 키워드를 다룹니다: 객체 키워드 (fixtures, channels, groups, presets, cues, sequences, executors), 함수 키워드 (store, delete, copy, move, goto, label, assign 및 기타 등등), 그리고 도움말 키워드 (thru, at, +).
기능 (Features)
- 101 MCP 도구 – 큐 관리(store/update/delete/goto, CMD 할당, 타이밍, 대량 작업), 피처 제어(값/속성 설정, programmer 지우기, 고급 선택: next/previous/invert/locate/align/fix), 프리셋 관리(store/apply), 실행기 제어(on/off/go/kill/toggle/release/top, fader, rate/speed, flash/swop/stomp/temp busking), 전역 상태(blackout, highlight), blind/preview 모드, 객체 레이블링, 외관 할당, 복사/이동 및 확장 삭제(group/preset/fixture/show), park/unpark, 매크로 편집, 효과 제어(apply, speed, form, range, phase, width, envelope, seconds, speed group, sync), MAtricks fan effects, show/user 변수, timecode (SMPTE), MIDI 출력(note/control/program), 피처 복제(clone fixtures), 콘솔 상태 조회, 쇼 파일 관리, read-back 검증, 뮤직 쇼 워크플로우, 원시 명령어 실행.
- 검증된 명령어 실행 – grandMA2는 Telnet 응답에 실패를 인라인으로 보고합니다 (
Error #NN: REASON). 변경 도구(Mutating tools)는 검증된 실행 코어(src/execution.py)를 통해 라우팅되며, 이 코어는 응답을 구문 분석하여 콘솔의 실제 결과를 반환하므로, 거부된 명령어에 대해 비서가 잘못된 성공을 받지 않습니다. 다중 명령어 도구는 첫 번째 오류 발생 시 중단됩니다.
- 범위/배치 선택기 – 객체 도구는
src/commands/selector.py에 의해 검증되는 grandMA2 선택 표현식(1 thru 10, 1 + 3 + 5, 1 thru 10 - 4)을 허용하므로, ID별로 반복하는 대신 전체 범위가 단일 호출로 복사/이동됩니다.
- 쇼 인식 이름 해석 –
src/introspection.py는 List Attribute(캐시됨)를 조회하고 친근하며 쇼에 특화된 속성 이름을 해석합니다 (예:
White -> COLORRGB5) 전송 전에 변환하고, 알 수 없는 이름은 제안과 함께 거부합니다.
-
Fixture-profile resolver -- src/profile_resolver.py는 MA2 fixture-type / GDTF XML을 구문 분석하고, 이름 지정된 기능들(open/closed/strobe/random/iris/frost/prism)을 각 fixture-type에 맞는 값으로 해결합니다. 따라서 동일한 논리적 프리셋(예: "Strobe Fast")이 모든 프로파일에서 올바른 DMX 값을 얻게 됩니다.
-
Palette builders -- build_color_palette와 일반화된 build_preset_palette는 단일 호출로 전체 프리셋 팔레트를 생성하며, 여기에는 각 fixture-type 값, Global/Selective 범위, 그리고 유형별 병합(팔레트를 새로운 fixture 그룹에 비파괴적으로 확장)이 포함됩니다.
-
Destructive command safety warnings -- 삭제 도구에는 다운스트림 영향(고아화된 executor 핸들, 손실된 큐 프로그래밍 등)에 대한 정보성 경고가 포함되어 있어, AI 어시스턴트가 확인하기 전에 영향을 이해하는 데 도움을 줍니다.
-
Complete command builder -- 30개 이상의 모듈에 걸쳐 모든 grandMA2 명령줄 키워드를 다루는 350개 이상의 Python 함수가 있으며, 각 함수는 올바르게 형식화된 명령어 문자열을 반환합니다.
-
High-level client -- GMA2Client는 워크플로우 수준의 메서드를 제공합니다: 큐 리스트 구축, 프리셋을 사용한 fixture 그룹 설정, 빠른 루크 프로그래밍, 배치 executor 할당. Telnet 왕복 횟수를 최소화하기 위해 grandMA2의 인라인 명명 구문을 사용합니다.
-
Command chaining -- CommandSequence를 사용하면 여러 명령을 구성하고, 미리 보고, 배치로 실행할 수 있습니다.
-
Resilient Telnet client -- telnetlib3을 기반으로 구축되었으며 자동 로그인, 영구 연결, 연결 상태 확인, 제한된 지수 백오프(exponential backoff)를 사용한 자동 재연결, asyncio.Lock을 통한 명령어 직렬화, 그리고 우아한 종료 기능을 갖추고 있습니다. 콘솔이 재시작되거나 네트워크가 끊어져도 클라이언트는 실패를 감지하고 다음 명령 전에 투명하게 재연결합니다.
-
연결 오류 노출(Connection error surfacing) -- MCP 도구는 연결 실패를 포착하고 처리되지 않은 예외(unhandled exceptions) 대신 사람이 읽을 수 있는 오류 메시지를 반환합니다. 따라서 AI 어시스턴트는 명령이 콘솔에 도달하지 않았음을 알 수 있습니다.
-
구성 가능한 전송 방식(Configurable transport) -- stdio (기본값, 단일 클라이언트)와 streamable-http (다중 클라이언트, 웹 기반 접근) 전송 방식을 지원합니다. HTTP 호스트 및 포트는 환경 변수를 통해 구성할 수 있습니다.
-
환경을 통한 구성(Configurable via environment) -- 호스트, 포트, 사용자 이름, 비밀번호 및 전송 설정은 .env 또는 환경 변수를 통해 설정됩니다.
시작하기 (Getting Started)
필수 조건 (Prerequisites)
- Python >= 3.12
- Telnet 접근이 활성화된 grandMA2 콘솔(또는 onPC)
- uv (권장) 또는 pip
macOS의 경우, 수동 테스트를 위한 Telnet 클라이언트가 필요할 때:
설치 (Installation)
git clone <repository-url>
cd gma2-mcp
uv 사용 시:
pip 사용 시:
python -m venv .venv
source .venv/bin/activate
pip install -e .
구성 (Configuration)
템플릿을 복사하여 콘솔 세부 정보를 채우세요:
| 변수명 | 설명 | 기본값 |
|---|
GMA_HOST | grandMA2 onPC의 IP 주소 | 127.0.0.1 |
| ... | | |
GMA_HOST는 grandMA2 onPC가 실행되는 머신의 IP 주소로 설정해야 합니다. 이 정보는 onPC 네트워크 설정 또는 해당 머신의 네트워크 구성을 확인하여 찾을 수 있습니다.
포트 30000은 표준 명령 포트입니다. 포트 30001은 읽기 전용(로그 출력)입니다.
웹 기반 또는 다중 클라이언트 접근을 위해 HTTP 전송 방식을 활성화하려면:
MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=3000
streamable-http를 사용할 때, grandMA2 콘솔이 명령을 순차적으로 처리하기 때문에, 내부 잠금(internal lock)을 통해 여러 클라이언트의 동시 명령은 자동으로 직렬화되어 (serialized) Telnet 명령이 뒤섞이는 것을 방지합니다.
MCP 등록
서버를 MCP 클라이언트 구성에 추가합니다.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"gma2": {
...
uv 없이 사용 시 -- 가상 환경(virtualenv) Python에 직접 포인팅합니다:
{
"mcpServers": {
"gma2": {
...
Claude Code (CLI / IDE 확장 기능)
Claude Code는 Claude Desktop과 별도로 자체 구성 파일을 통해 MCP 서버를 관리합니다. CLI 명령을 사용하거나 설정 파일을 직접 편집하여 설정할 수 있습니다.
옵션 1: claude mcp add 명령어 사용 (권장)
터미널에서 다음 명령을 실행합니다:
claude mcp add gma2 \
-e GMA_HOST=2.0.0.1 \
-e GMA_USER=administrator \
...
이 명령은 MCP 서버를 Claude Code에 등록합니다. -e 플래그는 서버가 시작 시 읽는 환경 변수(environment variables)를 설정합니다. /path/to/gma2-mcp를 클론한 저장소의 실제 경로로 대체하고, GMA_HOST, GMA_USER, GMA_PASSWORD 값을 콘솔에 맞게 조정하십시오.
서버를 전역(global)이 아닌 특정 프로젝트에만 등록하려면, -s project 플래그를 추가합니다:
claude mcp add gma2 -s project \
-e GMA_HOST=2.0.0.1 \
-e GMA_USER=administrator \
...
옵션 2: 설정 파일 수동 편집
서버 항목을 Claude Code 설정 파일에 추가합니다. 파일 위치는 범위(scope)에 따라 다릅니다:
- 사용자 레벨 (모든 프로젝트에서 사용 가능):
~/.claude/settings.json
- 프로젝트 레벨 (현재 프로젝트에서만 사용 가능): 프로젝트 루트의
.claude/settings.json
{
"mcpServers": {
"gma2": {
...
설정 확인
서버를 등록한 후, 작동하는지 확인합니다:
claude mcp list
...
새로운 Claude Code 세션을 시작하면 서버가 자동으로 시작됩니다. Claude에게 MCP 도구를 나열해 달라고 요청하거나 grandMA2 작업을 직접 요청하여 도구가 사용 가능한지 확인할 수 있습니다 (예: "콘솔에서 블랙아웃 토글").
**서버 관리 (Managing the server)**
```bash
claude mcp remove gma2
...
사용법 (Usage)
서버는 101개의 도구를 노출합니다:
| 도구 (Tool) | 설명 (Description) |
|---|
capabilities | 버전, 등록된 도구 및 프로필 스키마 버전을 보고합니다 (계약 표면; 콘솔 연결 없음) |
| ... | |
쿼리 도구는 send_command_with_response()를 사용하여 grandMA2 Telnet 출력을 캡처하고 원시 텍스트로 반환합니다. grandMA2 매뉴얼에는 List 및 Info 응답에 대한 정확한 Telnet 와이어 형식(wire format)이 문서화되어 있지 않기 때문에, 이 도구들은 AI가 직접 해석할 수 있는 처리되지 않은 콘솔 출력을 반환합니다.