Visual Loop MCP Server

<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 -->

<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 • 📖 Documentation • 🔧 Configuration • 🤖 Claude Desktop • 📡 API 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">

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

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

2️⃣ Install & Build

# 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>

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

</details>

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

$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

{
  "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:

{
  "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

# 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 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

<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>    <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>    <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>