GitHub - MonomythDevelopment/la-forge-mcp: Visual CSS debugging for AI coding assistants — an MCP server for pixel-perfect screenshot comparison, computed-style extraction, and CSS rule-chain analysis.

  _             ______
 | |           |  ____|
 | |     __ _  | |__ ___  _ __ __ _  ___
 | |    / _` | |  __/ _ \| '__/ _` |/ _ \
 | |___| (_| | | | | (_) | | | (_| |  __/
 |______\__,_| |_|  \___/|_|  \__, |\___|
                               __/ |
                              |___/   MCP

░▒▓█ A PIXEL PERFECT VISOR FOR AI CODING ASSISTANTS █▓▒░

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

The Problem

When AI coding assistants (like Claude Code) work on CSS/HTML:

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

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

Quick Install

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

Requirements

Node.js 18+
Claude Code CLI (claude command)
Google Chrome or Chromium

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."
}

Available Tools

Chrome Management

Tool	Description
`start_chrome(url, port, headless)`	Start Chrome with debugging enabled
`navigate(url)`	Navigate to a URL
`check_connection()`	Verify Chrome connection status

Reference Management

Tool	Description
`capture_reference(name, selectors, full_page)`	Save screenshot + computed styles as reference
`list_references()`	List all saved references

Visual Verification

Tool	Description
`verify_against_reference(name, threshold)`	Main tool — Compare current state against reference
`quick_visual_check(url)`	Quick sanity check for black screens, loading states

Element Analysis

Tool	Description
`get_element_debug_info(selector)`	Deep dive on element's computed styles + rule chain
`compare_elements(selector, expected)`	Compare element against expected style values
`screenshot_element(selector)`	Screenshot a single element

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

No more "looks good" on a black screen!

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

Variable	Description	Default
`CHROME_PATH`	Path to Chrome executable	Auto-detected
`CHROME_DEBUG_PORT`	Port for Chrome debugging	9222

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"

Check registration: claude mcp get la-forge
Test server manually (see above)

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

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║                               LA FORGE MCP                                ║
║                                                                           ║
║          ░▒▓█ A PIXEL PERFECT VISOR FOR AI CODING ASSISTANTS █▓▒░         ║
║                                                                           ║
║                    Made with ◉ by Monomyth Development                    ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.idea		.idea
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLAUDE_SNIPPET.md		CLAUDE_SNIPPET.md
LICENSE		LICENSE
README.md		README.md
install-remote.ps1		install-remote.ps1
install-remote.sh		install-remote.sh
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

The Problem

The Solution

Quick Install

One-Liner (macOS/Linux)

One-Liner (Windows PowerShell)

Manual Install

Requirements

Quick Start

1. Start Chrome and Navigate to Your App

2. Capture a Reference (When Things Look Right)

3. Make Your CSS Changes

4. Verify Against Reference

Available Tools

Chrome Management

Reference Management

Visual Verification

Element Analysis

Example Debugging Session

Black Screen Detection

CLAUDE.md Integration

Configuration

Environment Variables

Setting Chrome Path

How It Works

Pixel Diffing

Computed Style Extraction

CSS Rule Chain

Troubleshooting

Server won't start

"Chrome not found"

"No Chrome instance found"

Module import errors

Claude Code shows "Failed to connect"

Development

Uninstall

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages