Uianalyzermcp

🚀 UI Analyzer MCP Server

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

🚀 Quick Start

The UI Analyzer MCP Server is an MCP server designed to analyze website UIs and offer precise fix instructions for AI coding assistants. It effectively addresses the "messy UI updates" issue when using agentic code IDEs such as 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: Compares UIs across mobile, tablet, and desktop viewports.
• Accessibility Analysis: Extracts accessibility tree for semantic understanding.

📦 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 Examples

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)

Basic Usage

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

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

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

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

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

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

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

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

📚 Documentation

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:

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

Example Workflow

1. User runs their dev server: npm run dev.
2. User tells the AI: "The navbar is messed up and the hero section has weird spacing".
3. 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"
)

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

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

🔧 Technical Details

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

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.