UI Annotator for Claude Code

Drop numbered pins on your running dev site, capture an annotated screenshot, and let Claude Code read and fix your UI issues — without leaving the terminal.

---

What is UI Annotator?

UI Annotator is a local developer tool that bridges visual UI feedback and AI-assisted code changes. It consists of two parts:

• A Chrome extension — activates an annotation overlay on any localhost tab, lets you click to place numbered pins, type comments, and capture an annotated screenshot.
• An MCP server — receives the screenshot and annotations from the extension and exposes a get_ui_feedback() tool that Claude Code can call directly.

The result: you point at a bug, describe it, press a button, and Claude Code sees exactly what you see — no copy-pasting, no context loss.

---

Why developers love it

• Zero friction — no cloud services, no auth, no uploads. Everything runs locally.
• Works with any stack — React, Vue, Next.js, plain HTML, anything served on localhost.
• Structured feedback — Claude receives a screenshot and structured JSON (selector, coordinates, comment) for each pin, so it can target the exact element.
• MCP-native — plugs directly into Claude Code via the Model Context Protocol. No custom glue code needed.
• No build step — the Chrome extension is vanilla JS loaded directly from source.

---

Demo

1. Open your local dev site in Chrome.
2. Click the UI Annotator icon → annotation overlay activates.
3. Click any element, type a comment, repeat for every issue.
4. Click Send to Claude in the floating toolbar.
5. In your terminal: "Check my UI feedback"
6. Claude calls get_ui_feedback(), sees the annotated screenshot, and fixes the code.

Developer → pins UI bug → captures screenshot → sends to MCP server
                                                        ↓
Claude Code ← calls get_ui_feedback() ← reads screenshot + annotations
                                                        ↓
                              Claude describes and fixes the issue

---

Prerequisites

• Node.js 18+
• Chrome (or any Chromium-based browser)
• Claude Code with MCP support (claude mcp command available)

---

Installation

1. Clone and install

git clone https://github.com/your-username/ui-annotator.git
cd ui-annotator
npm install

2. Vendor html2canvas (one-time)

curl -L https://html2canvas.hertzen.com/dist/html2canvas.min.js \
  -o packages/chrome-extension/lib/html2canvas.min.js

3. Connect to Claude Code

claude mcp add ui-annotator node /absolute/path/to/ui-annotator/packages/mcp-server/src/index.js

Then restart Claude Code and verify:

/mcp
# → ui-annotator  ✓  get_ui_feedback

Claude Code auto-starts the MCP server — no need to run npm start manually.

4. Load the Chrome extension

1. Open chrome://extensions
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked
4. Select the packages/chrome-extension/ folder

The UI Annotator icon appears in your toolbar. Done.

---

Usage

1. Navigate to your dev site on localhost in Chrome.
2. Click the UI Annotator toolbar icon.
3. Click Enable Pin Mode and click on any element to annotate it.
4. Click Capture & Send when you're done.
5. Ask Claude Code: "Review my UI feedback" or "Check my UI annotations".

Claude calls get_ui_feedback() and receives:

• A full-page screenshot with pins overlaid
• Structured annotations: { id, comment, x, y, selector } per pin

---

How it works (architecture)

Chrome Extension
  └─ content.js        ← renders pins, captures screenshot via html2canvas
  └─ background.js     ← POSTs payload to MCP server

MCP Server (Node.js, port 3847)
  └─ httpBridge.js     ← Express: POST /feedback, GET /health
  └─ store.js          ← holds latest FeedbackBatch in memory
  └─ index.js          ← registers get_ui_feedback() MCP tool via stdio

Claude Code
  └─ calls get_ui_feedback() → receives screenshot + annotations

For a full architecture diagram and developer notes, see CLAUDE.md.

---

Project structure

ui-annotator/
├── packages/
│   ├── mcp-server/              # Node.js MCP server + Express HTTP bridge
│   │   ├── src/
│   │   │   ├── index.js         # MCP entry, get_ui_feedback tool
│   │   │   ├── httpBridge.js    # POST /feedback receiver (port 3847)
│   │   │   └── store.js         # In-memory FeedbackBatch store
│   │   └── tests/
│   │       └── server.test.js   # 12 integration + unit tests
│   └── chrome-extension/        # Manifest V3 extension (no build step)
│       ├── src/
│       │   ├── content.js       # Annotation overlay and capture engine
│       │   ├── background.js    # Service worker, POST to MCP server
│       │   └── popup/           # Popup UI (HTML/CSS/JS)
│       └── lib/
│           └── html2canvas.min.js
├── mcp-config.json              # Ready-to-use MCP config snippet
└── CLAUDE.md                    # Full developer + agent documentation

---

Running tests

npm test
# 12/12 passing — HTTP bridge integration + store unit tests

Tests use Node's built-in test runner. No extra setup required.

---

Configuration

Environment variable	Default	Description
PORT_BRIDGE	3847	Port the HTTP bridge listens on

---

Known limitations

• Localhost only — the extension only runs on http://localhost/* and http://127.0.0.1/*. Edit manifest.json to support remote dev servers.
• Cross-origin iframes — html2canvas cannot capture content inside cross-origin iframes.
• One batch at a time — a new capture overwrites the previous one. No queue yet.
• Pin scroll drift — pins placed before scrolling may appear slightly offset in the screenshot.

---

Roadmap

• Remote dev server support (configurable allowed origins)
• Multi-batch queue (FIFO)
• Auto-highlight DOM elements after Claude reads feedback
• VS Code extension variant
• Pre-built extension in the Chrome Web Store

---

Contributing

Contributions are welcome! The codebase is intentionally minimal — vanilla JS, no bundler, no framework.

1. Fork and clone the repo
2. npm install
3. Make your change
4. npm test — all 12 tests must pass
5. Open a pull request

Please read CLAUDE.md before contributing — it contains the full architecture, coding conventions, and rules the AI agent follows.

---

Related projects

• Model Context Protocol — the open standard this tool is built on
• Claude Code — the AI coding assistant this tool integrates with
• html2canvas — the screenshot library used in the extension

---

License

MIT © 2026