ui-ticket-mcp

ui-ticket-mcp

人間から AI へのコードレビューの橋渡しです。 ブラウザーで UI プロトタイプを直接レビューし、AI エージェントにフィードバックを読み取らせて、コードを自動修正できます。

要素をクリックして、「このボタンは青色にしてください」や「ここの間隔が正しくありません」といったレビューコメントを書き込むと、AI コーディングエージェント（Claude Code、Codex、Cursor など）が MCP 経由でコメントを取得し、指摘した要素、その CSS、位置、周辺の 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

1 つの Python プロセスですべてを処理します。エージェント向けの MCP プロトコル（stdio）とブラウザー UI 向けの REST API（HTTP）です。レビューはプロジェクト内の SQLite データベースに保存されます。

---

クイックスタート

1. AI エージェントに接続する

プロジェクトの .mcp.json に追加します（Claude Code、Codex、Cursor など）。

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

エージェントを再起動します。uvx がパッケージを自動でダウンロードして実行するため、手動でインストールする必要はありません。

代替方法： pip install ui-ticket-mcp を実行し、uvx の代わりに "command": "ui-ticket-mcp" を使用します。

MCP サーバーの起動時に、ブラウザー UI 向けの REST API も http://localhost:3200（またはカスタムの REVIEW_PORT）で起動します。

重要： API は常にローカル（localhost）で実行されます。ウェブサイト https://uiticket.0ics.ai/ はランディングページのみで、API エンドポイントではありません。api-url には必ず http://localhost:{PORT}/api を使用してください。

2. アプリにブラウザー UI を追加する

npm install ui-ticket-panel

アプリのエントリーファイル（例：main.ts、index.tsx）に追加します。

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

次に、ルートテンプレートに追加します。

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

これだけです。Angular、React、Vue、Svelte、プレーンな HTML など、あらゆるフレームワークで動作します。標準的な Web Component です。SSR フレームワーク（Next.js、Nuxt、SvelteKit）については、フレームワークの例のセクションをご覧ください。クライアント側で動的インポートが必要です。

バンドラーを使わない場合：CDN を使用する

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

バンドルを読み込むと、<review-panel> 要素が自動的に登録されます。npm のインストールも、ビルド手順も不要です。

3. レビューを開始する

ブラウザーでアプリを開きます。右下にフローティングチャットボタンが表示されます。クリックしてレビューパネルを開くか、Alt+A を押して注釈モードに切り替え、要素を直接クリックします。

---

ブラウザー UI の機能

レビューパネル

フローティングパネルで、すべてのレビューを閲覧、絞り込み、管理できます。

• フィルタータブ - オープン、解決済み、すべてのレビューを切り替えます
• 検索 - すべてのレビューコメントを全文検索します
• タグフィルター - カテゴリ（general、bug、suggestion、question）で絞り込みます
• レビューごとの操作 - 解決、再オープン、削除、返信、要素のハイライト
• スレッド形式の返信 - レビューに返信して、やり取りを続けられます
• 手動レビュー用フォーム - 注釈なしでレビューを書き込めます（Ctrl+Enter で送信）
• バッジカウンター - フローティングボタンに未解決レビューの件数を表示します

注釈システム

注釈システムを使うと、特定の要素を指定してレビューを付けられます。

• クリックして注釈 - Alt+A（またはターゲットボタン）を押してから、任意の要素をクリックします
• ドラッグして複数選択 - クリックしてドラッグし、複数の要素を含む範囲を選択します
• ホバープレビュー - マウスを動かすと、要素の識別情報をリアルタイムで確認できます
• スマートポップアップ - 空きスペースに応じて、要素の上または下に表示されます

要素に注釈を付けると、AI エージェントが指定された対象を正確に理解するのに役立つ詳細なメタデータが取得されます。

取得データ	例
要素名	Button 'Save'、Input[email] 'Your email'、Heading 2 'Features'
CSS セレクター	#main-header、div.card > button.primary:nth-of-type(2)
境界ボックス	ピクセル単位の位置とサイズ
近くのテキスト	要素自体のテキスト＋コンテキスト用の前後の兄弟要素のテキスト
選択したテキスト	注釈を付ける前にテキストを選択している場合
CSS クラス	フィルタリング済み（フレームワークが生成したハッシュを除外）
計算済みスタイル	色、背景、フォント、境界線、パディング（要素の種類に応じて最適化）
DOM パス全体	body > div#app > section.content > div.card > button
アクセシビリティ	ARIA ロール、ラベル、tabindex、フォーカス可否
兄弟要素のコンテキスト	親タグ、子要素数、隣接する兄弟要素のタグ

マーカーバッジ

注釈付きのレビューには、注釈対象の要素の横に番号付きバッジがページ上に表示されます。

• 単一のレビュー - レビュー ID を示す円形のバッジで、未解決は赤、解決済みは緑です
• レビューの重なり（同じ要素に3件以上） - 件数を示すピル型バッジで、未解決と解決済みの割合をグラデーションで表示します
• バッジをクリック - パネルでレビューを開きます
• バッジを削除 - ホバー時に表示される X ボタンで削除します
• ツールチップ - ホバーすると、投稿者、要素名、コメントのプレビューを確認できます

タグ

すべてのレビューにカテゴリのタグを付けられます。

タグ	色	用途
general	インディゴ	一般的なフィードバック（デフォルト）
bug	赤	不具合の報告
suggestion	緑	改善案
question	アンバー	明確化が必要な事項

キーボードショートカット

ショートカット	操作
Alt+A	注釈モードの切り替え
Ctrl+Enter	レビューまたは返信を送信
Escape	ポップアップを閉じる／注釈モードを終了

---

アーキテクチャ

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） - エージェントのフレームワークによって自動的に起動されます。AI エージェントがレビューを読み取り、解決し、管理するための10個のツールを提供します。
• REST API（HTTP :3200） - バックグラウンドで起動し、ブラウザのレビュー UI を提供します。すべてのオリジンで CORS が有効です。
• SQLite（WAL モード） - 読み取りは同時実行可能で、書き込みは1つまでです。ビジー状態のタイムアウトは5秒です。データベースはプロジェクト内の .reviews/reviews.db に保存されます。

---

MCP ツール

AI エージェントが利用できる10個のツール：

get_review_summary()

レビュー件数とともに、すべてのページの概要を表示します。

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

get_reviews(page_id?: str)

レビューコメントを一覧表示します。ページによる絞り込みも可能です。ステータス、タグ、要素のコンテキスト、返信スレッドを表示します。

[#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

get_annotated_reviews(page_id?: str)

要素の注釈メタデータがあるレビューのみを返します。要素名、CSS セレクター、DOM パス全体、選択したテキスト、アクセシビリティ情報など、注釈対象の要素を特定して理解するためにエージェントが必要とするすべての情報を含みます。

get_pending_work()

ページごとにグループ化された、すべての未解決レビューです。エージェントの「ToDo リスト」として利用できます。

## 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?)

新しいレビューを作成します。タグ、注釈メタデータ（JSON）、parent_id によるスレッド形式の返信に対応しています。

resolve_review(review_id, resolved_by?)

レビューを解決済みとしてマークします。resolved_at タイムスタンプと resolved_by を設定します（デフォルトは "agent" です）。

reopen_review(review_id)

解決済みのレビューを再開します。解決情報を消去します。

batch_resolve(page_id, resolved_by?)

ページ上の未解決レビューをすべて一度に解決します。Resolved 3 review(s) on user-profile. を返します。

find_source_file_tool(page_id)

PROJECT_ROOT 内でページ ID に一致するソースファイルを検索します。kebab-case、CamelCase、glob パターンで検索します。node_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

get_setup_guide()

セットアップガイド全体（MCP 設定、REST API、ブラウザー UI）を返します。新しいプロジェクトでレビューシステムをセットアップする際に、エージェントが支援する必要がある場合に便利です。

エージェントの一般的なワークフロー

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)"]

---

REST API

すべてのエンドポイントは /api 配下にあります。すべてのオリジンで CORS が有効です。

レビュー

Method	Endpoint	Description
GET	/api/reviews/summary	ページごとの概要（未解決／解決済みの件数）
GET	/api/reviews	すべてのレビュー（新しい順）
GET	/api/reviews/{page_id}	ページのレビュー。クエリ：?status=open|resolved、?tag=bug|suggestion|...
POST	/api/reviews/{page_id}	レビューを作成
PATCH	/api/review/{id}	レビューを更新（ステータス、テキスト、タグ、メタデータ）
DELETE	/api/review/{id}	レビューを完全に削除

返信

Method	Endpoint	Description
GET	/api/review/{id}/replies	レビューへのすべての返信を取得（時系列順）
POST	/api/reviews/{page_id}	返信を作成（本文に parent_id を含めます）

POST 本文

Field	Type	Default	Description
text	string	-	レビューコメント（必須）
author	string	"anonymous"	レビュアー名
tag	string	"general"	"general"、"bug"、"suggestion"、または "question"
metadata	object	-	注釈のコンテキスト（要素、セレクター、スタイルなど）
parent_id	integer	-	スレッド形式の返信の親レビュー ID

PATCH 本文

Field	Type	Description
status	"open" | "resolved"	解決時には resolved_at と resolved_by が自動設定されます
text	string	更新後のコメントテキスト
tag	string	更新後のタグ
resolved_by	string	解決したユーザー（API 経由ではデフォルトで "user"、MCP 経由では "agent"）
metadata	object	更新後の注釈メタデータ

---

データベース

レビューは、プロジェクト内の {PROJECT_ROOT}/.reviews/reviews.db にある SQLite に保存されます。初回実行時にデータベースが自動作成されます。

.reviews/ ディレクトリには以下が含まれます。

File	Purpose
reviews.db	SQLite データベース（チームでレビューを共有するには git にコミットします）
.gitkeep	ディレクトリが追跡対象になるようにします
.gitignore	WAL の一時ファイル（*.db-wal、*.db-shm）を無視します

パスの解決順序：

1. REVIEW_DB_PATH 環境変数（明示的な上書き）
2. PROJECT_ROOT/.reviews/reviews.db（デフォルト）
3. ./reviews.db（フォールバック）

スキーマ

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
)

注釈メタデータ（JSON）

注釈を使ってレビューを作成すると、metadata フィールドには以下が含まれます。

{
  "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"
}

このメタデータにより、AI エージェントは注釈の対象（どの要素か、どこにあるか、どのように見えるか、DOM 内でどのように見つけるか）について、正確なコンテキストを把握できます。

---

Web コンポーネントの属性

Attribute	Required	Description
api-url	はい	REST API のベース URL（例：http://localhost:3200/api）
page-id	いいえ	レビューを絞り込むための明示的なページ識別子。省略した場合は自動検出されます（推奨）

ページの識別

パネルがそのユーザーの表示中ページを把握し、該当ページのレビューを表示・登録できるようにする必要があります。方法は 2 種類あります。

自動検出（推奨）

page-id 属性が設定されていない場合、パネルは URL のパス名からページ識別子を導出します。

URL	Page ID
/	home
/analytics	analytics
/settings	settings
/user/profile	user/profile

また、パネルは SPA のナビゲーションイベント（pushState、replaceState、popstate）を監視し、ルートが変更されるとレビューを自動的に再読み込みします。そのため、React Router、Vue Router、Angular Router、Next.js などのクライアントサイドルーティングで、そのまま動作します。

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

明示的なページ ID

ページ ID を自分で制御する必要がある場合（ページと URL パスがきれいに対応しない場合など）は、page-id 属性を設定します。

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

重要： この 2 つのモードは同時に使用できません。page-id を設定すると、自動検出は完全に無効になります。パネルはルートの変更に反応しなくなります。両方を組み合わせないでください。

プログラム API

const panel = document.querySelector('review-panel');

// Change page without reloading
panel.setPageId('dashboard');

---

パッケージ

パッケージ	レジストリ	説明
ui-ticket-mcp	PyPI	Python MCP サーバー ＋ REST API
ui-ticket-panel	npm	<review-panel> Web コンポーネント
ui-ticket-core	npm	フレームワークに依存しないコア：型、API クライアント、リアクティブストア、注釈エンジン

---

環境変数

変数	デフォルト	説明
PROJECT_ROOT	-	レビュー対象プロジェクトのルート。DB は {PROJECT_ROOT}/.reviews/ に自動作成されます
REVIEW_DB_PATH	(auto)	DB パスを明示的に上書きします。PROJECT_ROOT より優先されます
REVIEW_PORT	3200	REST API サーバーのポート

---

フレームワークの使用例

バンドラーを使用する場合

エントリーファイル（例：main.ts、main.js）で次を実行します。

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

続いて、HTML に次を記述します。

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

プレーン HTML（バンドラーなし／CDN）

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

React

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

function App() {
  return <review-panel api-url="http://localhost:3200/api" />;
}

Vue

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

<script setup>
import { defineReviewPanel } from 'ui-ticket-panel';
defineReviewPanel();
</script>

Angular

// 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>`
})

Svelte

<script>
  import { defineReviewPanel } from 'ui-ticket-panel';
  defineReviewPanel();
</script>

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

Next.js（SSR）

Web コンポーネントが使用する window と HTMLElement は、サーバーサイドレンダリング中には存在しません。クライアント側でパネルを動的に読み込む必要があります。

// 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>
  );
}

Nuxt（SSR）

<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>

SvelteKit（SSR）

<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>

---

問題の報告とフィードバック

バグを見つけた場合や機能のリクエストがある場合は、このリポジトリで問題を報告してください。

---

ライセンス

CC BY-NC 4.0 — 学習、研究、非営利目的であれば無料で利用できます。詳細はLICENSEをご覧ください。

---

Šimon Cmar、Ladislav Sopko、Lorenzo Leoni によって制作されました