@cssints/mcp

An MCP server for cssints: it lets a coding agent check its CSS the way the build checks it, without running the app, and ask a running app's dev server what its classes are. It runs over stdio (cssints-mcp) and is built on effect/ai McpServer. Logs go to stderr; stdout carries the protocol only.

Tools

Tool	Answers	Example
check_declaration	ok, or the exact message the build gives: the property's grammar, value ranges, the prose rules of the specs	{ "property": "padding", "value": "-1rem" } → padding: unexpected "-1rem" in "-1rem", expected <length-percentage [0,∞]>
check_support	the targets that lack a property or a feature of its value, with the BCD key, by the rule of the build's support warnings (partial_implementation counts as supported); what LightningCSS lowers for them (loweredOf of cssints/check) is supported, under lowered with the value it writes	{ "property": "textWrap", "value": "balance", "query": "chrome 109" } → css.properties.text-wrap, lacking chrome 109
check_contrast	the WCAG 2.x ratio of css.check.contrast, from the engine (contrast of cssints/check; cut, not rounded, at two places), and whether it meets min	{ "foreground": "#777", "background": "white", "min": 4.5 } → contrast 4.47 is below 4.5
compile	a module through the real plugin: its class strings, the CSS it adds to the sheet, the transformed code, errors and warnings, each at its call (file:line:col; a warning is said by every compile)	{ "file": "src/Button.tsx" }, or { "file": "src/Card.ts", "source": "..." } for text that is not saved
search_docs	the matching sections of docs/API.md, README.md and the plugin READMEs: file, line, heading trail, an excerpt	{ "query": "firstThatWorks fallback" }
list_plugins	the plugin packages, their members, what each does, the README	{}

On a running dev server

Tool	Answers	Example
explain_class	per class: its declarations, conditions (@media, @container, :hover, ...), layer, plugin or kernel, the tokens it reads with their values, the calls that made it (file:line:col)	{ "classes": "_1d608he" } → color: #dc2626, :hover, _.b, src/components/Inspect.tsx:25:14
module_styles	the css.* calls of one file as the dev server compiled them, each with its classes and their CSS	{ "file": "src/components/Button.tsx" }
dev_errors	the build errors Vite sends to its clients now (message, file:line:col, plugin, code frame); what is not sent (warnings, the page's runtime errors) is named	{} → padding: unexpected "-1rem" at src/bad.ts:4:20

They take url, the app's dev server (default http://localhost:5173), which must be running. explain_class and module_styles need cssints({ devtools: true }) in the app's vite.config (else they say so): they ask for the table the devtools overlay reads (cssints:devtools:get over Vite's HMR websocket, one socket per url for the session) and keep it until the server says it is stale. The server knows only the modules it has served, so the first call fetches every module the page reaches (dynamic imports too), and again after an edit: no browser has to be open. dev_errors works on any Vite dev server: it fetches the modules again and collects Vite's error payloads.

In a browser

Tool	Answers	Example
inspect_element	what the devtools overlay shows: the element's classes by the call that made them, per property the winner, what it overrides (and why), what does not apply now, and the check against the computed style	{ "selector": "[data-case=hover-md]", "hover": true } → color: #dc2626 from ._1d608he:hover beats #2563eb by specificity, ✓
why_property	one property: the winner and its call, its conditions and whether each holds, what it beats and why, what does not apply, ✓/✗ with the reason	{ "selector": "[data-case=unlayered]", "property": "color" } → ✗, .mine { … } in src/components/inspect.css beats it

They open url (default http://localhost:5173) in a headless Chromium of playwright-core, one page per url kept for the session, read the table from the dev server as the live tools do (so cssints({ devtools: true }) again; server when the server is not the page's origin), add the devtools core to the page (@cssints/devtools/inject, bundled by Vite on the first call) and run the overlay's cascade on the first element the selector matches. hover and focus put the element in that state first (else the pointer is moved away and the focus dropped); width and height size the viewport. They need a Chromium: npx playwright-core install chromium, else an installed Chrome is used.

check_support without query reads the project's browserslist (package.json "browserslist" or .browserslistrc, found from root, else the working directory), as the plugin reads it from its Vite root; compile's warnings are those of the root's targets. compile starts a Vite dev server in middleware mode for the project root (the root argument, else the working directory) on its first call and reuses it: the project's vite.config is loaded when it has one (its aliases, its cssints() options), else the plugin alone; the project's own vite and cssints are used when installed. Each call reads the module and what it imports again.

Installed in a project, search_docs reads node_modules/cssints/docs/API.md (the published cssints holds a copy, made by its prepack), the README of cssints and those of @cssints/*, and list_plugins those READMEs; run from this repository, they read docs/API.md, README.md and every package README.

Install

bun add -d @cssints/mcp   # or: npm i -D @cssints/mcp

The client starts the server in the project's directory, so the working directory is the project root.

opencode

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cssints": {
      "type": "local",
      "command": ["npx", "cssints-mcp"],
      "enabled": true
    }
  }
}

Claude Code

claude mcp add cssints -- npx cssints-mcp

(--scope project writes it to .mcp.json for the whole team.)

Cursor

.cursor/mcp.json:

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

In this repository, use node packages/mcp/src/bin.ts as the command (Node 22.18 or later runs the TypeScript sources).

Credits

The server speaks the Model Context Protocol and is built on effect/ai. The checks are those of the build: mdn-data and browser-compat-data (both CC0-1.0), through @cssints/css-grammar.

Development

cd packages/mcp
bun run test        # test/tools.mjs: every tool through an in-process MCP client; test/stdio.mjs: the bin over stdio;
                    # test/live.mjs: the live tools on apps/demo's dev server and on test/fixtures/app
bun run test:browser  # test/browser.mjs: inspect_element and why_property on the demo in Chromium (needs one)
bun run typecheck