Uimax MCP Server

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:

1. Sees your app — captures a real screenshot via Puppeteer
2. Audits accessibility — runs axe-core for WCAG 2.1 violations
3. Runs Lighthouse — real Google Lighthouse scores (Performance, Accessibility, Best Practices, SEO)
4. Measures performance — captures Core Web Vitals (FCP, LCP, CLS, TBT)
5. Audits SEO — 18 checks: meta tags, Open Graph, Twitter cards, structured data, heading hierarchy, canonical URLs
6. Scans your code — AST-based analysis for 25+ anti-patterns across accessibility, design, and code quality
7. Grades everything — per-section Report Card with letter grades (A+ through F) for Accessibility, Performance, Best Practices, SEO, and Code Quality
8. Generates an expert review — Claude acts as a senior frontend engineer with a baked-in review methodology
9. Implements the fixes — edits your actual code files, starting from critical issues down
10. 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.

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

---

Quick Start

Install as MCP Server (for Claude Code)

# 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:

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

npm install -g uimax-mcp

---

Tools (37)

Review Pipeline

Screenshots & Visual

Lighthouse, Performance & SEO

Code Analysis

Browser Interaction

Debugging

Multi-Page

Baselines & Budgets

Review History

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:

┌─────────────────────────────────────────────────────┐
│                    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.

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:

{
  "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:

---

Example Workflows

Full Review (the main workflow)

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

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

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

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

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)

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

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

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

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

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

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

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

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

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:

---

Code Analysis Rules

The analyze_code tool checks for 25+ rules across categories:

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

+----------------------------------------------------------------------+
|                    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:

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

Action Outputs

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

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

---

Development

# 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:

• CSS specificity analyzer
• Design token extraction
• Framework-specific checks (Vue composition API, Svelte stores)
• Visual regression with pixel-level diffing
• Performance budgets (fail if scores drop below thresholds)
• Browser interaction (click, type, scroll, navigate)
• Console and network capture
• Deep Lighthouse analysis (PWA, security, unused code, LCP, resources)
• AI-powered semantic visual comparison
• Review history tracking with auto-save
• Dedicated SEO audit (18 checks, weighted scoring)
• Per-section letter grades (A+ through F Report Card)
• Verify fixes (before/after comparison with grade transitions)
• Competitive benchmarking (side-by-side site comparison)
• CI/CD integration (GitHub Action for automated review on PR)
• Custom rule plugins (user-defined regex rules)
• Figma design comparison (screenshot vs Figma mock)
• Cross-browser testing (Firefox, WebKit via Playwright)

---

License

MIT