Uianalyzermcp

🚀 UI Analyzer MCP Server

このMCP（Model Context Protocol）サーバーは、ウェブサイトのUIを分析し、AIコーディングアシスタントに正確な修正指示を提供します。GitHub CopilotやCursorなどのエージェント型コードIDEを使用する際の「UI更新の混乱」の問題を解決するように設計されています。

🚀 クイックスタート

このサーバーを使用することで、ウェブサイトのUIを分析し、AIコーディングアシスタントに正確な修正指示を提供できます。以下の手順でサーバーをセットアップしてください。

✨ 主な機能

• ライブUI分析 - Playwrightを使用して実際のウェブサイトをレンダリングし、検査します。
• スマートクエリ解釈 - 「ナビゲーションバーが壊れている」などの曖昧な不満を理解します。
• 正確な修正指示 - 特定のCSSセレクターとプロパティの変更を生成します。
• 技術検出 - React、Vue、Angular、Next.js、Tailwind、Bootstrapなどを識別します。
• レスポンシブテスト - モバイル、タブレット、デスクトップのビューポートでUIを比較します。
• アクセシビリティ分析 - アクセシビリティツリーを抽出し、セマンティックな理解を支援します。

問題点

AIコーディングアシスタントを使用してウェブサイトのUIを構築または更新する場合、結果が混乱することがあります。

• レイアウトが予期せず崩れる
• 要素が重なったり、位置がずれたりする
• 間隔が不整合になる
• レスポンシブデザインが崩れる

ユーザーは、「ナビゲーションバーが壊れている」や「ヒーローセクションがおかしい」など、何が問題なのかを正確に説明するのが難しいことが多いです。これらの曖昧な説明では、AIが必要なCSSやHTMLの変更を理解するのに役立ちません。

解決策

このMCPサーバーは、以下の方法でこのギャップを埋めます。

1. ライブウェブサイトの分析 - Playwrightを使用して実際のUIをレンダリングし、検査します。
2. 技術スタックの検出 - フレームワーク（React、Next.js、Vue）とCSSライブラリ（Tailwind、Bootstrap）を識別します。
3. UI要素の特定 - ナビゲーションバー、ヘッダー、フッター、ヒーロー、ボタン、フォームなどを見つけます。
4. 問題の検出 - レイアウトの問題、オーバーフロー、z-indexの衝突、アクセシビリティの問題を見つけます。
5. 曖昧なクエリの解釈 - 「ヘッダーが乱れている」という意味を理解します。
6. フレームワーク対応の修正指示の生成 - 検出された技術スタックに合わせた特定のCSSセレクター、プロパティの変更、およびコードスニペットを提供します。

📦 インストール

前提条件

• Python 3.13以上
• uvパッケージマネージャー

セットアップ

# リポジトリをクローンする
git clone https://github.com/0x-Professor/UIAnalyzerMCP.git
cd UIAnalyzerMCP

# 依存関係をインストールする
uv sync

# Playwrightブラウザをインストールする
uv run playwright install chromium

💻 使用例

サーバーの起動

# 直接実行する
uv run python server.py

# またはMCP CLIを使用する
uv run mcp run server.py

# インスペクターを使用した開発用
uv run mcp dev server.py

VS Code / GitHub Copilotの設定

VS Codeのsettings.jsonまたはMCP設定に以下を追加してください。

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/UIAnalyzerMCP"
    }
  }
}

Cursor IDEの設定

CursorのMCP設定（~/.cursor/mcp.jsonまたはプロジェクトの.cursor/mcp.json）に以下を追加してください。

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/UIAnalyzerMCP"
    }
  }
}

Claude Desktopの設定

Claude Desktopの設定ファイルに以下を追加してください。 Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ui-analyzer": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "C:\\path\\to\\UIAnalyzerMCP"
    }
  }
}

利用可能なツール（合計8つ）

analyze_page

ウェブページの完全なUI分析を行います。要素、問題、アクセシビリティツリー、DOM構造、およびスクリーンショットを返します。

analyze_page(url="http://localhost:3000", query="the navbar is broken")

get_fix_instructions

混乱したUIを修正するための主要なツールです。ユーザーの曖昧な不満を解釈し、正確な修正指示を生成します。

get_fix_instructions(
    url="http://localhost:3000",
    user_complaint="the hero section looks weird and buttons are not aligned"
)

返される内容:

• 解釈された問題の説明
• CSSセレクター付きの影響を受ける要素
• プロパティの変更を含む順序付けられた修正指示
• 適用する完全なCSS変更
• 追加の推奨事項

get_screenshot

オプションで要素を強調表示したスクリーンショットをキャプチャします。

get_screenshot(url="http://localhost:3000", element_type="navbar")
get_screenshot(url="http://localhost:3000", highlight_selector=".hero-section")

get_element_details

特定のUI要素タイプに関する詳細情報を取得します。

get_element_details(url="http://localhost:3000", element_type="button")

get_accessibility_snapshot

セマンティック構造を理解するために、YAML形式でアクセシビリティツリーを取得します。

get_accessibility_snapshot(url="http://localhost:3000")

get_dom_overview

簡略化されたDOM構造の概要を取得します。

get_dom_overview(url="http://localhost:3000", max_depth=5)

compare_viewports

異なる画面サイズでUIを比較し、レスポンシブな問題を特定します。

compare_viewports(url="http://localhost:3000")

get_tech_stack

ウェブページで使用されている技術スタック（フレームワーク、ライブラリ、CSSアプローチ）を検出します。フレームワーク固有の修正ガイダンスを返します。

get_tech_stack(url="http://localhost:3000")

返される内容:

• 主要なフレームワーク（React、Vue、Angular、Svelteなど）
• メタフレームワーク（Next.js、Nuxt、Remix、Gatsby、Astro）
• CSSアプローチ（Tailwind、Bootstrap、CSS Modules、styled-components）
• UIライブラリ（shadcn/ui、Material UI、Chakra UI、Ant Design）
• フレームワーク固有の修正推奨事項

サポートされる技術検出

JavaScriptフレームワーク

• React、Vue、Angular、Svelte、Solid、Preact
• jQuery、Alpine.js、HTMX

メタフレームワーク

• Next.js、Nuxt、Remix、Gatsby、Astro、SvelteKit、Vite

CSSフレームワークとライブラリ

• Tailwind CSS、Bootstrap、Bulma、Foundation
• shadcn/ui、Material UI、Chakra UI、Ant Design、Radix UI

CSSアプローチ

• CSS Modules、styled-components、Emotion
• インラインスタイル、CSS変数、Sass/SCSS

例のワークフロー

1. ユーザーが開発サーバーを起動します: npm run dev
2. ユーザーがAIに「ナビゲーションバーが乱れており、ヒーローセクションの間隔がおかしい」と伝えます。
3. AIがget_fix_instructionsを使用します:

get_fix_instructions(
    url="http://localhost:3000",
    user_complaint="The navbar is messed up and the hero section has weird spacing"
)

4. サーバーが正確な指示を返します:

解釈された問題: ユーザーはナビゲーションバーとヒーローの配置と間隔の問題を報告しています。

影響を受ける要素:
- nav.navbar (セレクター: nav.navbar)
- section.hero (セレクター: .hero-section)

修正指示:

1. ナビゲーションバーの間隔を修正する
   セレクター: nav.navbar
   CSSの変更:
   - padding: 1rem 2rem
   - gap: 1rem
   - align-items: center

2. ヒーローの間隔を修正する
   セレクター: .hero-section
   CSSの変更:
   - padding: 4rem 2rem
   - margin: 0 auto
   - max-width: 1200px

5. AIが正確なCSS変更をコードベースに適用します。

サポートされるUI要素

このアナライザーは、以下の要素を識別して分析できます。

• navbar - ナビゲーションバー、メニュー
• header - ページのヘッダー、バナー
• footer - ページのフッター
• hero - ヒーローセクション、スプラッシュエリア
• button - ボタン、CTA
• link - アンカーリンク
• heading - H1 - H6の見出し
• form - フォームとフォームコンテナ
• input - 入力フィールド、テキストエリア、セレクトボックス
• card - カードコンポーネント、パネル
• sidebar - サイドナビゲーション、サイドバー
• modal - ダイアログ、ポップアップ
• dropdown - ドロップダウンメニュー、セレクトボックス
• image - 画像、SVG
• section - コンテンツセクション
• container - メインコンテナ、ラッパー

検出される問題のタイプ

• layout_broken
• overflow_hidden
• z_index_conflict
• spacing_inconsistent
• alignment_off
• responsive_issue
• accessibility_missing
• contrast_low
• element_overlap
• invisible_element
• empty_container
• broken_flexbox
• broken_grid

開発

# デバッグ用にMCPインスペクターで実行する
uv run mcp dev server.py

# テストスイートを実行する
uv run python test_mcp_server.py

テストカバレッジ:

• クエリ解釈（曖昧なユーザークエリから要素タイプへ）
• 複数のテストサイトでのページ読み込み
• スクリーンショットのキャプチャ（全ページ、ビューポート、強調表示された要素）
• アクセシビリティツリーの抽出
• DOM構造の抽出
• 要素タイプによる要素識別
• 問題の検出
• 全ページ分析
• 修正指示の生成
• ビューポートの比較（モバイル、タブレット、デスクトップ）
• 技術スタックの検出

テストアーティファクトはtest_output/ディレクトリに保存されます。

• 異なるビューポートでのスクリーンショット
• アクセシビリティツリーのYAML
• DOM構造のテキスト
• 検出された要素のJSON
• 分析結果のJSON
• 技術スタックの検出結果

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

コントリビューション

コントリビューションは大歓迎です！問題を開くか、プルリクエストを送信してください。

謝辞

• MCP Python SDKを使用して構築されています。
• ブラウザー自動化にPlaywrightを使用しています。
• GitHub Copilot、Cursor、およびClaudeと連携するように設計されています。