e kept running into the same problem: we see a bug in the browser, but explaining it to our AI coding agent is painful.
"The third button in the second card, the padding is off, the text is clipped..."
Sound familiar? You see the problem instantly, but translating a visual issue into something an AI agent can act on takes longer than fixing it yourself.
So we built ui-ticket-mcp.
What it does
ui-ticket-mcp is an MCP server that bridges the gap between what you SEE in the browser and what your AI agent sees in code.
You click on the broken element, write a comment like "padding is wrong" or "this text is clipped", and your AI coding agent picks it up with full context:
- CSS computed styles
- DOM structure and attributes
- CSS selectors (unique path to the element)
- Bounding box and position
- Accessibility info
- Sibling elements for context
The agent reads the review, finds the source file, fixes the code, and marks the review as resolved. Full loop — no copy-pasting error descriptions.
How it works
The system has two parts:
1. Review panel (browser side)
A web component (<review-panel>) that you add to your app. It gives you a floating panel where you can:
- Click any element to annotate it
- Drag to select multiple elements
- Write comments with tags (bug, suggestion, question)
- See numbered markers on reviewed elements (red = open, green = resolved)
2. MCP server (agent side)
A Python MCP server that exposes 10 tools to your AI agent:
get_pending_work— all open reviews grouped by page
get_reviews— reviews filtered by page
get_annotated_reviews— reviews with full element metadata
find_source_file— locate the source file for a page
add_review/resolve_review— manage reviews- and more
The agent calls get_pending_work(), gets the reviews with all the element context, and knows exactly what to fix and where.
Setup (2 minutes)
The easy way
Tell your AI agent:
"Add ui-ticket-mcp to the project"
It handles everything — adds the MCP server config and the review panel to your app.
The manual way
Step 1: Add the MCP server
Add this to your .mcp.json:
{
"mcpServers": {
"ui-ticket-mcp": {
"command": "uvx",
"args": ["ui-ticket-mcp"],
"env": {
"PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
No pip install needed — uvx handles it automatically.
Step 2: Add the review panel
Option A — npm:
npm i ui-ticket-panel
import 'ui-ticket-panel';
Option B — CDN script tag (works with any stack):
That's it. Open your app, click the review panel, start annotating.
What the agent sees
When your agent calls get_annotated_reviews, it gets something like this:
{
"page_id": "login",
"text": "Submit button padding is off",
"tag": "bug",
"metadata": {
"tagName": "BUTTON",
"selector": "form > button.btn-primary",
"computedStyles": {
"padding": "4px 8px",
"fontSize": "14px"
},
"boundingBox": { "x": 320, "y": 480, "width": 120, "height": 32 },
"accessibility": { "role": "button", "name": "Submit" }
}
}
The agent doesn't have to guess which element you mean. It has the exact selector, styles, and DOM context to locate the source and fix it.
Works with everything
AI agents: Claude Code, Cursor, Windsurf, or any MCP-compatible agent
Frameworks: React, Angular, Vue, Svelte, plain HTML — the review panel is a framework-agnostic web component
Storage: Reviews are stored in a single SQLite file (.reviews/reviews.db) that you can commit to git and share with your team
What we use it for
- Quick UI bug fixes during development — click, comment, let the agent fix it
- Design review sessions — go through the app, annotate everything, then let the agent batch-fix
- Team collaboration — one person reviews in the browser, the agent resolves the tickets
Links
- Website:
- PyPI:
pip install ui-ticket-mcp
- npm:
npm i ui-ticket-panel
- MCP Registry: registry.modelcontextprotocol.io
We'd love feedback. What's missing? What would make this more useful for your workflow?
SOCIAL SHARE CARD GENERATOR