# Browser Feedback MCP for Claude Code

A Model Context Protocol (MCP) server that enables visual browser feedback collection directly into Claude Code. Users can point at elements in their browser and send annotated feedback that Claude can act on immediately.

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│  Your Web App (localhost:3000)                                  │
│                                                                 │
│  [Widget delivered by browser extension]                        │
│                                                                 │
│                                        ┌──────────────────┐     │
│       Your App UI                      │ Add annotation   │     │
│                                        └──────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
                             │
                        WebSocket
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  browser-feedback-mcp server (localhost:9877)                   │
└─────────────────────────────────────────────────────────────────┘
                             │
                        MCP Protocol
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  Claude Code                                                    │
│                                                                 │
│  "Let me annotate" → installs widget → waits → receives feedback│
└─────────────────────────────────────────────────────────────────┘
```

## Installation

### 1. Install the MCP Server

```bash
# Clone the repository
git clone https://github.com/itk-dev/mcp-claude-code-browser-feedback.git
cd mcp-claude-code-browser-feedback

# Install dependencies
npm install
```

### 2. Add to Claude Code

```bash
claude mcp add --scope user browser-feedback node /path/to/mcp-claude-code-browser-feedback/src/server.js
```

Or add manually to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "browser-feedback": {
      "command": "node",
      "args": ["/path/to/mcp-claude-code-browser-feedback/src/server.js"],
      "env": {
        "FEEDBACK_PORT": "9877"
      }
    }
  }
}
```

### 3. Install the Browser Extension

The extension delivers the widget to any tab with a single toggle — no changes to your project's files. Ask Claude to run the `setup_extension` tool, which opens the extension folder and shows instructions, or install manually:

#### Chrome

1. Navigate to `chrome://extensions`
2. Enable **Developer Mode** (toggle in top right)
3. Click **Load unpacked**
4. Select the `extension/` folder from this repository

#### Firefox

1. Navigate to `about:debugging#/runtime/this-firefox`
2. Click **Load Temporary Add-on...**
3. Select `extension/manifest.json` from this repository

## Usage

### Basic Workflow

Turn the widget on for your app's tab via the extension:

1. Click the extension icon in your browser toolbar
2. Toggle the widget ON for the current tab — the "Add annotation" button appears without any file changes
3. Toggle OFF to cleanly remove the widget

The extension connects to the MCP server at `http://localhost:9877` by default (configurable in the popup) and auto-matches the tab to your Claude Code session by project URL.

Then tell Claude you want to show it something:

```
You: There's a bug with the checkout button, let me show you

Claude: [Calls: wait_for_browser_feedback]
        Click "Add annotation" in your browser, then click on the
        problematic element.

--- You use the browser widget to select the button ---

Claude: I received your feedback! I can see:

        📸 Screenshot captured
        🎯 Element: <button class="checkout-btn" disabled>
        📝 Your description: "Button stays disabled even with items in cart"
        🔴 Console Error: "TypeError: Cannot read property 'items' of null"

        Let me look at the checkout code and fix this...
```

### Multiple Annotations

You can submit multiple feedback items at once:

```
You: I have several issues to show you

Claude: [Calls: wait_for_multiple_feedback]
        Submit all your annotations, then click "Done" when finished.

--- You submit 3 feedback items, then click Done ---

Claude: I received 3 feedback items. Let me address each one...
```

### Offline Export

The widget works without a server connection. When offline, feedback is stored locally and can be exported:

- **Export Markdown** - Click "Pending" to open the queue, then "Export Markdown" to download a `.md` file
- **Create GitHub Issue** - Click "Create GitHub Issue" to open a pre-filled issue in your browser (you'll be prompted for the repository on first use, stored in localStorage)

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `setup_extension` | Help install the browser extension (opens folder + instructions) |
| `wait_for_browser_feedback` | Block until user submits single feedback |
| `wait_for_multiple_feedback` | Wait for multiple feedback items (user clicks Done when finished) |
| `get_pending_feedback` | Get any feedback that's been submitted |
| `preview_pending_feedback` | Preview pending feedback summaries without consuming them |
| `delete_pending_feedback` | Delete a specific pending feedback item by ID |
| `get_connection_status` | Check if browser clients are connected |
| `request_annotation` | Prompt the user to annotate something specific |
| `open_in_browser` | Open project URL in default browser (auto-detects from config files) |
| `install_widget` | **Deprecated** — auto-inject the widget script into your app's HTML |
| `uninstall_widget` | **Deprecated** — remove the injected widget script |
| `get_widget_snippet` | **Deprecated** — get the script tag for manual installation |

### Script Installation (deprecated)

> **Deprecated:** Script installation modifies your project's HTML, which produces git noise and risks accidental commits. Use the browser extension instead. This path is kept only for environments where installing a browser extension is genuinely blocked, and will be removed in a future major release ([#48](https://github.com/itk-dev/mcp-claude-code-browser-feedback/issues/48)).

Add this script tag to your HTML:

```html
<script src="http://localhost:9877/widget.js"></script>
```

The `install_widget` / `uninstall_widget` tools still automate injecting and removing the tag (with hostname gating via `dev_only` / `allowed_hostnames` and auto-detection of common entry points like `public/index.html`), and `get_widget_snippet` returns the tag with your session ID.

## Widget Features

- **Draggable dialog** - Move the feedback panel anywhere on screen
- **Minimizable** - Collapse the panel to just the header bar
- **Collapsible element details** - Technical info hidden by default
- **Screenshot capture** - Automatic viewport capture using html2canvas (bundled)
- **Console log capture** - Includes recent console messages
- **Multi-feedback mode** - Submit multiple annotations before sending to Claude
- **Shadow DOM isolation** - Widget styles are isolated from host page CSS
- **Offline mode** - Annotate elements even without a server connection; feedback is stored locally
- **Export to Markdown** - Download pending feedback as a structured Markdown file
- **Export to GitHub Issue** - Open a pre-filled GitHub issue directly from the widget

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FEEDBACK_PORT` | `9877` | Port for HTTP/WebSocket server |

## Screenshot Capture

The widget automatically captures viewport screenshots using html2canvas, which is bundled with the MCP server and loaded on demand. No extra setup is needed.

## Troubleshooting

### Widget shows "disconnected" (gray button)

- Make sure the MCP server is running (check with `/mcp` in Claude Code)
- Check that the port (9877) is not in use by another process
- Try restarting Claude Code

### Port already in use

The server handles this gracefully - the MCP tools will still work, but you'll need to free the port for the browser widget:

```bash
# Find and kill the process using port 9877
lsof -i :9877
kill <PID>
```

Or use a different port:

```bash
FEEDBACK_PORT=9878 node src/server.js
```

### No feedback received

- Check browser console for WebSocket errors
- Ensure the widget script loaded correctly
- Verify the MCP server logs for connection info

## Security Notes

- The widget only connects to `localhost`
- No data is sent to external servers
- All communication stays on your machine
- **Note:** The HTTP/WebSocket server listens on all interfaces (`0.0.0.0`) by default. If you need to restrict this, use a firewall or bind to a specific interface via a reverse proxy.

## Development

```bash
npm test          # Unit tests (vitest)
npm run test:e2e  # Widget end-to-end test (requires a Playwright Chromium)
```

The e2e test drives the widget in a headless browser to cover annotation-mode
behavior the unit suite can't reach (iframe selection, Escape handling,
shadow DOM focus). It looks for a Chromium in the Playwright browser cache;
run `npx playwright install chromium` once, or point `PLAYWRIGHT_CHROMIUM`
at a browser executable.

## License

MIT