css-sota-mcp

An MCP server that answers what CSS you can actually ship today — from live Baseline data and MDN browser-compat-data, not from a model's training set.

Agents are confidently wrong about browser support. They will tell you anchor-name is fine, or that :has() needs a polyfill, depending on when their weights were frozen. This server replaces the guess with the current answer.

• Endpoint — https://css-sota-mcp.lusrodri.workers.dev/mcp (Streamable HTTP, no auth)
• Docs — css-sota-mcp.pages.dev
• Registry — io.github.LuSrodri/css-sota-mcp, listed in the official MCP Registry

Tools

check_support and audit_css answer with no network call at all — the data they need is compiled into the Worker.

dont_make_me_think

Named after Steve Krug's rule: a page should be self-evident. Two modes.

mode: "guidelines" returns the principles to design against — Nielsen's 10 heuristics, Hick's and Fitts's laws, WCAG 2.2, neurodiversity-inclusive design, motion and microinteractions (including when Lottie or Rive earn their bundle cost), SVG craft and animation, light-first theming, lightness, responsiveness. Filter with topic. The knowledge base is mcp/src/data/ux-guidelines.json; every principle carries its rationale, actionable rules and a source.

mode: "review" checks HTML and CSS — or a fetched url — and reports what violates which principle, with the line and the evidence.

It reads source; it does not render it. A Worker has no layout engine, so the review cannot measure computed contrast, real target sizes, or where focus actually lands. It catches what is visible in the markup: missing alt, blocked zoom, animation with no reduced-motion path, a removed focus ring, a dark-only palette, vague link text, a nav past Hick's range. A clean result is a floor, not a pass, and the tool says so in its own output.

audit_css targets

Two target styles, because they answer different questions:

• A Baseline level — baseline-widely, baseline-newly. Asks "is this interoperable enough to ship?", judged against web-features' Baseline status.
• An explicit browser list — chrome 120, safari 17.4, firefox 128. Asks "does this work for my users?", judged against per-browser versions.

Browserslist queries (last 2 versions, >0.5%) are not accepted. Resolving them needs usage data this server does not carry, and approximating them would produce confidently wrong audits — exactly the failure mode the server exists to fix. The tool says so rather than guessing.

Connect

claude mcp add --scope user --transport http css-sota https://css-sota-mcp.lusrodri.workers.dev/mcp

--scope user registers it once for every project on the machine. Leave it out and the server is added to the current project only.

https://css-sota-mcp.lusrodri.workers.dev/mcp

npx @modelcontextprotocol/inspector@latest

Limits on the hosted endpoint

The endpoint is public and unauthenticated on purpose: every tool is read-only over public datasets, so there is nothing to protect from disclosure. What is worth protecting is the account's request budget and the server's standing with the upstreams it proxies.

120/minute is sized against real usage rather than a round number: an agent working through a task calls a handful of tools per turn, so a burst of twenty is unremarkable and 120 leaves room for a shared address running several clients.

Cloudflare's own guidance prefers keying rate limits on a user or tenant id rather than an IP, since an IP can be shared behind NAT or a privacy relay. This endpoint has no authentication and so no such id; the limit is set generously enough that the trade is a fair one.

If you expect sustained traffic above this, run your own instance — the whole thing is one Worker and deploys in a minute.

Layout

mcp/       The MCP server — a Cloudflare Worker
landing/   Documentation site — Vite, on Cloudflare Pages

What the landing page serves to crawlers

The docs site is how an agent finds this server without being told about it, so it publishes more than HTML:

Two things the page does not do are worth stating, because both were true until recently. The endpoint URL is no longer injected only by script — it is in the markup, so anything that reads the HTML without executing it still learns the one fact the page exists to convey. And the Worker origin now carries a Link: …; rel="canonical" header pointing at the docs site, so the two hostnames describing this server do not compete to be the one that gets cited.

The page makes no third-party requests. The three typefaces are served from this origin, pinned in landing/public/fonts/ and declared in landing/src/fonts.css — latin subsets only, and one file per family where upstream is variable. They came from fonts.googleapis.com until that stylesheet turned out to be the longest pole in the page's largest contentful paint: render-blocking, on another host, and itself a hop to a third host for the files. Regenerate them with landing/scripts/fetch-fonts.js; it is deliberately not a build step, since refetching on every build would put a third party back in the critical path one level down.

How the data is put together

@mdn/browser-compat-data unpacks to ~20 MB, far past a Worker's bundle budget. At build time mcp/scripts/build-data.js extracts the CSS slice of it plus the web-features catalog, drops every field the server never reads, and encodes per-browser support positionally. The result is about 1 MB of JSON — 120 KB gzipped — which ships inside the Worker.

The generated files are gitignored. Every build, test and deploy regenerates them, so the data always matches whatever version npm resolved.

Two details worth knowing, both found the hard way:

• web-features encodes Baseline as "high" / "low" / false, while api.webstatus.dev and all Baseline documentation say widely / newly / limited. The build normalises to the latter so the two halves of the server never disagree.
• MDN reorganised its CSS reference under Web/CSS/Reference/…. Compat data records the slug a page had when the entry was written, so building a raw GitHub path from mdn_url 404s. get_feature resolves the canonical slug through MDN first, then reads the source.

Development

npm install

npm run dev --workspace mcp        # wrangler dev on :8787
npm test --workspace mcp           # vitest
npm run typecheck                  # both workspaces

node mcp/scripts/smoke.js          # real MCP protocol call against :8787
node mcp/scripts/smoke.js <url>    # ...or against a deployment

smoke.js speaks the 2025-era Streamable HTTP flow — the same one the AI Playground and MCP Inspector use — so a passing run means those clients will work too.

Deploy

Pushing to main deploys both. Cloudflare builds from this repo directly — no API token is stored in GitHub, and Cloudflare issues its own build credential.

The Worker's build command is not optional: mcp/src/data/generated/ is gitignored, and src/data/index.ts imports it statically, so a build that skips it fails to bundle.