ui-ticket-mcp

Human-to-AI code review bridge.Review UI prototypes directly in the browser, then let AI agents read your feedback and fix the code automatically.

You click on elements, write review comments like "This button should be blue" or "The spacing is wrong here", and your AI coding agent (Claude Code, Codex, Cursor, etc.) picks them up via MCP and resolves them - with full context about which element you pointed at, its CSS, position, and surrounding DOM.

journey title Using ui-ticket-mcp section Review Open your app in browser: 5: You Click on a broken element: 4: You Write what's wrong: 5: You section AI resolves Agent reads your feedback: 3: AI Agent finds the source file: 4: AI Agent fixes the code: 5: AI Review disappears: 5: You, AI

One Python process handles everything - MCP protocol for the agent (stdio) and REST API for the browser UI (HTTP). Reviews are stored in a SQLite database inside your project.

Add to your project's.mcp.json(Claude Code, Codex, Cursor, etc.):

{ "mcpServers": { "ui-ticket-mcp": { "command": "uvx", "args": ["ui-ticket-mcp"], "env": { "PROJECT_ROOT": "/path/to/your/project", "REVIEW_PORT": "3200" } } } }

Restart the agent.uvxdownloads and runs the package automatically - no manual install needed.

Alternative:pip install ui-ticket-mcp, then use"command": "ui-ticket-mcp"instead ofuvx.

When the MCP server starts, it also launches a REST API onhttp://localhost:3200(or your customREVIEW_PORT) for the browser UI.

Important:The API always runslocally(localhost). The websitehttps://uiticket.0ics.ai/is the landing page only — it is NOT an API endpoint. Always usehttp://localhost:{PORT}/apias theapi-url.

In your app's entry file (e.g.main.ts,index.tsx):

import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel();

<review-panel api-url="http://localhost:3200/api"></review-panel>

That's it. Works inany framework- Angular, React, Vue, Svelte, or plain HTML. It's a standard Web Component. ForSSR frameworks(Next.js, Nuxt, SvelteKit) see theFramework Examplessection — you need a dynamic import on the client side.

<script type="module" src="https://unpkg.com/ui-ticket-panel/dist/bundle.js"></script> <review-panel api-url="http://localhost:3200/api"></review-panel>

graph LR Agent[AI Agent] Browser[Reviewer - Browser] Server[ui-ticket-mcp] DB[(SQLite)] Agent <-->|stdio MCP| Server Browser <-->|HTTP REST :3200| Server Server --- DB

- MCP(stdio) - Your agent framework starts it automatically. 10 tools for AI agents to read, resolve, and manage reviews.
- REST API(HTTP :3200) - Starts in background, serves the browser review UI. CORS enabled for all origins.
- SQLite(WAL mode) - Concurrent readers + 1 writer, 5s busy timeout. Database lives inside your project at.reviews/reviews.db.

Overview of all pages with review counts.

Page | Open | Resolved | Total ------------ | ---- | -------- | ----- user-profile | 3 | 1 | 4 dashboard | 0 | 2 | 2

List review comments. Optionally filtered by page. Shows status, tag, element context, and reply chains.

[#1] [OPEN] [bug] user-profile - alice: The header spacing is off → Element: Heading 2 'User Profile' | Selector: h2.page-title [#2] [RESOLVED] user-profile - bob: Button color should be blue

Returns only reviews that have element annotation metadata. Includes element name, CSS selector, full DOM path, selected text, accessibility info - everything the agent needs to locate and understand the annotated element.

All open reviews grouped by page - the agent's "todo list".

## user-profile (2 open) - #1 [bug] (alice): The header spacing is off - #3 [suggestion] (alice): Add hover state to buttons ## dashboard (1 open) - #4 (bob): Chart labels are truncated

add_review(page_id, author, text, tag?, metadata?, parent_id?)

Create a new review. Supports tags, annotation metadata (JSON), and threading viaparent_id.

Mark a review as resolved. Setsresolved_attimestamp andresolved_by(defaults to"agent").

Reopen a previously resolved review. Clears resolution info.

Resolve all open reviews on a page at once. ReturnsResolved 3 review(s) on user-profile.

Find source files inPROJECT_ROOTmatching a page ID. Searches by kebab-case, CamelCase, and glob patterns. Skipsnode_modules,dist,.git.

Found 3 file(s) for 'user-profile': - src/app/user-profile/user-profile.component.ts - src/app/user-profile/user-profile.component.html - src/app/shared/UserProfile.ts

Returns the full setup guide (MCP config, REST API, browser UI). Useful when the agent needs to help set up the review system in a new project.

graph TD A["get_pending_work()"] -->|See what needs attention| B["get_annotated_reviews(page)"] B -->|Get element metadata for context| C["find_source_file_tool(page)"] C -->|Locate the source files| D["Read & edit the code"] D --> E{Resolve} E -->|Single| F["resolve_review(id)"] E -->|All on page| G["batch_resolve(page)"]

All endpoints under/api. CORS enabled for all origins.

Reviews are stored in SQLite inside your project at{PROJECT_ROOT}/.reviews/reviews.db. The database is auto-created on first run.
- REVIEW_DB_PATHenv var (explicit override)
- PROJECT_ROOT/.reviews/reviews.db(default)
- ./reviews.db(fallback)

reviews ( id INTEGER PRIMARY KEY, page_id TEXT NOT NULL, author TEXT DEFAULT 'anonymous', text TEXT NOT NULL, status TEXT DEFAULT 'open', -- 'open' | 'resolved' created_at TEXT NOT NULL, -- ISO 8601 resolved_at TEXT, resolved_by TEXT, metadata TEXT, -- JSON: annotation context tag TEXT DEFAULT 'general', -- 'general' | 'bug' | 'suggestion' | 'question' parent_id INTEGER REFERENCES reviews(id) -- threaded replies )

When a review is created via annotation, themetadatafield contains:

{ "element": "Button 'Save'", "selector": "button.btn-primary", "boundingBox": { "x": 100, "y": 200, "width": 80, "height": 40 }, "selectedText": "Click to save", "cssClasses": "btn btn-primary active", "nearbyText": "Save your work | [after:] Cancel", "nearbyElements": "Parent: form.editor (5 children) | Siblings: input, button.secondary", "computedStyles": "color: #fff, background: #3b82f6, border-radius: 4px", "fullPath": "body > div#app > div.modal > form > button", "accessibility": "role=\"button\", tabindex=\"0\", focusable", "isMultiSelect": false, "url": "http://localhost:4200/user-profile" }

This metadata gives the AI agent precise context about what you annotated - which element, where it is, what it looks like, and how to find it in the DOM.

The panel needs to know which page the user is on, so it can show and file reviews for that specific page. There are two modes:

When nopage-idattribute is set, the panel derives the page identifier from the URL pathname:

The panel also listens for SPA navigation events (pushState,replaceState,popstate) and automatically reloads reviews when the route changes. This means it works out of the box with client-side routing in React Router, Vue Router, Angular Router, Next.js, etc.

<!-- Auto-detection: no page-id attribute needed --> <review-panel api-url="http://localhost:3200/api"></review-panel>

If you need to control the page ID yourself (e.g. your pages don't map cleanly to URL paths), set thepage-idattribute:

<review-panel api-url="http://localhost:3200/api" page-id="dashboard"></review-panel>

Important:These two modes are mutually exclusive. Whenpage-idis set, auto-detection is completely disabled — the panel will NOT react to route changes. Do not combine both.

const panel = document.querySelector('review-panel'); // Change page without reloading panel.setPageId('dashboard');

In your entry file (e.g.main.ts,main.js):

import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel();

<review-panel api-url="http://localhost:3200/api"></review-panel>

<script type="module" src="https://unpkg.com/ui-ticket-panel/dist/bundle.js"></script> <review-panel api-url="http://localhost:3200/api"></review-panel>

import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel(); function App() { return <review-panel api-url="http://localhost:3200/api" />; }

<template> <review-panel api-url="http://localhost:3200/api"></review-panel> </template> <script setup> import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel(); </script>

// app.config.ts import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel(); // component - add CUSTOM_ELEMENTS_SCHEMA @Component({ schemas: [CUSTOM_ELEMENTS_SCHEMA], template: <review-panel api-url="http://localhost:3200/api"></review-panel> })

<script> import { defineReviewPanel } from 'ui-ticket-panel'; defineReviewPanel(); </script> <review-panel api-url="http://localhost:3200/api"></review-panel>

Web Components usewindowandHTMLElementwhich don't exist during server-side rendering. You must load the panel dynamically on the client side:

// components/ReviewPanel.tsx 'use client'; import { useEffect } from 'react'; export default function ReviewPanel() { useEffect(() => { import('ui-ticket-panel').then(m => m.defineReviewPanel()); }, []); return <review-panel api-url="http://localhost:3200/api" />; }

// app/layout.tsx import ReviewPanel from './components/ReviewPanel'; export default function RootLayout({ children }) { return ( <html> <body> {children} <ReviewPanel /> </body> </html> ); }

<template> <ClientOnly> <review-panel api-url="http://localhost:3200/api"></review-panel> </ClientOnly> </template> <script setup> import { onMounted } from 'vue'; onMounted(async () => { const { defineReviewPanel } = await import('ui-ticket-panel'); defineReviewPanel(); }); </script>

<script> import { onMount } from 'svelte'; onMount(async () => { const { defineReviewPanel } = await import('ui-ticket-panel'); defineReviewPanel(); }); </script> <review-panel api-url="http://localhost:3200/api"></review-panel>

Found a bug or have a feature request?Open an issueon this repository.

CC BY-NC 4.0 — free for study, research, and non-commercial use. SeeLICENSEfor details.

Help agents automatically write and test stories for your UI components