mcp-frontend-tools

The reference Model Context Protocol server for frontend work. One install gives any coding agent — Claude Desktop, Cursor, VS Code, Zed, Continue — real eyes and hands on your UI:

• axe_audit — run the real axe-core rule engine against raw HTML (via jsdom) or a live URL (via Playwright). Returns violations grouped by WCAG impact with fix links.

• page_screenshot — headless-Chromium PNGs of any URL or CSS selector, with viewport / DPR / color-scheme / waitForSelector controls.

• bundle_budget_check — walk a dist/ directory, compute gzip (+ optional brotli) sizes, enforce a global or per-entry KB budget. CI-ready pass/fail JSON.

• design_token_diff — structural diff of two W3C DTCG / Style Dictionary token files. Reports added / removed / changed tokens with $type-aware notes.

• storybook_story_run — load a single Storybook story in headless Chromium via iframe.html?id=…, screenshot it, and run an axe audit against just the rendered component.

• scaffold_react_component — emit a typed React component (functional / forwardRef / polymorphic as) plus optional Vitest test and Storybook story.

All tools return structured JSON the model can reason over. No bespoke wrappers per editor.

Install

npm i -g @ashios15/mcp-frontend-tools
# Optional — enables page_screenshot, storybook_story_run, and URL-mode axe_audit
npm i -g playwright
npx playwright install chromium

Node ≥ 20 is required. Without Playwright the server still starts; those three tools will return a clear "install playwright" error if called.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or the Windows equivalent):

{
  "mcpServers": {
    "frontend-tools": {
      "command": "mcp-frontend-tools"
    }
  }
}

Cursor

Settings → MCP → Add new server:

{
  "frontend-tools": { "command": "mcp-frontend-tools" }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json:

{
  "servers": {
    "frontend-tools": { "command": "mcp-frontend-tools" }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector mcp-frontend-tools

Related MCP server: Components Build MCP

Tool reference

axe_audit

{
  url?: string;        // require playwright
  html?: string;       // jsdom
  tags?: string[];     // default: wcag2a/aa + wcag21aa + wcag22aa + best-practice
  selector?: string;   // URL mode only
  timeoutMs?: number;  // default 15000
}

Returns violations and incomplete rules with impact, help, helpUrl, and up to 5 example failing nodes per rule.

page_screenshot

{
  url: string;
  outPath: string;           // absolute; parent dirs auto-created
  selector?: string;
  fullPage?: boolean;
  width?: number;            // default 1280
  height?: number;           // default 800
  deviceScaleFactor?: number;// default 2
  colorScheme?: "light" | "dark" | "no-preference";
  waitForSelector?: string;
  timeoutMs?: number;
}

bundle_budget_check

{
  buildDir: string;
  budgetKb?: number;                       // default 250 (gzipped)
  perEntryBudgetKb?: Record<string, number>;// key = path substring, longest match wins
  ext?: string[];                          // default [".js",".mjs",".cjs",".css"]
  includeBrotli?: boolean;
}

Returns every file with raw / gzip / brotli sizes, its applied budget, and status: "pass" | "fail".

design_token_diff

{
  beforePath: string;
  afterPath: string;
  ignoreKeys?: string[];
}

Understands the W3C DTCG shape ($value, $type). Group metadata keys starting with $ are ignored. Color / dimension changes get annotated notes.

storybook_story_run

{
  storybookUrl: string;      // e.g. http://localhost:6006
  storyId: string;           // e.g. components-button--primary
  screenshotPath?: string;
  runAxe?: boolean;          // default true
  viewport?: { width: number; height: number };
  colorScheme?: "light" | "dark" | "no-preference";
  timeoutMs?: number;
}

Loads ${storybookUrl}/iframe.html?viewMode=story&id=${storyId}, waits for #storybook-root, and reports any page errors + axe violations scoped to the story.

scaffold_react_component

{
  name: string;           // PascalCase
  outDir: string;         // absolute
  variant?: "functional" | "forwardRef" | "polymorphic";
  withTests?: boolean;    // default true
  withStory?: boolean;    // default true
  props?: Array<{ name: string; type: string; required?: boolean; defaultValue?: string }>;
}

Why this over ad-hoc scripts?

• Agents get typed contracts. Every tool is a Zod-validated JSON Schema the model can introspect.

• No local hallucination. Axe violations come from the real axe-core engine, not a regex. Bundle sizes come from actual zlib compression, not estimates.

• Composable. bundle_budget_check failure → ask the agent to pull the largest file into page_screenshot → feed the image into a visual-regression step. All through MCP.

• Stable surface. Tools change behind a version bump; your .vscode/mcp.json doesn't.

Development

git clone https://github.com/ashios15/mcp-frontend-tools.git
cd mcp-frontend-tools
npm install
npm run test       # 3 unit tests (bundle + tokens + scaffold)
npm run build
npm run inspector  # opens MCP Inspector against the built server
node scripts/smoke.mjs  # quick stdio tools/list check

License

MIT © ashios15