Content
# FE Inspector MCP
**A frontend quality inspection MCP Server for AI coding agents.**
hallmark checks aesthetic. FE Inspector checks aesthetic + accessibility + responsive + interaction — because a good UI isn't just pretty, it works.
## Real-world comparison
We took a typical AI-generated SaaS landing page (purple gradient, stacked cards, missing alt text, no viewport meta, dead links — the kind Claude Code or Cursor outputs in one shot) and ran both tools on it.
| | hallmark | FE Inspector |
|---|---|---|
| **Issues caught** | 2 | **16** |
| **Coverage** | Aesthetic only | Aesthetic + A11y + Responsive + Interaction |
**hallmark caught:**
- Dense content spacing issue
- Stacked card layout detection
**FE Inspector caught ALL of those PLUS:**
- 2 images missing alt text 🚨
- 4 clickable divs without roles 🚨
- Missing viewport meta tag 🚨
- No CSS media queries (not responsive)
- Multi-column grid without mobile breakpoint
- No hover/focus visual feedback on interactive elements
- 2 links with no destination (dead links)
- Missing pointer cursor on buttons
[See the sample page →](docs/sample-ai-page.html) | [Run it yourself →](#installation)
hallmark is a great aesthetic checker. FE Inspector is a **complete frontend quality gate**.
## Why this exists
[hallmark](https://github.com/Nutlope/hallmark) proved that developers care about AI-generated UI quality. But hallmark only checks **visual patterns** (gradients, spacing, fonts). Your users also care about:
- Can a screen reader navigate this page?
- Does it work on a phone?
- Does the button actually respond when clicked?
FE Inspector closes that gap.
## What it checks (20 rules)
### Aesthetic (5 rules)
- Purple-blue gradient detection
- Excessive border-radius
- Low contrast text
- Dense content without separation
- Stacked-card layout detection
### Accessibility (5 rules)
- Missing image alt text
- Interactive elements without labels
- Form inputs without associated labels
- Positive tabindex values
- Clickable divs without proper roles
### Responsive (5 rules)
- Fixed pixel widths on containers
- Missing viewport meta tag
- No CSS media queries
- Rigid grid columns without mobile fallback
- Touch targets below 44px
### Interaction (5 rules)
- Missing pointer cursor on interactive elements
- No hover/focus visual feedback
- Forms without submit mechanisms
- Empty or hash-only links
- Disabled elements without explanation
## Installation
```bash
# Install globally via npm
npm install -g fe-inspector-mcp
# Or run directly with npx
npx fe-inspector-mcp
```
## MCP configuration
Add to your MCP client config (e.g., `~/.codex/config.toml` or Cursor MCP settings):
```json
{
"mcpServers": {
"fe-inspector": {
"command": "npx",
"args": ["fe-inspector-mcp"]
}
}
}
```
Or for local development:
```json
{
"mcpServers": {
"fe-inspector": {
"command": "node",
"args": ["/path/to/fe-inspector-mcp/dist/index.js"]
}
}
}
```
## Available tools
### `inspect_html`
Run all quality checks on an HTML string.
**Parameters:**
- `html` (required): The HTML content to inspect
- `url` (optional): URL for context
- `categories` (optional): Specific categories to check (`aesthetic`, `a11y`, `responsive`, `interaction`)
- `format` (optional): `text` (default) or `json`
**Example output:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FE Inspector — Frontend Quality Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generated: 2026-07-21T07:48:00Z
Elements: 187
Summary: Found 2 errors, 3 warnings, 15 passed.
── Aesthetic (2) ──
[!] ae-001: Avoid purple-blue gradient backgrounds
Element <section> uses a purple-blue gradient
Fix: Replace with a neutral or brand-specific scheme
── Accessibility (2) ──
[X] a11y-001: Missing alt attribute on <img>
Image "/hero.jpg" has no alt text
Fix: Add descriptive alt attribute
── Responsive (1) ──
[X] rp-002: Missing viewport <meta> tag
Without viewport meta, mobile browsers may scale wrongly
Fix: Add <meta name="viewport" content="width=device-width, initial-scale=1">
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quality Score: 75/100
15 passed | 3 warnings | 2 errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### `inspect_html_fix`
Same as `inspect_html` but returns structured Markdown fix suggestions that coding agents can apply automatically.
### `inspect_categories`
List available categories and rule counts.
### `review_design` ✨ (hallmark can't do this)
**Pre-build design review.** Describe what you're about to build, and get a checklist of common frontend pitfalls BEFORE writing code.
**Parameters:**
- `description` (required): Describe the UI you're planning (e.g. "a login form with email and password, a navbar with dropdown menus, a pricing card grid")
**Example:**
```
Agent: review_design description="a landing page with hero section, feature cards, testimonial carousel, and footer form"
Result:
[!] [a11y] MUST: Alt text on all images
Every <img> needs alt. Decorative images get alt="".
[!] [responsive] MUST: Viewport meta tag
Every page needs <meta name="viewport">.
[~] [responsive] SHOULD: Responsive grid breakpoints
Use grid-template-columns with auto-fit/auto-fill or add @media breakpoints.
[~] [interaction] SHOULD: Loading states
Show skeleton screens or spinners during data fetch.
[~] [semantic] SHOULD: Semantic HTML structure
Use <header>, <main>, <section> instead of generic <div>s.
---
3 must-fix, 4 should-fix, 7 total points to review.
```
**Why this matters:** hallmark only checks code after it's written. `review_design` checks your intent before you write a single line — catching issues at the design stage where they're cheapest to fix.
## Usage with agents
**Claude Code:**
```
claude
> inspect the HTML I just generated
```
**Codex CLI:**
```
codex
> run fe-inspector on the page output
```
**Cursor:**
Configure MCP server in Cursor settings → MCP → Add server.
## Compared to hallmark
| | hallmark | FE Inspector |
|---|---|---|
| **Real-world catch rate** (SaaS landing page) | 2 issues | **16 issues** (8x more) |
| **Aesthetic checks** | 57 rules | 5 focused rules |
| **Accessibility (a11y)** | ❌ | 5 rules |
| **Responsive (mobile)** | ❌ | 5 rules |
| **Interaction logic** | ❌ | 5 rules |
| **Total rules** | 57 (all aesthetic) | **20 (4 dimensions)** |
| **Output format** | Passive Skill (agent text) | MCP tools (text + JSON + fix suggestions) |
| **Distribution** | SKILL.md only | MCP Server + SKILL.md |
## License
MIT
