Housestyle MCP Server

housestyle-mcp

An MCP server that stops AI-built interfaces from looking AI-built.

Agents are good at producing working UI and bad at producing UI that looks like somebody decided something. The result has a recognisable fingerprint: Inter on a Tailwind blue, a purple-to-pink gradient, one border radius everywhere, and a type scale where the headline is barely larger than the body text.

This server gives an agent the tools to notice that and fix it.

No API key. Colour and type maths runs locally; font data comes from Google Fonts' public metadata endpoint. Nothing to configure, nothing to sign up for.

Install

npx housestyle-mcp

Claude Code

claude mcp add housestyle -- npx -y housestyle-mcp

Claude Desktop / any MCP client

{
  "mcpServers": {
    "housestyle": {
      "command": "npx",
      "args": ["-y", "housestyle-mcp"]
    }
  }
}

Tools

audit_css

Paste a stylesheet, token block, or Tailwind config. Returns the generic-design tells it found, why each one matters, and what to do instead.

## Design audit — 4 high, 3 medium, 1 low

### 1. !! framework-default-blue

**Found:** `#3b82f6 (Tailwind blue-500)`

**Why it matters:** A framework's stock blue signals that the palette was
inherited, not chosen. It is the single fastest way for an interface to look
like every other generated interface.

**Fix:** Choose a hue the product actually argues for and build the ramp from
it. build_palette generates a perceptually even ramp from any seed.

Ten rules, all deterministic: default font stacks, framework blues, the AI gradient, uniform radius, uniform shadow, flat type scale, emoji used as icons, wholesale centring, missing measure limit, and pure black on pure white.

A clean audit is not a claim that the design is good — only that it does not carry the usual fingerprints.

suggest_fonts / suggest_pairing

Reads the live Google Fonts catalogue (~1,950 families) and ranks for a role and mood — editorial, technical, warm, brutalist, elegant, neutral.

The ranking is deliberately not "most popular". Popularity is what produces the anonymous look, so the top of the charts is penalised, the long tail is penalised for being untested, and the middle is preferred. Inter, Roboto, Poppins and thirteen other signature defaults are excluded unless you ask for them. Script-specific families are filtered out for Latin interfaces.

suggest_pairing pairs across a category boundary, because the change of category is what makes a pairing read as deliberate. Returns ready-to-paste @import URLs and CSS custom properties.

check_contrast

WCAG 2.2 ratio with AA/AAA verdicts, plus the APCA Lc value.

Both are reported because WCAG 2.x systematically misjudges dark themes — it will pass light-on-dark pairs that are genuinely hard to read. Where the two disagree on a dark background, trust APCA.

build_palette

An 11-step ramp from one seed colour, computed in OKLCH.

OKLCH rather than HSL because HSL lightness is not perceptual: at a fixed HSL lightness, yellow reads far brighter than blue, so an HSL ramp produces steps that look unevenly spaced. Chroma is tapered toward both ends and every step is fitted back into the sRGB gamut, so no step silently clips. Contrast against white and black is computed for each step.

build_type_scale

A fluid modular scale emitted as clamp(), so sizes interpolate with the viewport instead of stepping at breakpoints.

The narrow end uses a gentler ratio than the wide end, because a single ratio applied at 360px overshoots and headlines wrap badly. Body size stays fixed — only display sizes scale.

Design

• Zero runtime dependencies beyond the MCP SDK. The colour maths is fixed by specification, so it is written out rather than pulled from a package that could drift or carry a supply chain.
• Nothing to break. The only network call is the Google Fonts metadata endpoint, cached for an hour, and every other tool is pure computation.

Development

npm install
npm run build
npm test

Licence

MIT