style-agent

Portable style verification toolkit (Chrome CDP + JSON specs).
Works as a CLI, and optionally as an MCP server for any MCP client (Cursor, Claude Code, etc.). Not a Cursor-only plugin.

You: define acceptance + final review
Agent / you: find → inspect → fix CSS → re-check
Channel: Chrome DevTools Protocol (no browser extension required)

---

Quick start (CLI)

git clone https://github.com/jtrslar/style-agent.git
cd style-agent
npm install
chmod +x launch-chrome.sh

# 1) Start debug Chrome (independent profile)
./launch-chrome.sh http://127.0.0.1:8080/your-page
# or: ./launch-chrome.sh   then navigate manually

# 2) Probe CDP / run a demo spec (adapt selectors to your DOM)
node cli.mjs status
node cli.mjs inspect demo-modal-shell.json

Demo specs under specs/examples/ use neutral class names (.demo-modal, …). Copy them into your app repo and edit selectors — do not treat examples as a product baseline.

---

Optional: MCP client

Register the server with your client. Cursor example:

See examples/mcp.cursor.json.example (replace the absolute path).

Optional Cursor rule sample: examples/cursor/style-agent.mdc.

Then refresh MCP in the client settings.

---

MCP tools

Tool	Purpose
style_status / style_tabs	CDP + open tabs
style_inspect	JSON spec check (failures only by default)
style_find	text / css / testid / role → uid
style_styles	computed-style subtree
style_click / style_hover / style_wait	interact then measure
style_spacing / style_dialogs / style_highlight	helpers
style_eval	advanced page expressions

No screenshots in the default path — structured JSON only.

---

Where specs live

Kind	Location
Project specs	Your app repo, e.g. style-specs/ or .kiro/style-specs/
This repo specs/examples/	Format demos only

Details: SPECS.md.

node cli.mjs inspect /absolute/path/to/your-app/style-specs/foo.json
# or
export STYLE_AGENT_SPECS_DIR="/absolute/path/to/your-app/style-specs"

---

Layout

index.mjs              MCP server entry (optional)
cli.mjs                CLI
launch-chrome.sh       debug Chrome on CDP
lib/cdp.js             CDP connect
inject/page-runtime.js page-side find + inspect
SPECS.md               project vs example specs
UPGRADE.md             optional Pixelmatch roadmap
specs/examples/        neutral demos only
examples/              MCP / Cursor samples

---

Environment (optional)

Variable	Default	Meaning
STYLE_AGENT_CDP_URL	http://127.0.0.1:9222	CDP endpoint
STYLE_AGENT_SPECS_DIR	./specs/examples	Spec search dir (point at your app in real use)

---

Upgrade path

UPGRADE.md: optional Pixelmatch gate + style-agent targeted fixes.
When style_status reports upgradeStatus=proposed, ask once whether to adopt it.

---

Notes

• Log in / CAPTCHA in the debug Chrome window yourself when needed
• Does not replace human visual taste checks; it provides structured diffs for fixing CSS