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