Annotation Overlay MCP

Annotation Overlay MCP

DOM-aware visual annotation overlay for web feedback. Draw arrows, boxes, text, freehand strokes, click elements, and annotate text selections — all in one toolbar. Submit structured annotations to Claude Code via MCP.

6 interaction modes. Zero JS dependencies. Chrome Extension + MCP Server.

[Browser Page]  ←→  [Chrome Extension]  ←→  [MCP Server]  ←→  [Claude Code]
   overlay.js         bridge.js              HTTP + stdio       read/clear tools

Quick Start

1. Install & Start MCP Server

git clone https://github.com/cc10143/annotation-overlay-mcp.git
cd annotation-overlay-mcp
npm install
npm start
# → HTTP server on port 3847 + MCP stdio transport connected

2. Load Chrome Extension

1. Open chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select the extension/ directory

The overlay now auto-injects on every page. Press Ctrl+Shift+A to toggle the toolbar.

3. Configure Claude Code MCP

// ~/.claude/settings.json
{
  "mcpServers": {
    "annotation-overlay-mcp": {
      "command": "node",
      "args": ["D:/KaiFa/annotation-overlay/server/index.js"]
    }
  }
}

Or use the CLI:

claude mcp add annotation-overlay-mcp -- node D:/KaiFa/annotation-overlay/server/index.js

Usage

Annotation Workflow

1. Open any page — the overlay auto-injects via Chrome extension
2. Annotate — use any of the 6 tools to mark issues
3. Submit — click Submit to send structured JSON to the MCP server
4. Agent reads — Claude Code calls read_annotations → processes feedback
5. Page refreshes — extension auto-reinjects overlay → next round

Tools

Keyboard Shortcuts

Colors

5 preset colors: red #e94560, blue #4080f0, green #2ecc71, yellow #f1c40f, purple #9b59b6.

MCP Tools

read_annotations

Read all pending annotations. Each annotation includes:

{
  "id": "uuid",
  "type": "arrow | circle | text | freehand | select | textsel",
  "comment": "user feedback text",
  "selector": "div.card:nth-child(1) > button.btn-primary",
  "fallbackSelectors": [
    { "type": "id", "value": "#submit-btn" },
    { "type": "cssPath", "value": "div.card:nth-child(1) > ..." },
    { "type": "contentHash", "value": "Buy Now-a3f8b2c1" }
  ],
  "tagName": "BUTTON",
  "classes": ["btn-primary"],
  "elementText": "Buy Now",
  "contentHash": "Buy Now-a3f8b2c1",
  "position": { "start": {"x":100,"y":200}, "end": {"x":300,"y":400} },
  "color": "#e94560"
}

clear_annotations

Clear all stored annotations. Call after processing feedback.

Selector Fallback Chain

When the agent regenerates the page, CSS selectors may break. Each annotation carries a fallback chain:

1. id — #element-id (most stable)
2. cssPath — div.card:nth-child(1) > button.btn-primary
3. contentHash — Buy Now-a3f8b2c1 (first 40 chars of text + djb2 hash)

The agent should try each fallback in order when resolving elements after page changes.

Standalone Use (Without Extension)

The overlay can be injected into any page via script tag or browser console:

<script src="annotation-overlay.js"></script>

Or via Tandem evaluate / Playwright:

// Tandem
tandem_devtools_evaluate({ function: "..." }) // paste annotation-overlay.js contents

// Playwright
await page.evaluate(fs.readFileSync('annotation-overlay.js', 'utf-8'));

Public API:

__annotationOverlay.activate()    // show toolbar
__annotationOverlay.deactivate()  // hide overlay
__annotationOverlay.serialize()   // → JSON string
__annotationOverlay.clear()       // remove all annotations
__annotationOverlay.submit()      // send to MCP server via direct fetch

Architecture

┌──────────────────────────────────────────────────────┐
│  annotation-overlay.js  (src/, ~700 lines)            │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ Toolbar  │  │  Canvas  │  │  DOM Bridge      │   │
│  │  6 tools │  │  2D ctx  │  │  elementFromPoint │   │
│  │  5 colors│  │  DPR     │  │  CSS selector gen │   │
│  │  Submit  │  │  undo    │  │  contentHash      │   │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘   │
│       │             │                │               │
│       └─────────────┴───────┬────────┘               │
│                             │                         │
│                    ┌────────▼────────┐                │
│                    │  Annotation Model│               │
│                    │  + Serializer   │               │
│                    │  + Fallback     │               │
│                    └────────┬────────┘               │
└─────────────────────────────┼────────────────────────┘
                              │ postMessage
┌─────────────────────────────┼────────────────────────┐
│  Chrome Extension           ▼                         │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │  bridge.js   │  │  service-    │                  │
│  │  (ISOLATED)  │  │  worker.js   │                  │
│  │  inject +    │  │  badge +     │                  │
│  │  relay       │  │  relay       │                  │
│  └──────┬───────┘  └──────┬───────┘                  │
└─────────┼──────────────────┼──────────────────────────┘
          │                  │ HTTP (port 3847)
┌─────────▼──────────────────▼──────────────────────────┐
│  MCP Server (Node.js, single process)                  │
│  ┌──────────────┐  ┌──────────────┐                   │
│  │  Express API │  │  MCP stdio   │                   │
│  │  POST/GET/   │  │  read_       │                   │
│  │  DELETE ann  │  │  clear tools │                   │
│  └──────┬───────┘  └──────┬───────┘                   │
│         └────────┬─────────┘                           │
│         ┌────────▼────────┐                            │
│         │  In-memory Store│                            │
│         └─────────────────┘                            │
└────────────────────────────────────────────────────────┘

Comparison

Configuration

License

MIT — Copyright (c) 2026 gaogao