Uianalyzermcp

🚀 UI Analyzer MCP Server

UI Analyzer MCP Server 是一個 MCP（模型上下文協議）服務器，可分析網站 UI 併為 AI 編碼助手提供精確的修復指令。它旨在解決使用 GitHub Copilot 或 Cursor 等智能代碼 IDE 時“UI 更新混亂”的問題。

🚀 快速開始

UI Analyzer MCP Server 是一個強大的工具，可幫助開發者更高效地處理網站 UI 問題。以下是使用該工具的快速指南。

安裝

前提條件

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

✨ 主要特性

• 即時 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 選擇器、屬性更改和代碼片段。

💻 使用示例

可用工具（共 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 模塊、styled-components）
• UI 庫（shadcn/ui、Material UI、Chakra UI、Ant Design）
• 特定框架的修復建議

示例工作流程

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 更改應用到代碼庫中

🔧 技術細節

支持的技術檢測

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 模塊、styled-components、Emotion
• 內聯樣式、CSS 變量、Sass/SCSS

支持的 UI 元素

分析器可以識別和分析以下 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 配合使用