金大哥 - uianalyzermcp MCP 详情

article

README

🚀 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 服务器通过以下方式解决这些问题：

分析实时网站 - 使用 Playwright 渲染和检查实际 UI。
检测技术栈 - 识别框架（React、Next.js、Vue）和 CSS 库（Tailwind、Bootstrap）。
识别 UI 元素 - 查找导航栏、页眉、页脚、英雄部分、按钮、表单等。
检测问题 - 发现布局问题、溢出、z-index 冲突、可访问性问题。
解释模糊查询 - 理解“页眉乱了”实际意味着什么。
生成框架感知的修复指令 - 根据检测到的技术栈提供特定的 CSS 选择器、属性更改和代码片段。

💻 使用示例

可用工具（共 8 个）

| 工具 | 描述 | |------|-------------| | analyze_page | 对页面进行全面 UI 分析，包括元素、问题和截图。 | | get_fix_instructions | 根据模糊抱怨生成精确的修复指令。 | | get_screenshot | 捕获截图，可选择突出显示元素。 | | get_element_details | 获取特定元素类型的详细信息。 | | get_accessibility_snapshot | 以 YAML 格式提取可访问性树。 | | get_dom_overview | 获取简化的 DOM 结构概述。 | | compare_viewports | 比较不同屏幕尺寸下的 UI，以识别响应式问题。 | | get_tech_stack | 检测网页使用的技术栈（框架、库、CSS 方法），并返回特定框架的修复指导。 |

`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）
特定框架的修复建议

示例工作流程

用户运行开发服务器：npm run dev
用户告诉 AI：“导航栏乱了，英雄部分的间距很奇怪”
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"
)

服务器返回精确指令：

解释后的问题：用户报告导航栏和英雄部分存在对齐和间距问题

受影响的元素：
- 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

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 配合使用