<div align="center">

<!-- Animated Header Banner -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:6C63FF,50:A855F7,100:EC4899&height=220&section=header&text=Visual%20Loop%20MCP&fontSize=50&fontColor=FFFFFF&fontAlignY=35&desc=Execute%20%E2%80%A2%20Render%20%E2%80%A2%20Verify&descSize=20&descAlignY=55&animation=fadeIn" width="100%" alt="Visual Loop MCP Header"/>

<br/>

<!-- Badges -->
[![MCP Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-6C63FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg==&logoColor=white)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Playwright](https://img.shields.io/badge/Playwright-1.48+-2EAD33?style=for-the-badge&logo=playwright&logoColor=white)](https://playwright.dev/)
[![Judge0](https://img.shields.io/badge/Judge0-Codebox-E34F26?style=for-the-badge&logo=codepen&logoColor=white)](https://judge0.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-F59E0B?style=for-the-badge)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-≥20.0-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)

<br/>

<p align="center">
  <strong>A production-ready MCP server that combines <em>secure code execution</em> with <em>visual rendering</em> — giving multimodal AI clients the power to write, run, and <em>see</em> code in one seamless loop.</strong>
</p>

<br/>

[🚀 Quick Start](#-quick-start) •
[📖 Documentation](#-how-it-works) •
[🔧 Configuration](#-configuration) •
[🤖 Claude Desktop](#-claude-desktop-integration) •
[📡 API Reference](#-tool-reference)

<br/>

---

</div>

## ✨ Why Visual Loop?

Most AI coding assistants can *write* code — but they can't *see* the result. **Visual Loop MCP** closes that gap by providing a single tool that:

<table>
<tr>
<td width="60" align="center">⚡</td>
<td><strong>Executes code securely</strong> via Judge0/Codebox sandboxed runtime</td>
</tr>
<tr>
<td align="center">🖼️</td>
<td><strong>Renders visual output</strong> using Playwright headless Chromium</td>
</tr>
<tr>
<td align="center">📸</td>
<td><strong>Returns screenshots</strong> alongside console output in a single multimodal response</td>
</tr>
<tr>
<td align="center">🔄</td>
<td><strong>Enables iterative UI development</strong> — AI sees its own output and self-corrects</td>
</tr>
</table>

> [!TIP]
> Think of it as **giving your AI eyes** — it can now verify layouts, catch visual bugs, and iterate on designs without human intervention.

---

## 🏗️ Architecture

```
                    ┌──────────────────────────────┐
                    │        AI Client             │
                    │   (Claude Desktop / Cursor)  │
                    └──────────────┬───────────────┘
                                   │
                          stdio (JSON-RPC 2.0)
                                   │
                    ┌──────────────▼───────────────┐
                    │    Visual Loop MCP Server     │
                    │                               │
                    │   ┌───────────────────────┐   │
                    │   │   Phase A: Execute     │   │     ┌──────────────────┐
                    │   │   Code Validation      │───┼────▶│  Judge0/Codebox   │
                    │   │                        │   │     │  (Sandboxed API)  │
                    │   └───────────────────────┘   │     └──────────────────┘
                    │                               │
                    │   ┌───────────────────────┐   │
                    │   │   Phase B: Render      │   │     ┌──────────────────┐
                    │   │   Visual Screenshot    │───┼────▶│  Playwright       │
                    │   │                        │   │     │  (Headless Chrome) │
                    │   └───────────────────────┘   │     └──────────────────┘
                    │                               │
                    │   ┌───────────────────────┐   │
                    │   │   Phase C: Cleanup     │   │     Temp files removed
                    │   │   Resource Disposal    │   │     Browser closed
                    │   └───────────────────────┘   │
                    │                               │
                    └───────────────────────────────┘
```

<div align="center">

```mermaid
graph LR
    A[🤖 AI Client] -->|stdio JSON-RPC| B[🔄 Visual Loop MCP]
    B -->|POST /submissions| C[⚡ Judge0 Codebox]
    B -->|file:// render| D[🌐 Playwright]
    C -->|stdout / stderr| B
    D -->|base64 PNG| B
    B -->|multimodal response| A

    style A fill:#6C63FF,stroke:#4F46E5,color:#fff,stroke-width:2px
    style B fill:#A855F7,stroke:#9333EA,color:#fff,stroke-width:2px
    style C fill:#F59E0B,stroke:#D97706,color:#fff,stroke-width:2px
    style D fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
```

</div>

---

## 📦 Prerequisites

| Requirement | Version | Purpose |
|:---:|:---:|:---|
| <img src="https://img.shields.io/badge/-Node.js-339933?logo=node.js&logoColor=white&style=flat-square" /> | `≥ 20.0` | Runtime environment |
| <img src="https://img.shields.io/badge/-npm-CB3837?logo=npm&logoColor=white&style=flat-square" /> | `≥ 10.0` | Package management |
| <img src="https://img.shields.io/badge/-Docker-2496ED?logo=docker&logoColor=white&style=flat-square" /> | Any | Judge0 container hosting |

---

## 🚀 Quick Start

### 1️⃣ Start the Judge0 Sandbox

```bash
# Pull and run Judge0 CE in Docker
docker run -d -p 2358:2358 --name judge0 judge0/judge0-ce
```

### 2️⃣ Install & Build

```bash
# Clone the repository
git clone https://github.com/IqbalHere/-Visual-Loop-MCP-Server.git
cd -Visual-Loop-MCP-Server

# Install dependencies
npm install

# Install Playwright Chromium (minimal footprint)
npx playwright install chromium

# Build the TypeScript project
npm run build
```

### 3️⃣ Run the Server

<details>
<summary><strong>🐧 macOS / Linux</strong></summary>

```bash
CODEBOX_URL=http://localhost:2358 CODEBOX_TOKEN=your_token npm start
```

</details>

<details>
<summary><strong>🪟 Windows (PowerShell)</strong></summary>

```powershell
$env:CODEBOX_URL = "http://localhost:2358"
$env:CODEBOX_TOKEN = "your_token"
npm start
```

</details>

---

## 🔧 Configuration

| Variable | Required | Description |
|:---|:---:|:---|
| `CODEBOX_URL` | ✅ | Base URL of your Judge0/Codebox instance |
| `CODEBOX_TOKEN` | ❌ | Auth token for the Codebox API *(omit if no auth)* |

> [!NOTE]
> If `CODEBOX_URL` is unset, the server gracefully skips code execution and only performs visual rendering. No crash, no fuss.

---

## 🤖 Claude Desktop Integration

Add this to your Claude Desktop configuration file:

| Platform | Config Path |
|:---|:---|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |

```jsonc
{
  "mcpServers": {
    "visual-loop": {
      "command": "node",
      "args": ["C:/absolute/path/to/visual-loop-mcp/build/index.js"],
      "env": {
        "CODEBOX_URL": "http://localhost:2358",
        "CODEBOX_TOKEN": "your_token_here"   // optional
      }
    }
  }
}
```

> [!IMPORTANT]
> Replace the path in `args` with the **absolute path** to your cloned project. Use forward slashes (`/`) even on Windows.

After saving, **restart Claude Desktop**. The `execute_and_render` tool will appear in the tool picker. 🎉

---

## 📡 Tool Reference

### `execute_and_render`

The single, powerful tool exposed by this server.

```
AI writes code  →  Codebox validates logic  →  Playwright renders visuals  →  AI sees the result
```

#### Parameters

| Parameter | Type | Required | Default | Description |
|:---|:---:|:---:|:---:|:---|
| `source_code` | `string` | ✅ | — | Raw HTML/CSS/JS source code to execute and render |
| `language_id` | `number` | ✅ | — | Judge0 language ID (see table below) |
| `viewport_width` | `number` | ❌ | `1280` | Browser viewport width in pixels |
| `viewport_height` | `number` | ❌ | `720` | Browser viewport height in pixels |

#### Response Format

The tool returns a **multimodal MCP content array** containing both text and image:

```json
{
  "content": [
    {
      "type": "text",
      "text": "[Codebox] Status: Accepted (id: 3)\n── stdout ──\nHello, world!\n\nExecution time: 0.012s | Memory: 3456 KB"
    },
    {
      "type": "image",
      "data": "<base64-encoded-PNG-screenshot>",
      "mimeType": "image/png"
    }
  ]
}
```

---

## 🗂️ Supported Languages

| Language | ID | Language | ID |
|:---|:---:|:---|:---:|
| 🟨 JavaScript (Node.js) | `63` | 🐍 Python 3 | `71` |
| 🔷 TypeScript | `74` | ☕ Java | `62` |
| ⚙️ C++ (GCC) | `54` | 💎 Ruby | `72` |
| 🐹 Go | `60` | 🌐 HTML/CSS | `82` |

> [!TIP]
> For a complete list of 60+ supported languages, query your Judge0 instance: `GET /languages`

---

## 🛡️ Error Handling

The server is engineered to **never crash** from tool-level errors. Every failure is caught and returned gracefully:

| Scenario | Behavior |
|:---|:---|
| 🔌 Codebox timeout / network error | Error details in text response; screenshot still attempted |
| 🖥️ Playwright crash | Codebox results returned with rendering error note |
| 💥 Both fail | Descriptive error text returned; no image block |
| ⚠️ Missing `CODEBOX_URL` | Codebox phase skipped with warning; rendering proceeds |

---

## 🧰 Development

```bash
# Build and run in one step
npm run dev

# Watch mode with tsx (great for iterating)
npx tsx watch src/index.ts
```

### Project Structure

```
visual-loop-mcp/
├── 📄 src/
│   └── index.ts          # Main server — Codebox + Playwright + MCP
├── 📁 build/             # Compiled JavaScript output
├── 📦 package.json       # Dependencies & scripts
├── ⚙️ tsconfig.json      # TypeScript configuration
└── 📖 README.md          # You are here!
```

---

## 🛠️ Tech Stack

<div align="center">

| Technology | Role |
|:---:|:---|
| <img src="https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&style=for-the-badge" height="28" /> | Core language with strict type safety |
| <img src="https://img.shields.io/badge/-MCP%20SDK-6C63FF?style=for-the-badge" height="28" /> | Model Context Protocol server framework |
| <img src="https://img.shields.io/badge/-Playwright-2EAD33?logo=playwright&logoColor=white&style=for-the-badge" height="28" /> | Headless browser automation & screenshots |
| <img src="https://img.shields.io/badge/-Judge0-E34F26?style=for-the-badge" height="28" /> | Sandboxed multi-language code execution |
| <img src="https://img.shields.io/badge/-Axios-5A29E4?logo=axios&logoColor=white&style=for-the-badge" height="28" /> | HTTP client for Codebox API |
| <img src="https://img.shields.io/badge/-Zod-3E67B1?logo=zod&logoColor=white&style=for-the-badge" height="28" /> | Runtime schema validation |

</div>

---

## 🤝 Contributing

Contributions are welcome! Here's how to get started:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

---

## 📄 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:6C63FF,50:A855F7,100:EC4899&height=120&section=footer&animation=fadeIn" width="100%" alt="Footer"/>

<br/>

**Built with ❤️ by [Iqbal](https://github.com/IqbalHere)**

<br/>

<a href="https://github.com/IqbalHere/-Visual-Loop-MCP-Server/stargazers">
  <img src="https://img.shields.io/github/stars/IqbalHere/-Visual-Loop-MCP-Server?style=social" alt="GitHub Stars" />
</a>
&nbsp;&nbsp;
<a href="https://github.com/IqbalHere/-Visual-Loop-MCP-Server/network/members">
  <img src="https://img.shields.io/github/forks/IqbalHere/-Visual-Loop-MCP-Server?style=social" alt="GitHub Forks" />
</a>
&nbsp;&nbsp;
<a href="https://github.com/IqbalHere/-Visual-Loop-MCP-Server/issues">
  <img src="https://img.shields.io/github/issues/IqbalHere/-Visual-Loop-MCP-Server?style=social" alt="GitHub Issues" />
</a>

<br/><br/>

⭐ **Star this repo if you found it useful!** ⭐

</div>