<div align="center">

<img src="assets/avatar.png" alt="Xuân Văn 97 (Maka) - grandMA2 MCP Server" width="130" height="130" style="border-radius: 50%; object-fit: cover; border: 3px solid #FF6B00; box-shadow: 0 4px 16px rgba(255, 107, 0, 0.4); margin-bottom: 8px;" />

# 🎭 grandMA2 Universal MCP Server
### *AI-Powered Stage Lighting Control Bridge via Model Context Protocol*

**Author: Xuân Văn 97 (Maka) — Minh Toan Event Company (Hai Phong, Vietnam)**  
*Contact Email:* `makadino97@gmail.com`

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![grandMA2](https://img.shields.io/badge/grandMA2-onPC%203.2--3.9%2B-FF6B00)](https://www.malighting.com/)
[![Protocol](https://img.shields.io/badge/Protocol-MCP%202.x-00C853)](https://modelcontextprotocol.io/)
[![Unit Tests](https://img.shields.io/badge/E2E%20Tests-100%25%20Passed-brightgreen)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-FBC02D.svg)](LICENSE)
[![Company](https://img.shields.io/badge/Company-Minh%20Toan%20Event%20Hai%20Phong-8E24AA)](#-author--organization)

**[🇻🇳 Tiếng Việt](README.vi.md) • [🇬🇧 English](README.md) • [📖 Full A-Z Manual (VI)](HUONG_DAN_KET_NOI_CHI_TIET.md) • [🛠️ Instant Doctor](#-instant-troubleshooting--connection-doctor)**

</div>

---

## 🌟 Overview

The **grandMA2 Universal MCP Server** is a lighting control bridge that directly connects modern AI Agents (including **Google Antigravity IDE, Claude Desktop, OpenAI Codex CLI, Cursor, Windsurf, VS Code, Dola AI, Doubao, and ChatGPT Custom GPTs**) to **grandMA2 (onPC or physical consoles)** using the **Model Context Protocol (MCP)**.

Engineered and battle-tested in live concert environments by **Xuân Văn 97 (Staff at Minh Toan Event Company, Hai Phong, Vietnam)**, this server eliminates unnecessary clutter, delivering sub-millisecond command execution and production-grade reliability for live stage performances.

---

## 🗺️ System Architecture

```mermaid
flowchart LR
    subgraph AI ["🤖 AI Agents"]
        A1["Antigravity / Codex / Claude / Cursor"]
        A2["Dola AI / Doubao / Custom GPT"]
    end

    subgraph MCP ["⚡ MCP Server (Pure Python)"]
        S1["grandma2_mcp_server.py\n(Transport: stdio)"]
        S2["ma2_mcp_http_server.py\n(Transport: HTTP/SSE /mcp)"]
        DOC["check_connection.py\n(Automated Diagnostic Doctor)"]
    end

    subgraph GMA2 ["🎭 grandMA2 Console"]
        NET["Telnet Port 30000\n(Global Settings = Enabled)"]
        ENG["grandMA2 Command Engine"]
        DMX["DMX 512 / Art-Net / sACN Output"]
        LIGHT["💡 Stage Fixtures & grandMA 3D"]
    end

    A1 ==>|JSON-RPC stdio| S1
    A2 ==>|HTTP POST/SSE| S2
    S1 ==>|Async Telnet Socket| NET
    S2 ==>|Async Telnet Socket| NET
    NET --> ENG --> DMX --> LIGHT
```

---

## 🚀 Quick Start in 3 Steps

### Step 1: Install Python dependencies
```bash
pip install -r requirements.txt
```

### Step 2: Enable Telnet in grandMA2 onPC / Console
1. Launch **grandMA2 onPC** (or power on your physical console).
2. Go to: **Setup** $\rightarrow$ **Console** column $\rightarrow$ **Global Settings**.
3. Toggle **Telnet** to **`Enabled`** (Default Port: `30000`, User: `administrator`, Pass: `admin`).

### Step 3: Run the Server

| Mode | For AI Clients | Command |
| :--- | :--- | :--- |
| **Mode A (stdio)** | Antigravity IDE, Claude Desktop, Codex, Cursor | `python grandma2_mcp_server.py`<br>*(or launch `run_ma2_mcp.bat`)* |
| **Mode B (HTTP)** | Dola AI, Doubao, Cici, ChatGPT Custom GPTs | `python ma2_mcp_http_server.py`<br>*(or launch `run_dola_ma2_mcp.bat`)* |

> [!TIP]
> **Connecting Physical grandMA2 Consoles**: Connect an Ethernet cable to `eth0` on your console, set a static IP on the console (e.g. private LAN `192.168.x.x`), enable Telnet in `Global Settings`, and set the environment variable `GMA2_HOST=[MA2_CONSOLE_IP]` on your AI host computer. The setup operates over an isolated, private LAN, air-gapped from the Internet to guarantee 100% security and anti-tamper protection. See [HUONG_DAN_KET_NOI_CHI_TIET.md](HUONG_DAN_KET_NOI_CHI_TIET.md#%EF%B8%8F-ph%E1%BA%A7n-2-h%C6%B0%E1%BB%9Bng-d%E1%BA%ABn-k%E1%BA%BFt-n%E1%BB%91i-b%C3%A0n-grandma2-th%E1%BA%ADt-console-v%E1%BA%ADt-l%C3%BD--onpc-qua-m%E1%BA%A1ng-lan).

---

## 🛠️ Instant Troubleshooting & Connection Doctor

Experiencing connection difficulties or fixtures not responding? Run the built-in diagnostic doctor:

```bash
python check_connection.py
```

> [!TIP]
> This tool scans the Telnet port 30000, performs a handshake authentication test, and verifies the HTTP server status on port 8000, outputting precise actionable steps if any component is offline.

👉 **For comprehensive troubleshooting diagrams and error resolution trees, see:** [HUONG_DAN_KET_NOI_CHI_TIET.md](HUONG_DAN_KET_NOI_CHI_TIET.md).

---

## 🌟 Everything AI Can Do On grandMA2

Connected through the Model Context Protocol (MCP), AI Agents operate as an end-to-end **Virtual Lighting Programmer & Stage Operator**:

| Domain | What AI Can Do On grandMA2 | Example AI Commands |
| :--- | :--- | :--- |
| **1. 💡 Live Fixture & Attribute Control** | • Dimmer 0–100%, Strobe Pulse, Random Strobe.<br>• RGB/CMY color mixing, portrait CTO/CTB color temperature.<br>• Pan/Tilt 540°/270°, automatic Fanning & fan symmetry.<br>• Gobo wheel 1/2 selection, Prism rotation, Frost/Zoom/Iris.<br>• Remote Lamp On/Off, motor reset for jammed fixtures. | *"Set Fixtures 1 Thru 10 to Red, 80% dimmer, 30-degree fan out, light strobe"* |
| **2. 🎬 Professional Show & Cue Programming** | • Store new Cues, Merge parameters, Update existing Cues.<br>• Discrete Fade/Delay timing per attribute (Dimmer 1s, Color 3s).<br>• Manage Sequences, assign to Executor Faders, Go, Pause, Off, Top.<br>• **Blind Mode**: Program unseen backstage cues directly during live shows without changing current stage output. | *"In Blind mode, program Chorus cue with 2.5s fade and assign to Executor 1"* |
| **3. 🎨 Preset Pool & Resource Management** | • Manage all 9 standard Pools: Dimmer, Position, Gobo, Color, Beam, Focus, Control, Shapers, Video.<br>• Create Groups (Odd/Even selection, Wings symmetry, Invert selection).<br>• Create Worlds to isolate stage zones and apply safety attribute Filters. | *"Create an Odd Fixtures Group and assign Cyan Color preset"* |
| **4. ⚡ Macro Engine & Stage Automation** | • Auto-generate and inject multi-line complex Macros into the MA2 Pool.<br>• Timecode timeline sync (SMPTE / MIDI Timecode / LTC) aligned with audio.<br>• Agenda scheduling for automated venue/theater runs. | *"Generate Macro 150 to warm up fixtures and check all channels on boot"* |
| **5. 🧠 Musical Intelligence & Stage Design** | • Analyze song structure (Intro, Verse, Chorus, Drop, Bridge, Outro) and auto-generate matching Cue Lists.<br>• Calculate BPM to dynamically adapt Speed Masters and chaser rates.<br>• Recommend cinematic color palettes: Cyberpunk, Acoustic Warm, Dark Rock, Dreamy. | *"Analyze this track lyrics and design a 5-cue sequence matching song emotions"* |
| **6. 🛡️ Live Stage Emergency & System Admin** | • Instant Programmer rescue (`ClearAll`), undo mistakes (`Oops`).<br>• Isolate and lock broken/overheating fixtures during show (`Park Fixture`).<br>• Highlight & Solo for truss technicians focusing beams.<br>• Automated showfile backup (`SaveShow`, `SaveShowAs`). | *"Fixture 12 motor is stuck, immediately park it at 0 without stopping the show"* |
| **7. 🎓 Interactive MA2 CLI Tutor & Coach** | • Instant lookup for grandMA2 syntax with real-world examples.<br>• Pre-flight syntax validation before sending commands to console.<br>• Guided onboarding for new lighting technicians. | *"How do I create a smooth rainbow color chaser across 20 par LEDs?"* |

---

## 🔌 Ready-to-Use Configs for AI Clients

### 1. Google Antigravity IDE / Cursor / VS Code
Add to `.agents/mcp_config.json` or `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "grandma2": {
      "command": "python",
      "args": ["C:/path/to/grandma2-mcp-server/grandma2_mcp_server.py"],
      "env": {
        "GMA2_HOST": "127.0.0.1",
        "GMA2_PORT": "30000"
      }
    }
  }
}
```

### 2. Claude Desktop
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "grandma2": {
      "command": "python",
      "args": ["C:\\path\\to\\grandma2-mcp-server\\grandma2_mcp_server.py"]
    }
  }
}
```

### 3. Dola AI / Doubao
1. Run `run_dola_ma2_mcp.bat`.
2. Enter the SSE endpoint: `http://127.0.0.1:8000/mcp`.

---

## 📁 Repository Structure

```
grandma2-mcp-server/
├── check_connection.py         # 1-Click automated connection doctor & diagnostic tool
├── grandma2_mcp_server.py      # Standard stdio MCP Server (Antigravity, Claude, Codex, Cursor)
├── ma2_mcp_http_server.py      # HTTP / REST MCP Server (Dola AI, Doubao, Custom GPT)
├── xv97_lighting_bridge.py     # Protected lighting bridge with obfuscated credentials
├── configs/                    # Ready-to-use configuration templates for each AI tool
├── HUONG_DAN_KET_NOI_CHI_TIET.md # Master manual with architectural flows & troubleshooting (VI)
├── run_ma2_mcp.bat             # Fast Windows launcher (stdio)
├── run_dola_ma2_mcp.bat        # Fast Windows launcher (HTTP)
├── requirements.txt            # Required Python libraries
├── README.md                   # English Documentation
└── README.vi.md                # Vietnamese Documentation
```

---

## 👤 Author & Organization

**Xuân Văn 97 (Maka)**
- **Affiliation**: Technical Staff — **Minh Toan Event Company (Công ty Sự kiện Minh Toán Hải Phòng)**
- **Email**: `makadino97@gmail.com`
- **Repository**: [https://github.com/vandiy064-byte/grandma2-mcp-server](https://github.com/vandiy064-byte/grandma2-mcp-server)
- **Base of Operations**: Hai Phong, Vietnam

<div align="center">
  <br>
  <img src="assets/avatar.png" alt="Maka (Xuân Văn 97)" width="120" height="120" style="border-radius: 50%; object-fit: cover; border: 3px solid #8E24AA; box-shadow: 0 4px 12px rgba(142, 36, 170, 0.35); margin-bottom: 12px;" />
  <br>
  <img src="assets/zalo_contact_qr.png" alt="Zalo Contact Card - Maka (Xuân Văn 97)" width="280" style="border-radius: 12px; box-shadow: 0 4px 14px rgba(0,0,0,0.2);" />
  <p><b>Maka (Xuân Văn 97) — Scan QR to connect via Zalo for technical exchange & support</b></p>
</div>

---

## 📄 License

Distributed under the **MIT License**. Free for commercial and private stage productions.  
Copyright (c) 2026 **Xuân Văn 97** (Minh Toan Event Company).

---

## 🙏 Acknowledgments

Developed and maintained by **Xuân Văn 97** with practical field experience from productions at **Minh Toan Event Company (Hai Phong)**.  
If this project supports your live productions, please give it a ⭐ on GitHub! 🙌