# Nitpick

MCP server + Chrome extension for structured, click-to-annotate UI feedback that AI coding agents (Cursor, Claude Code, etc.) can consume as context.

> **Status:** Week 1 — MCP server core. Chrome extension lands in weeks 3–4.

## What's here

| Package | Role |
|---|---|
| `@nitpick/shared` | Zod feedback schema (single source of truth) |
| `@nitpick/mcp-server` | MCP tools over stdio + localhost HTTP ingest |

## Prerequisites

- Node.js 20+
- npm 10+

## Setup

```bash
git clone https://github.com/salahashraf3/Nitpick.git
cd Nitpick
npm install
npm run build
```

## Run the MCP server

```bash
npm run start:server
```

This starts:

1. **MCP stdio** — for Cursor / Claude Code
2. **HTTP ingest** on `http://127.0.0.1:3847` (default) — for the future Chrome extension

If `3847` is already taken, the server picks the next free port (`3848`, `3849`, …) and logs the URL on stderr. To pin a port:

```bash
NITPICK_HTTP_PORT=3850 npm run start:server
```

If you set `NITPICK_HTTP_PORT` and that port is busy, startup fails with a clear error (no silent fallback), so the extension can keep a fixed URL.

Health check (use the port from the log line):

```bash
curl http://127.0.0.1:3847/health
```

Submit feedback via HTTP (hand-crafted payload):

```bash
curl -s -X POST http://127.0.0.1:3847/feedback \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://app.example.com/dashboard",
    "target": {
      "selector": "#dashboard > div.card-header:nth-child(2)",
      "tagName": "div",
      "textContent": "Revenue Overview",
      "boundingBox": { "x": 120, "y": 84, "width": 320, "height": 48 }
    },
    "issueType": "spacing",
    "severity": "minor",
    "description": "Card header has too much bottom padding compared to other cards"
  }'
```

Feedback is kept in memory and persisted to `~/.nitpick/feedback.json`.

## Cursor MCP config

Add to your Cursor MCP settings (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "nitpick": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/Nitpick/packages/mcp-server/dist/index.js"]
    }
  }
}
```

Replace `/ABSOLUTE/PATH/TO/Nitpick` with your clone path. After reload, the agent can call `submit_ui_feedback`.

### Claude Code

```bash
claude mcp add nitpick -- node /ABSOLUTE/PATH/TO/Nitpick/packages/mcp-server/dist/index.js
```

## MCP tool (week 1)

### `submit_ui_feedback`

Required: `target`, `issueType`, `description`.

Optional: `url`, `severity` (default `minor`), `screenshot`, `suggestedFix`, `domContext`.

`issueType`: `spacing` | `alignment` | `color` | `typography` | `responsiveness` | `interaction` | `content` | `other`

`severity`: `blocker` | `major` | `minor` | `nit`

## Project layout

```
packages/
  shared/          # Zod schema + types
  mcp-server/      # MCP + HTTP ingest
  chrome-extension/  # (weeks 3–4)
docs/
```

## Roadmap

- **Weeks 1–2:** MCP server core ← you are here
- **Weeks 3–4:** Chrome extension capture
- **Weeks 5–6:** Extension → server end-to-end
- **Week 7:** Polish + demo GIF
- **Weeks 8–9:** Resume packaging + soft launch

## License

MIT