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

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

Run the MCP server

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:

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):

curl http://127.0.0.1:3847/health

Submit feedback via HTTP (hand-crafted payload):

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):

{
  "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

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