UI Analyzer MCP Server

An MCP (Model Context Protocol) server that analyzes website UIs and provides precise fix instructions for AI coding assistants. Designed to solve the problem of "messy UI updates" when using agentic code IDEs like GitHub Copilot or Cursor.

Features

Live UI Analysis - Renders and inspects actual websites using Playwright
Smart Query Interpretation - Understands vague complaints like "navbar is broken"
Precise Fix Instructions - Generates specific CSS selectors and property changes
Technology Detection - Identifies React, Vue, Angular, Next.js, Tailwind, Bootstrap, and more
Responsive Testing - Compare UIs across mobile, tablet, and desktop viewports
Accessibility Analysis - Extracts accessibility tree for semantic understanding

The Problem

When using AI coding assistants to build or update website UIs, the results can sometimes be messy:

Layout breaks unexpectedly
Elements overlap or misalign
Spacing becomes inconsistent
Responsive design breaks

Users often struggle to describe exactly what's wrong, saying things like "the navbar is broken" or "the hero section looks weird" - vague descriptions that don't help the AI understand what specific CSS or HTML changes are needed.

The Solution

This MCP server bridges that gap by:

Analyzing the live website - Using Playwright to render and inspect the actual UI
Detecting technology stack - Identifying frameworks (React, Next.js, Vue) and CSS libraries (Tailwind, Bootstrap)
Identifying UI elements - Finding navbars, headers, footers, heroes, buttons, forms, etc.
Detecting issues - Spotting layout problems, overflow, z-index conflicts, accessibility issues
Interpreting vague queries - Understanding what "the header is messed up" actually means
Generating framework-aware fix instructions - Providing specific CSS selectors, property changes, and code snippets tailored to the detected tech stack

Installation

Prerequisites

Python 3.13 or higher
uv package manager

Setup

# Clone the repository
git clone https://github.com/0x-Professor/UIAnalyzerMCP.git
cd UIAnalyzerMCP

# Install dependencies
uv sync

# Install Playwright browsers
uv run playwright install chromium

Usage

Running the Server

# Run directly
uv run python server.py

# Or use the MCP CLI
uv run mcp run server.py

# For development with inspector
uv run mcp dev server.py

VS Code / GitHub Copilot Configuration

Add to your VS Code settings.json or MCP configuration:

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/UIAnalyzerMCP"
    }
  }
}

Cursor IDE Configuration

Add to your Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/UIAnalyzerMCP"
    }
  }
}

Claude Desktop Configuration

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "C:\\path\\to\\UIAnalyzerMCP"
    }
  }
}

Available Tools (8 Total)

| Tool | Description | |------|-------------| | analyze_page | Full UI analysis with elements, issues, and screenshot | | get_fix_instructions | Generate precise fix instructions from vague complaints | | get_screenshot | Capture screenshots with optional element highlighting | | get_element_details | Get detailed info about specific element types | | get_accessibility_snapshot | Extract accessibility tree in YAML format | | get_dom_overview | Get simplified DOM structure overview | | compare_viewports | Compare UI at mobile, tablet, and desktop sizes | | get_tech_stack | Detect frameworks, libraries, and CSS approach |

analyze_page

Full UI analysis of a webpage. Returns elements, issues, accessibility tree, DOM structure, and screenshot.

analyze_page(url="http://localhost:3000", query="the navbar is broken")

get_fix_instructions

The main tool for fixing messy UIs. Interprets vague user complaints and generates precise fix instructions.

get_fix_instructions(
    url="http://localhost:3000",
    user_complaint="the hero section looks weird and buttons are not aligned"
)

Returns:

Interpreted problem description
Affected elements with CSS selectors
Ordered fix instructions with property changes
Complete CSS changes to apply
Additional recommendations

get_screenshot

Capture a screenshot with optional element highlighting.

get_screenshot(url="http://localhost:3000", element_type="navbar")
get_screenshot(url="http://localhost:3000", highlight_selector=".hero-section")

get_element_details

Get detailed information about specific UI element types.

get_element_details(url="http://localhost:3000", element_type="button")

get_accessibility_snapshot

Get the accessibility tree in YAML format for understanding semantic structure.

get_accessibility_snapshot(url="http://localhost:3000")

get_dom_overview

Get a simplified DOM structure overview.

get_dom_overview(url="http://localhost:3000", max_depth=5)

compare_viewports

Compare the UI at different screen sizes to identify responsive issues.

compare_viewports(url="http://localhost:3000")

get_tech_stack

Detect the technology stack (frameworks, libraries, CSS approach) used on a webpage. Returns framework-specific fix guidance.

get_tech_stack(url="http://localhost:3000")

Returns:

Primary framework (React, Vue, Angular, Svelte, etc.)
Meta framework (Next.js, Nuxt, Remix, Gatsby, Astro)
CSS approach (Tailwind, Bootstrap, CSS Modules, styled-components)
UI libraries (shadcn/ui, Material UI, Chakra UI, Ant Design)
Framework-specific fix recommendations

Supported Technology Detection

JavaScript Frameworks

React, Vue, Angular, Svelte, Solid, Preact
jQuery, Alpine.js, HTMX

Meta Frameworks

Next.js, Nuxt, Remix, Gatsby, Astro, SvelteKit, Vite

CSS Frameworks & Libraries

Tailwind CSS, Bootstrap, Bulma, Foundation
shadcn/ui, Material UI, Chakra UI, Ant Design, Radix UI

CSS Approaches

CSS Modules, styled-components, Emotion
Inline styles, CSS variables, Sass/SCSS

Example Workflow

User runs their dev server: npm run dev
User tells the AI: "The navbar is messed up and the hero section has weird spacing"
AI uses get_fix_instructions:

get_fix_instructions(
    url="http://localhost:3000",
    user_complaint="The navbar is messed up and the hero section has weird spacing"
)

Server returns precise instructions:

Interpreted Problem: User is reporting alignment, spacing issues with the navbar, hero

Affected Elements:
- nav.navbar (selector: nav.navbar)
- section.hero (selector: .hero-section)

Fix Instructions:

1. Fix spacing on navbar
   Selector: nav.navbar
   CSS Changes:
   - padding: 1rem 2rem
   - gap: 1rem
   - align-items: center

2. Fix spacing on hero
   Selector: .hero-section
   CSS Changes:
   - padding: 4rem 2rem
   - margin: 0 auto
   - max-width: 1200px

AI applies the exact CSS changes to the codebase

Supported UI Elements

The analyzer can identify and analyze:

navbar - Navigation bars, menus
header - Page headers, banners
footer - Page footers
hero - Hero sections, splash areas
button - Buttons, CTAs
link - Anchor links
heading - H1-H6 headings
form - Forms and form containers
input - Input fields, textareas, selects
card - Card components, panels
sidebar - Side navigation, asides
modal - Dialogs, popups
dropdown - Dropdown menus, selects
image - Images, SVGs
section - Content sections
container - Main containers, wrappers

Detected Issue Types

layout_broken
overflow_hidden
z_index_conflict
spacing_inconsistent
alignment_off
responsive_issue
accessibility_missing
contrast_low
element_overlap
invisible_element
empty_container
broken_flexbox
broken_grid

Development

# Run with MCP inspector for debugging
uv run mcp dev server.py

# Run the test suite
uv run python test_mcp_server.py

Test Coverage:

Query interpretation (vague user queries to element types)
Page loading across multiple test sites
Screenshot capture (full page, viewport, highlighted elements)
Accessibility tree extraction
DOM structure extraction
Element identification by type
Issue detection
Full page analysis
Fix instruction generation
Viewport comparison (mobile, tablet, desktop)
Technology stack detection

Test artifacts are saved to test_output/ directory:

Screenshots at different viewports
Accessibility tree YAML
DOM structure text
Detected elements JSON
Analysis results JSON
Tech stack detection results

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Acknowledgments

Built with MCP Python SDK
Uses Playwright for browser automation
Designed to work with GitHub Copilot, Cursor, and Claude

MCP Servers