Visual Loop Server

MCP Protocol TypeScript Playwright Judge0 License: MIT Node.js

A production-ready MCP server that combines secure code execution with visual rendering — giving multimodal AI clients the power to write, run, and see code in one seamless loop.

🚀 Quick Start • 📖 Documentation • 🔧 Configuration • 🤖 Claude Desktop • 📡 API Reference

---

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

[!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
                    │   └───────────────────────┘   │
                    │                               │
                    └───────────────────────────────┘

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

📦 Prerequisites

Requirement	Version	Purpose
	≥ 20.0	Runtime environment
	≥ 10.0	Package management
	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

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

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

🔧 Configuration

[!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:

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

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

[!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:

🧰 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

Technology	Role
	Core language with strict type safety
	Model Context Protocol server framework
	Headless browser automation & screenshots
	Sandboxed multi-language code execution
	HTTP client for Codebox API
	Runtime schema validation

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

Built with ❤️ by Iqbal

     

⭐ Star this repo if you found it useful! ⭐