Uimax MCP

Official

by prembobby39-gif · TypeScript

Frontend expert for Claude Code. Screenshots, Lighthouse, axe-core, code analysis, auto-fix.

Frontend development expert providing screenshots, performance analysis, accessibility testing, and code fixes.

Topics

accessibilityaxe-coreclaudeclaude-codecode-analysisdesign-reviewdeveloper-toolsfrontendlighthousemcpmodel-context-protocolpuppeteerui-reviewweb-audit

README.md26 KBView on GitHub

UIMax MCP

Turns Claude Code into a frontend expert that reviews and fixes your UI automatically.

One command — "review my UI at localhost:3000" — and it:

Sees your app — captures a real screenshot via Puppeteer
Audits accessibility — runs axe-core for WCAG 2.1 violations
Runs Lighthouse — real Google Lighthouse scores (Performance, Accessibility, Best Practices, SEO)
Measures performance — captures Core Web Vitals (FCP, LCP, CLS, TBT)
Audits SEO — 18 checks: meta tags, Open Graph, Twitter cards, structured data, heading hierarchy, canonical URLs
Scans your code — AST-based analysis for 25+ anti-patterns across accessibility, design, and code quality
Grades everything — per-section Report Card with letter grades (A+ through F) for Accessibility, Performance, Best Practices, SEO, and Code Quality
Generates an expert review — Claude acts as a senior frontend engineer with a baked-in review methodology
Implements the fixes — edits your actual code files, starting from critical issues down
Tracks everything — auto-saves review history so you can see progress over time

Works on any URL — localhost, staging, production. Any site your machine can reach.

Free for all Claude Code users (Pro plan and above). No API keys. No extra costs. Just install and go.

bash

claude mcp add uimax -- npx -y uimax-mcp

Quick Start

Install as MCP Server (for Claude Code)

bash

# Add to Claude Code — that's it, no API keys needed
claude mcp add uimax -- npx -y uimax-mcp

That's it. Now in any Claude Code conversation:

code

You: Review the UI at http://localhost:3000, source code is in ./src

Claude Code calls review_ui ->
  1. Captures screenshot of your running app
  2. Runs axe-core accessibility audit
  3. Runs Google Lighthouse (Performance, A11y, Best Practices, SEO)
  4. Measures Core Web Vitals
  5. Runs dedicated SEO audit (18 checks)
  6. Scans source code with AST-based analysis
  7. Generates per-section Report Card (A+ through F letter grades)
  8. Returns screenshot + all data + expert review methodology
  9. Claude Code generates expert review (using YOUR Pro plan -- $0 extra)
  10. Claude Code implements every fix automatically
  11. Review saved to .uimax-reviews.json for tracking

Install Globally

bash

npm install -g uimax-mcp

Tools (37)

Review Pipeline

Tool	Description
`review_ui`	The main tool. Full automated pipeline: screenshot + Lighthouse + axe-core + performance + SEO + code analysis + Report Card (A+-F letter grades) + expert review methodology. Auto-saves to review history.
`verify_fixes`	New in v0.9.0. Re-run the full audit after applying fixes. Compares against the previous review and shows a before/after Report Card with grade transitions, resolved issue count, and verdict (improved/regressed/mixed). Closes the review-fix-verify loop.
`compare_sites`	New in v0.9.0. Competitive benchmarking — audit two URLs side-by-side. Returns screenshots of both sites plus a comparison Report Card with grades for Accessibility, Performance, SEO, and weighted Overall score.
`quick_review`	Fast design-only review. Screenshot + focused design methodology. No code analysis or performance audit.
`export_report`	Generate a standalone HTML report with everything embedded. Now includes Report Card grade cards and SEO section. Dark themed, zero dependencies. Share with your team.

Screenshots & Visual

Tool	Description
`screenshot`	Capture a high-resolution PNG screenshot of any URL.
`responsive_screenshots`	Screenshots at mobile (375px), tablet (768px), and desktop (1440px) viewports.
`check_dark_mode`	Compare light mode vs dark mode (emulated). Returns both screenshots + difference percentage.
`compare_screenshots`	Pixel-level diff using `pixelmatch`. Returns both screenshots + red-highlighted diff image + exact pixel difference %.
`semantic_compare`	AI-powered visual comparison. Captures before/after + pixel diff, returns structured methodology for Claude to evaluate whether changes match the intended design request.

Lighthouse, Performance & SEO

Tool	Description
`lighthouse_audit`	Full Google Lighthouse audit — Performance, Accessibility, Best Practices, SEO scores + failing audits.
`seo_audit`	New in v0.8.0. Dedicated SEO audit checking 18 signals: meta title/description, heading hierarchy, Open Graph, Twitter cards, structured data (JSON-LD), canonical URLs, image alt text, viewport meta, lang attribute, and more. Weighted scoring by impact.
`pwa_audit`	PWA readiness: installable, service worker, HTTPS, manifest, offline capability.
`security_audit`	Security analysis: HTTPS, CSP, mixed content, vulnerable JS libraries, external links without `noopener`.
`unused_code`	Find unused JavaScript and CSS with exact byte savings per resource.
`lcp_optimization`	Deep LCP analysis: what the element is, resource load time, render delay, TTFB, optimization suggestions.
`resource_analysis`	Full resource breakdown by type, transfer sizes, request count, top 10 largest, render-blocking resources.
`performance_audit`	Core Web Vitals via Performance API: FCP, LCP, CLS, TBT, DOM node count, JS heap size.
`accessibility_audit`	axe-core WCAG 2.1 Level A & AA audit. Violations grouped by severity with fix instructions.

Code Analysis

Tool	Description
`analyze_code`	AST-based analysis (TypeScript compiler API) for 25+ rules. Zero false positives on string literals. Falls back to regex for non-JS files. Configurable via `.uimaxrc.json`.

Browser Interaction

Tool	Description
`navigate`	Navigate to a URL, wait for network idle. Returns page info + screenshot.
`click`	Click an element by CSS selector. Returns screenshot after click.
`type_text`	Type into input fields. Options: `clearFirst`, `pressEnter`. Returns screenshot after.
`select_option`	Select a dropdown option by value. Returns screenshot after.
`scroll`	Scroll by pixel amount or to a specific element. Returns screenshot after.
`wait_for`	Wait for an element to appear in the DOM. Returns tag name and text content.
`get_element`	Get element details: attributes, bounding box, computed styles, visibility.

Debugging

Tool	Description
`capture_console`	Capture all console messages (log, warn, error, info, debug) + uncaught exceptions during page load.
`capture_network`	Capture all network requests with status, size, timing, resource type. Summary grouped by type.
`capture_errors`	Capture JS exceptions, unhandled rejections, and failed resource loads.

Multi-Page

Tool	Description
`crawl_and_review`	Discover internal links from a URL and audit up to 10 pages — screenshot + axe-core + performance each.

Baselines & Budgets

Tool	Description
`save_baseline`	Save current audit state to `.uimax-history.json`. Track scores over time.
`compare_to_baseline`	Compare current state vs previous baseline. Shows improvements and regressions with letter grade transitions (e.g., "D -> B+ (+22)").
`check_budgets`	Enforce performance budgets from `.uimaxrc.json`. Pass/fail for Lighthouse scores, Web Vitals, violation counts.

Review History

Tool	Description
`get_review_history`	View past UIMax reviews for this project. Filter by URL, limit count. Now includes letter grades alongside scores.
`get_review_stats`	Aggregate statistics: total reviews, score trends, most common issues, most problematic files. Includes Code Quality grades.
`review_diff`	Compare two specific reviews — new issues, resolved issues, score changes with letter grade transitions.

Every review is auto-saved. When you run review_ui, the results are automatically persisted to .uimax-reviews.json. No manual save needed — just ask "show me my review history" anytime.

Report Card (A+ through F)

Every review_ui run now generates a per-section Report Card with letter grades on a 13-tier scale:

code

┌─────────────────────────────────────────────────────┐
│                    REPORT CARD                       │
├──────────────────┬──────────┬───────┬───────────────┤
│ Section          │ Score    │ Grade │ Rating        │
├──────────────────┼──────────┼───────┼───────────────┤
│ Accessibility    │ 95       │ A     │ Excellent     │
│ Performance      │ 72       │ C-    │ Below Average │
│ Best Practices   │ 88       │ B+    │ Very Good     │
│ SEO              │ 61       │ D-    │ Very Weak     │
│ Code Quality     │ 83       │ B     │ Good          │
└──────────────────┴──────────┴───────┴───────────────┘

Grades appear in:

review_ui output — Report Card table at the top of every review
export_report HTML — color-coded grade cards (green A -> red F)
compare_to_baseline — grade transitions showing improvement (e.g., D -> B+ (+22))
get_review_history / get_review_stats / review_diff — grades alongside numeric scores for quick scanning

The grading scale: A+ (97+) > A (93+) > A- (90+) > B+ (87+) > B (83+) > B- (80+) > C+ (77+) > C (73+) > C- (70+) > D+ (67+) > D (63+) > D- (60+) > F (<60)

AST-Powered Code Analysis

The analyze_code tool uses the TypeScript compiler API for .ts/.tsx/.js/.jsx files — catching bugs that regex misses with zero false positives.

Rule	What AST catches that regex misses
`react-hooks-conditional`	Hooks inside nested if/for/while/ternary — proper scope traversal
`missing-key-prop`	`.map()` callbacks returning JSX without `key` — handles arrow/block bodies
`empty-catch`	Empty catch blocks — not fooled by comments
`any-type`	`any` in type positions only — ignores "any" in strings/comments
`direct-dom-access`	`document.querySelector` etc. — proper call expression matching
`console-log`	`console.log/warn/error` — not fooled by variable names containing "console"
`inline-style`	JSX `style={}` attributes — proper attribute detection

Falls back to regex for file types that can't be AST-parsed and for rules without AST implementations (hardcoded colors, z-index, font sizes, etc.).

Configuration

Create a .uimaxrc.json in your project root to customize code analysis and performance budgets:

json

{
  "rules": {
    "console-log": "off",
    "magic-number": "off",
    "hardcoded-color": "warn",
    "inline-style": "error"
  },
  "severity": {
    "todo-fixme": "high"
  },
  "ignore": [
    "node_modules",
    "dist",
    "*.test.*",
    "*.spec.*"
  ],
  "budgets": {
    "lighthouse": {
      "performance": 90,
      "accessibility": 95,
      "bestPractices": 90,
      "seo": 90
    },
    "webVitals": {
      "fcp": 1800,
      "lcp": 2500,
      "cls": 0.1,
      "tbt": 300
    },
    "maxAccessibilityViolations": 0,
    "maxCodeIssues": 10
  }
}

rules — Set any rule to "off", "warn", or "error"
severity — Override severity: "low", "medium", "high", "critical"
ignore — Additional glob patterns to exclude from analysis
budgets — Performance thresholds enforced by the check_budgets tool

UIMax searches for .uimaxrc.json in the target directory and up to 3 parent directories, so it works in monorepos.

Prompts

Expert review prompts that guide Claude's analysis:

Prompt	Use Case
`ui-review`	Comprehensive review (design + UX + a11y + perf + code)
`responsive-review`	Responsive design review across viewports
`quick-design-review`	Fast visual/UX feedback from a screenshot only
`semantic-compare`	AI-powered before/after visual comparison

Example Workflows

Full Review (the main workflow)

code

You: Review the UI at http://localhost:3000
     Source code is in ./src

Claude: [Calls review_ui]
        [Captures screenshot, runs Lighthouse + axe + perf + code scan]
        [Generates 20+ findings with specific fixes]
        [Implements every fix automatically]
        [Auto-saves review to .uimax-reviews.json]

Review Any Public Website

code

You: Review the UI at https://stripe.com

Claude: [Calls review_ui]
        [Full audit of the live production site]
        [Returns findings + recommendations]

Track Progress Over Time

code

You: Show me my review history

Claude: [Calls get_review_history]
        [Shows table of past reviews: dates, scores, issue counts]

You: Compare my last two reviews

Claude: [Calls review_diff]
        [Shows what improved ✅, what regressed ❌, new issues, resolved issues]

You: What are my most common issues?

Claude: [Calls get_review_stats]
        [Shows trends, most common issues, most problematic files]

Interact with Your App

code

You: Navigate to localhost:3000, click the login button,
     type "test@email.com" in the email field

Claude: [Calls navigate → click → type_text]
        [Returns a screenshot after each action]
        [Verifies each step visually]

Deep Performance Analysis

code

You: Find unused code on https://myapp.com

Claude: [Calls unused_code]
        [Lists every unused JS/CSS file with byte savings]
        [Suggests what to tree-shake]

You: Why is my LCP slow?

Claude: [Calls lcp_optimization]
        [Identifies the LCP element, breakdown of load time]
        [Specific optimization suggestions]

Verify Fixes (Close the Loop)

code

You: Review and fix my UI at localhost:3000

Claude: [Calls review_ui → finds 14 issues → implements fixes]

You: Now verify the fixes worked

Claude: [Calls verify_fixes]
        [Re-runs full audit → compares to previous review]

  Fix Verification — Before vs After
  | Metric                   | Before | After | Change  |
  | Accessibility violations | 5      | 0     | ✅ -5   |
  | Code findings            | 9      | 2     | ✅ -7   |
  | Total issues             | 14     | 2     | ✅ -12  |

  Verdict: ✅ IMPROVED

Competitive Benchmarking

code

You: Compare my site vs stripe.com

Claude: [Calls compare_sites]
        [Audits both URLs concurrently]
        [Returns screenshots of both sites + comparison table]

  | Category      | myapp.com | stripe.com | Winner       |
  | Accessibility | C+ (78)   | A  (94)    | ✅ stripe.com |
  | Performance   | B- (81)   | A+ (98)    | ✅ stripe.com |
  | SEO           | D  (63)   | A  (93)    | ✅ stripe.com |
  | Overall       | C  (74)   | A  (95)    | ✅ stripe.com |

SEO Audit

code

You: Run an SEO audit on https://myapp.com

Claude: [Calls seo_audit]
        [Checks 18 SEO signals: meta tags, Open Graph, structured data, etc.]
        [Returns score, passing checks, and failed checks with fix recommendations]
        [Weighted by impact: critical > high > medium > low]

Debug Page Load Issues

code

You: What console errors does localhost:3000 produce?

Claude: [Calls capture_console]
        [Returns all console messages + uncaught exceptions]

You: Show me all network requests on page load

Claude: [Calls capture_network]
        [Returns every request: URL, status, size, timing]
        [Summary grouped by resource type]

Before/After Comparison

code

You: Compare localhost:3000 with localhost:3001

Claude: [Calls compare_screenshots]
        [Pixel-level diff with red-highlighted changes]
        [Reports exact pixel difference %]

Semantic Visual Review

code

You: I changed the header to be sticky. Compare before and after.

Claude: [Calls semantic_compare with change description]
        [Captures both states + pixel diff]
        [Evaluates whether changes match the intent]
        [Checks for visual regressions]

Enforce Performance Budgets

code

You: Check if my site meets our performance budgets

Claude: [Calls check_budgets]
        [Reads thresholds from .uimaxrc.json]
        [Returns ✅ pass or ❌ fail for each metric]

Generate Shareable Report

code

You: Export a full report of localhost:3000 to ./report.html

Claude: [Calls export_report]
        [Generates standalone dark-themed HTML report]
        [Open in any browser, share with team]

Multi-Page Audit

code

You: Crawl localhost:3000 and audit all pages

Claude: [Calls crawl_and_review]
        [Discovers internal links, audits up to 10 pages]
        [Per-page: screenshot + accessibility + performance]

What Claude Reviews

When using the full review_ui pipeline, Claude evaluates:

Category	What's Checked
Visual Design	Layout, typography, color contrast, whitespace, shadows, icon consistency
User Experience	Navigation, interaction states, loading/error/empty states, edge cases
Accessibility	WCAG 2.1 AA, keyboard nav, screen reader compat, focus management
Performance	Lighthouse scores, Core Web Vitals, render-blocking resources, bundle size
SEO	Meta tags, Open Graph, Twitter cards, structured data, heading hierarchy, canonical URLs, image alt text
Code Quality	Component architecture, CSS organization, error boundaries, TypeScript safety
Security	HTTPS, CSP, vulnerable libraries, mixed content
Report Card	Per-section letter grades (A+ through F) for Accessibility, Performance, Best Practices, SEO, Code Quality
Creative	Modern UI patterns (Linear, Vercel, Raycast), micro-interactions, animations

Code Analysis Rules

The analyze_code tool checks for 25+ rules across categories:

Rule	Severity	Category
`img-no-alt`	High	Accessibility
`click-no-keyboard`	High	Accessibility
`no-form-label`	High	Accessibility
`missing-viewport-meta`	High	Accessibility
`no-lang-attr`	Medium	Accessibility
`no-focus-visible`	Medium	Accessibility
`empty-catch`	High	Code Quality
`react-hooks-conditional`	High	Code Quality
`missing-key-prop`	High	Bug
`console-log`	Low	Code Quality
`todo-fixme`	Low	Code Quality
`inline-style`	Medium	Code Quality
`any-type`	Medium	Code Quality
`magic-number`	Low	Code Quality
`direct-dom-access`	Medium	Code Quality
`event-handler-inline`	Low	Code Quality
`important-css`	Medium	Design
`hardcoded-color`	Low	Design
`z-index-high`	Medium	Design
`font-too-small`	Medium	Design
`no-lazy-image`	Medium	Performance
`large-bundle-import`	Medium	Performance
`no-error-boundary`	Medium	UX
`missing-meta-description`	Medium	UX
`large-file`	Medium/High	Code Quality
`deep-nesting`	Medium/High	Code Quality

All rules can be toggled via .uimaxrc.json.

Supported Frameworks

Auto-detected from package.json:

React / Next.js
Vue / Nuxt
Svelte / SvelteKit
Angular
Plain HTML/CSS/JS

Requirements

Node.js >= 18.0.0
Chrome/Chromium (uses your system Chrome — no extra download)
Claude Code (for MCP integration)
No API keys needed — runs entirely within Claude Code using your existing Pro plan

How It Works

code

+----------------------------------------------------------------------+
|                    Claude Code (your Pro plan)                         |
|                                                                       |
|  User: "Review my UI at localhost:3000 and fix everything"            |
|           |                                                           |
|           v                                                           |
|  +----------------------------------------------------------------+  |
|  |                UIMax MCP (37 tools)                             |  |
|  |                                                                 |  |
|  |  Screenshot -------> Puppeteer ----------> PNG Image            |  |
|  |  Accessibility ----> axe-core ------------> WCAG Violations     |  |
|  |  Lighthouse -------> Google LH ----------> Scores + Audits     |  |
|  |  Deep LH ----------> PWA/Security/LCP --> Granular Analysis    |  |
|  |  SEO Audit --------> 18 checks ----------> SEO Score           |  |
|  |  Performance ------> Perf API ----------> Web Vitals           |  |
|  |  Code Scan --------> TypeScript AST -----> Anti-patterns       |  |
|  |  Report Card ------> Grading Engine -----> A+ to F Grades      |  |
|  |  Browser ----------> Click/Type/Scroll --> Interaction          |  |
|  |  Debugging --------> Console/Network ----> Runtime Data        |  |
|  |  History ----------> .uimax-reviews.json > Progress Tracking   |  |
|  |  Expert Prompt ----> Baked-in methodology                      |  |
|  +----------------------------+-----------------------------------+  |
|                               |                                      |
|                               v                                      |
|  Claude Code receives: screenshot + data + expert methodology        |
|                               |                                      |
|                               v                                      |
|  Claude acts as world-class frontend expert (FREE -- Pro plan)       |
|     Generates comprehensive review with exact fixes                  |
|                               |                                      |
|                               v                                      |
|  Claude implements every fix in the codebase automatically           |
|                                                                       |
+----------------------------------------------------------------------+

CI / GitHub Action

UIMax ships with a reusable GitHub Action that runs audits on every PR and posts a Report Card comment.

Quick Setup

Copy the example workflow to your project:

yaml

# .github/workflows/uimax-ci.yml
name: UIMax Review
on:
  pull_request:
    branches: [main]

jobs:
  uimax-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Build and start your app
      - run: npm ci && npm run build
      - run: npm start &
      - run: npx wait-on http://localhost:3000

      # Run UIMax
      - uses: prembobby39-gif/uimax-mcp/.github/actions/uimax-review@main
        with:
          url: http://localhost:3000
          budget-accessibility: 90
          budget-performance: 80
          budget-seo: 80
          max-violations: 0

Action Inputs

Input	Description	Required	Default
`url`	URL to audit	Yes	—
`github-token`	Token for PR comments	No	`GITHUB_TOKEN`
`budget-performance`	Min performance score (0-100)	No	—
`budget-accessibility`	Min accessibility score (0-100)	No	—
`budget-seo`	Min SEO score (0-100)	No	—
`max-violations`	Max allowed a11y violations	No	—
`fail-on-regression`	Fail if grades regress	No	`false`

Action Outputs

Output	Description
`accessibility-grade`	Letter grade (A+ through F)
`performance-grade`	Letter grade
`seo-grade`	Letter grade
`total-violations`	Accessibility violation count
`passed`	Whether all budgets passed (`true`/`false`)
`report`	Full markdown report

The action updates existing UIMax comments on re-push (no duplicate comments).

See examples/uimax-ci.yml for a complete working example.

Development

bash

# Clone
git clone https://github.com/prembobby39-gif/uimax-mcp.git
cd uimax-mcp

# Install
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Test locally with Claude Code
claude mcp add uimax-dev -- node /path/to/uimax-mcp/dist/index.js

Contributing

Contributions welcome! Some ideas:

License

MIT

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "uimax-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "uimax-mcp@0.7.0"
      ]
    }
  }
}