# 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.

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

---

## Quick start (CLI)

```bash
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`](./examples/mcp.cursor.json.example) (replace the absolute path).

Optional Cursor rule sample: [`examples/cursor/style-agent.mdc`](./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`](./SPECS.md).

```bash
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

```text
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`](./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