# RenderBuddy MCP — AI-Connected Render Agent & Gateway

> *"Your Blender render, one message away."*  
> Version: **v3.0.1** | Status: **Production Ready** | Tests: **59/59 Passed (100%)**

---

## 🎨 What is RenderBuddy?

**RenderBuddy** is an open-source, AI-connected render agent and gateway platform for **Blender 3.6+ and 5.1+**. It allows 3D artists, studio teams, and developers to monitor and control long Blender render jobs using **natural language** — via AI assistants (Antigravity, Claude, Cursor), a real-time Web Dashboard, or a Telegram Mobile Bot.

---

## ✨ Features at a Glance

* 🟢 **Native Blender Add-on (v3.0.1)**: Runs inside Blender with `@persistent` render handlers and an N-Panel control panel.
* 🤖 **MCP Server (8 Tools)**: Exposes status, frame preview, settings, email dispatch, local upload, render cancellation, and system shutdown tools to AI clients over stdio.
* 📊 **Glassmorphism Web Dashboard**: Live telemetry monitoring completion percentage, frame count, elapsed time, and engine stats in real time.
* 📱 **Telegram Bot Integration**: Monitor progress, request live frame previews (`/preview`), or cancel renders (`/cancel <PIN>`) directly from your phone.
* 🔒 **PIN Security Gate**: Destructive actions (render cancellation and system shutdown) are protected by salted SHA-256 PIN authentication.
* 🚀 **Zero Cloud Dependency**: Pure Python core (stdlib + MCP SDK). No subscription services required.

---

## 🏛️ System Architecture & Gateway Hierarchy

RenderBuddy operates on a decoupled 3-tier architecture:

```
Workstation (Blender + Add-on)
    └─ Loopback TCP (Port 7345) ──► Local Agent (SQLite DB + REST API 7342)
                                        │
                                        ▼
                               Gateway Runner (runner.py)
                                ├── API Interface (Agent HTTP 7342 proxy)
                                ├── Web Dashboard (web_ui.py - Port 8080)
                                ├── Telegram Bot (telegram_bot.py)
                                └── Pairing Service (pairing.py - OTP Manager)
                                        │
                                        ▼
                               Public Internet / Remote Clients
                                (Mobile Web UI / Telegram / MCP / ChatGPT)
```

---

## 🚀 Quick Start Guide

### 1. Build & Install the Blender Add-on
```powershell
python build_addon.py
```
In Blender: **Edit → Preferences → Add-ons → Install from Disk...** → Select `dist/renderbuddy_addon.zip` and enable **RenderBuddy**.

### 2. Configure MCP Client
Add RenderBuddy to your MCP client configuration (`mcp_config.json`):

```json
{
  "mcpServers": {
    "renderbuddy": {
      "command": "python",
      "args": [
        "D:/MCP_RenderBuddy/main.py"
      ]
    }
  }
}
```

### 3. Launch Gateway Services
```powershell
python -m gateway.runner
```

---

## 📚 Complete Documentation Index

For detailed instructions, architecture, presentation guide, and developer documents, consult the full documentation suite:

* 📖 **[Presentation & File Overview Guide](PROJECT_PRESENTATION_GUIDE.md)** — Exhaustive file-by-file catalog, architectural pitch, and live demo script.
* 📖 **[Installation Guide](HOW_TO_INSTALL.md)** — Step-by-step setup, Python environment, ngrok tunnel, and MCP registration.
* 📖 **[Operating Manual](HOW_TO_USE.md)** — N-Panel controls, OTP pairing, Web UI, Telegram bot commands, and MCP natural language prompts.
* 📖 **[Deployment Topology & Diagrams](DEPLOYMENT.md)** — End-to-end network deployment, security boundaries, and 4 complete UML sequence diagrams.
* 📖 **[Architecture Specification](ARCHITECTURE.md)** — Technical design, SQLite schema, event bus, and PIN authorization gates.
* 📖 **[What Was Built](WHAT_WAS_BUILT.md)** — Milestone summary, version evolution, and file map.

---

## 🧪 Test Suite

RenderBuddy includes a full automated test suite covering configuration, event bus, SQLite projections, security gates, and tool handlers.

```powershell
python -m pytest -v
```
```
59 tests collected — 59 passed in ~1.3s
```

---

## 📜 License

RenderBuddy is released under the **MIT License**. Open-source for artists, studios, and developers worldwide.