Skip to main content
Glama
Sign In
Visual Loop MCP Server

Visual Loop MCP Server

by IqbalHere
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

MCP Protocol TypeScript Playwright Judge0 License: MIT Node.js

🚀 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 asgiving your AI eyes — it can now verify layouts, catch visual bugs, and iterate on designs without human intervention.

Related MCP server: Secure Grid Genesis Execution

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

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

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

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

Available Tools

1 tool
execute_and_renderA

Execute source code via Codebox (Judge0) for logic validation and render it as HTML in a headless browser via Playwright, returning the console output and a screenshot. Use this to write full-stack UI code and instantly verify both its logic and visual appearance.

Inputs: language_id (required), source_code (required), viewport_width, viewport_height.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of ambiguity or confusion with other tools.

    Naming Consistency5/5

    With a single tool, naming consistency is not a concern; the name 'execute_and_render' clearly describes its function.

    Tool Count3/5

    One tool is on the lower end of reasonable count, but it serves a specific combined purpose of execution and rendering, which may justify the minimal surface.

    Completeness3/5

    The single tool covers both code execution and visual rendering, but lacks separate tools for execution-only or rendering-only tasks, limiting flexibility.

    Resources

    Related MCP Connectors

    Related MCP Servers