io.github.prembobby39-gif/uimax-mcp
Frontend expert for Claude Code. Screenshots, Lighthouse, axe-core, code analysis, auto-fix.
Open source Open in the app JSON README (API)
About
Frontend expert for Claude Code. Screenshots, Lighthouse, axe-core, code analysis, auto-fix.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- prembobby39-gif
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.7.0
- Stars
- 9
- Forks
- 1
- Last push
- 2026-03-29T18:50:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:13
- Updated
- 2026-08-29 04:01:13
- Origin id
io.github.prembobby39-gif/uimax-mcp
README
# UIMax MCP
**Turns Claude Code into a frontend expert that reviews and fixes your UI automatically.**
<p align="center">
<img src="https://img.shields.io/npm/v/uimax-mcp" alt="npm version" />
<img src="https://img.shields.io/npm/dm/uimax-mcp" alt="npm downloads" />
<img src="https://img.shields.io/npm/l/uimax-mcp" alt="license" />
<img src="https://img.shields.io/badge/tools-37-blue" alt="37 tools" />
<img src="https://img.shields.io/badge/tests-463%20passing-brightgreen" alt="463 tests passing" />
<img src="https://img.shields.io/badge/cost-free%20(Pro%20plan)-brightgreen" alt="free for Pro plan" />
</p>
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.**
```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:
```
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:
```
┌─────────────────────────────────────────────────────┐
│ 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)
```
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:
| 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`](#configuration).
---
## 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:
```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:
- [ ] CSS specificity analyzer
- [ ] Design token extraction
- [ ] Framework-specific checks (Vue composition API, Svelte stores)
- [x] Visual regression with pixel-level diffing
- [x] Performance budgets (fail if scores drop below thresholds)
- [x] Browser interaction (click, type, scroll, navigate)
- [x] Console and network capture
- [x] Deep Lighthouse analysis (PWA, security, unused code, LCP, resources)
- [x] AI-powered semantic visual comparison
- [x] Review history tracking with auto-save
- [x] Dedicated SEO audit (18 checks, weighted scoring)
- [x] Per-section letter grades (A+ through F Report Card)
- [x] Verify fixes (before/after comparison with grade transitions)
- [x] Competitive benchmarking (side-by-side site comparison)
- [x] 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