Skip to main content
Glama
README.md
# visual-feedback-mcp

English | [한국어](README.ko.md)

An MCP server that lets a coding agent show you images in a local browser page and collect your feedback on them. You pick an image, drag boxes over the areas you mean, and write comments or questions. The agent reads them the next time you send a message.

Use it to choose between design options, point out changes on a screenshot, or review results while the agent works.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/annotate-en-dark.png">
  <img alt="Feedback view: two numbered regions on a mobile screen, with a comment for each. Session tabs are at the top." src="docs/screenshots/annotate-en-light.png">
</picture>

## Why it does not wait

Most MCP clients stop a tool call after a fixed time; Codex and Cursor use about 60 seconds. A tool that waits for you to finish reviewing would fail there. So the agent shows the images and ends its turn. You leave feedback at your own pace, then send any message in the chat, and the agent collects everything you submitted.

## Requirements

- Node.js 22 or later
- A browser on the same machine as the MCP client

## Install

```bash
git clone https://github.com/tortle1228/visual-feedback-mcp.git
cd visual-feedback-mcp
npm install --ignore-scripts
```

Register it with your client. Replace `/ABS/PATH` with the absolute path of the clone.

Claude Code:

```bash
claude mcp add -s user visual-feedback -- node /ABS/PATH/src/index.js
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.visual-feedback]
command = "node"
args = ["/ABS/PATH/src/index.js"]
```

Cursor (`~/.cursor/mcp.json`):

```json
{ "mcpServers": { "visual-feedback": { "command": "node", "args": ["/ABS/PATH/src/index.js"] } } }
```

VS Code (`.vscode/mcp.json`):

```json
{ "servers": { "visual-feedback": { "type": "stdio", "command": "node", "args": ["/ABS/PATH/src/index.js"] } } }
```

Only Claude Code has been tested end to end. The other snippets follow each client's documented format.

## Usage

Ask in plain words, for example: "Show me a.png and b.png, I'll pick one."

1. The agent calls `show_images`. Your browser opens the page, or the page you already have open updates. If you already have the page open and the images change, you get a notice (see below).
2. Pick an image and press **Leave feedback**. Drag boxes and write comments if you want, then press **Send**. You can send feedback on several images, several times.
3. When you are done, send any message in the chat. The agent calls `get_feedback` and receives everything you sent.

Things you can do on the page:

- **Zoom** the preview with the buttons at its bottom right, `Ctrl`/`⌘` + scroll (or a trackpad pinch), or the `+`, `-`, and `0` keys. Boxes can be drawn while zoomed in.
- **Review what you sent.** The **Sent feedback** button lists feedback the agent has not collected yet. **Cancel** removes an item. Once the agent collects it, it leaves the list and can no longer be cancelled.
- **Run several agents at once.** Every agent session on your computer shares this one page. Each session gets a tab at the top, named after its working folder. Hover a tab to see when it was last updated. A dot means new images you have not looked at. Feedback in a tab goes only to the session that owns it.
- **Close a tab.** Press **×** on a tab to remove it. If the tab has feedback the agent has not collected, you are asked first, and that feedback is discarded. The agent is told once, the next time it calls `get_feedback`. The tab comes back when the session calls `show_images` again.
- **Notice updates.** Under the question you see when the images were last updated. When the images you are looking at change, a message appears at the top and the image area is outlined for a moment. If the page is in the background, a ● appears before the browser tab's title until you come back.
- **Messages.** Notices such as "Sent" appear at the top. Success messages fade after 4 seconds and errors after 10. Click one to close it.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/view-en-dark.png">
  <img alt="View page: a large preview with three design options in a list on the right. Session tabs and the last update time are above." src="docs/screenshots/view-en-light.png">
</picture>

The page is in Korean when your browser's language is Korean and in English otherwise. It follows your system's light or dark mode.

### Tools

| Tool | Input | Returns |
|---|---|---|
| `show_images` | `question`, and `images`: 1 to 20 items of `{ id, label, path }`. `path` is an absolute path to a PNG, JPEG, or WebP file. | The page URL and whether a browser was opened |
| `get_feedback` | none | Each submission since the last call: a JSON summary and the image. If you closed the session's tab, a note saying so. |

Calling `show_images` again replaces the whole list. If an image keeps its `id`, the page keeps it selected. Closing a tab discards its waiting feedback.

Each submission includes the image as it was when you commented, even if the file changed later. When you drew boxes, the image has them drawn with numbers, and the JSON has each box's position as a fraction of the image size.

## Limits

- The page is served on `127.0.0.1` only, behind a random token in the URL.
- A background process (the daemon) serves the page for all sessions. The first session that needs it starts it, and it exits after 10 minutes with no session connected. It writes its address and an agent key to `~/.visual-feedback-mcp/daemon.json` (mode 0600, in a 0700 folder). The page token is never written to disk. Set `VISUAL_FEEDBACK_STATE_DIR` to use another folder.
- Everything else is kept in memory. When a session ends, or you close its tab, its tab and any feedback the agent has not collected disappear. Stopping the daemon drops everything.
- Up to 20 sessions can have a tab at once.

## Troubleshooting

**The agent does not see the tools.** Most clients load MCP servers when a session starts. Start a new session after registering.

**Updating to a new version.** A running session keeps the code it started with. Have the agent collect pending feedback first, then reconnect the server (in Claude Code: `/mcp`, then reconnect `visual-feedback`). A new version starts its own daemon and page; the old daemon exits on its own once its sessions have ended. Do not mix old and new versions: a session on each starts its own daemon, and they keep replacing the daemon's address file. Reconnect every session, then close the old page.

**No browser opens.** The tool result includes the URL; open it yourself. Set `VISUAL_FEEDBACK_NO_OPEN=1` in the server's environment to never open a browser.

## Development

```bash
npm test
```

`docs/mockups/app.html` is the fictional app used for the screenshots.

## License

[MIT](LICENSE)