La Forge MCP

🚀 LA FORGE MCP

A Model Context Protocol (MCP) server that gives AI coding assistants the visual perception they lack.

🚀 Quick Start

1. Start Chrome and Navigate to Your App

start_chrome("http://localhost:3000")

2. Capture a Reference (When Things Look Right)

capture_reference("homepage", selectors=[".header", ".nav", ".hero", ".footer"])

3. Make Your CSS Changes

Edit your code as normal...

4. Verify Against Reference

verify_against_reference("homepage")

Returns a detailed report:

{
  "passed": false,
  "summary": {
    "match_percentage": 94.2,
    "problem_region_count": 2
  },
  "problem_areas": [{
    "region": {"area": "top-center"},
    "style_differences": [
      {"property": "height", "expected": "64px", "actual": "48px"}
    ],
    "css_rules": [
      {"selector": ".header", "source": "component.css"},
      {"selector": "header", "source": "reset.css"}
    ]
  }],
  "recommendation": "Check problem_areas for CSS rule conflicts."
}

✨ Features

A Model Context Protocol (MCP) server that gives AI coding assistants the visual perception they lack. When AI coding assistants (like Claude Code) work on CSS/HTML, they face several issues:

• They can see the code, but can't truly "see" the rendered result.
• Screenshots are interpreted semantically, not pixel - precisely.
• CSS inheritance and cascade can cause unexpected results invisible in source code.
• A black screen might be reported as "looks good" because there's nothing to semantically parse.

The solution provided by this MCP server includes:

┌─ VISOR ONLINE ──────────────────────────────────────────────────────────┐
│                                                                         │
│  ◉ Pixel - level diffing         Catches ANY visual difference           │
│  ◉ Computed style extraction   See what CSS is ACTUALLY applied        │
│  ◉ CSS rule chain analysis     Find which rules override your styles   │
│  ◉ Problem region detection    Automatically identify differing areas  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

📦 Installation

One - Liner (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/MonomythDevelopment/la - forge - mcp/main/install - remote.sh | bash

One - Liner (Windows PowerShell)

irm https://raw.githubusercontent.com/MonomythDevelopment/la - forge - mcp/main/install - remote.ps1 | iex

Manual Install

# Clone the repo
git clone https://github.com/MonomythDevelopment/la - forge - mcp.git ~/.la - forge - mcp
cd ~/.la - forge - mcp

# Run installer
chmod +x install.sh
./install.sh

💻 Usage Examples

Example Debugging Session

User: "The header height seems wrong after my changes"

Claude: Let me check what's happening.

> verify_against_reference("homepage")
{
  "passed": false,
  "problem_areas": [{
    "style_differences": [
      {"property": "height", "expected": "64px", "actual": "48px"}
    ],
    "css_rules": [
      {"selector": ".main - header", "source": "header.css", "styles": "height: 64px"},
      {"selector": "header", "source": "reset.css", "styles": "height: auto"}
    ]
  }]
}

Claude: Found it! Your reset.css has `header { height: auto }` which is 
overriding `.main - header { height: 64px }`. The reset rule appears later 
in the cascade.

Fix options:
1. Increase specificity: `header.main - header { height: 64px }`
2. Use !important: `.main - header { height: 64px !important }`
3. Reorder stylesheet imports

Black Screen Detection

The quick_visual_check() tool programmatically detects rendering issues:

{
  "healthy": false,
  "issues": [
    "Screen appears black/very dark",
    "Page has no visible text content"
  ],
  "metrics": {
    "mean_brightness": 2.3,
    "std_deviation": 1.1
  }
}

📚 Documentation

Available Tools

Chrome Management

Reference Management

Visual Verification

Element Analysis

CLAUDE.md Integration

For best results, add the snippet from CLAUDE_SNIPPET.md to your user - level CLAUDE.md:

# Find your Claude config location
claude config get

# Append the snippet
cat CLAUDE_SNIPPET.md >> ~/.claude/CLAUDE.md

This teaches Claude Code when and how to use the visual debugging tools automatically.

Configuration

Environment Variables

Setting Chrome Path

If Chrome isn't auto - detected:

# macOS
export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Linux  
export CHROME_PATH="/usr/bin/google-chrome"

# Windows
set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

How It Works

Pixel Diffing

Uses sharp to compare images pixel - by - pixel. Outputs a diff image with mismatched areas highlighted in magenta. Connected components analysis identifies distinct problem regions.

Computed Style Extraction

Uses Chrome DevTools Protocol to query window.getComputedStyle() for any element. Shows the actual applied values after CSS cascade, not just source file values.

CSS Rule Chain

Iterates through all stylesheets via CDP to find every rule matching an element. Shows source file, selector, and styles. Reveals which rule is "winning" for each property.

Troubleshooting

Server won't start

# Test directly
node ~/.la - forge - mcp/dist/index.js

# Should hang waiting for input (Ctrl+C to exit)
# If errors appear, check Node version and run npm install

"Chrome not found"

Set CHROME_PATH environment variable or pass chrome_path to start_chrome().

"No Chrome instance found"

Start Chrome manually with debugging:

google - chrome --remote - debugging - port=9222

Or use start_chrome() tool which does this automatically.

Module import errors

Reinstall and rebuild:

cd ~/.la - forge - mcp
npm install
npm run build

Claude Code shows "Failed to connect"

1. Check registration: claude mcp get la - forge
2. Test server manually (see above)
3. Remove and re - add:

claude mcp remove la - forge - s user
claude mcp add la - forge node ~/.la - forge - mcp/dist/index.js - s user

Development

# Clone
git clone https://github.com/MonomythDevelopment/la - forge - mcp.git
cd la - forge - mcp

# Install deps
npm install

# Development (with hot reload)
npm run dev

# Build
npm run build

# Run built version
npm start

Uninstall

# Remove from Claude Code
claude mcp remove la - forge - s user

# Remove files
rm -rf ~/.la - forge - mcp

📄 License

MIT — see LICENSE