使用说明

UI分析器MCP服务器

MCP（模型上下文协议）服务器，用于分析网站UI并为AI编码助手提供精确的修复指令。旨在解决使用GitHub Copilot或Cursor等代理代码IDE时“混乱的UI更新”问题。

特性

实时UI分析 -使用Playwright渲染和检查实际网站
智能查询解释 -理解诸如“导航栏坏了”之类的模糊抱怨
精确的修复说明 -生成特定的CSS选择器和属性更改
技术检测 -识别React、Vue、Angular、Next.js、Tailwind、Bootstrap等
响应式测试 -比较移动设备、平板电脑和桌面视口的UI
可及性分析 -提取可访问性树以进行语义理解

问题

当使用AI编码助手构建或更新网站UI时，结果有时会很混乱：

布局意外中断
元素重叠或错位
间距变得不一致
响应式设计突破

用户经常很难准确描述出了什么问题，比如说“导航栏坏了”或“英雄部分看起来很奇怪”——这些模糊的描述无助于人工智能理解需要进行哪些特定的CSS或HTML更改。

解决方案

此MCP服务器通过以下方式弥合了这一差距：

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

安装

先决条件

Python 3.13或更高版本
uv包管理器

设置

# Clone the repository
git clone https://github.com/0x-Professor/UIAnalyzerMCP.git
cd UIAnalyzerMCP

# Install dependencies
uv sync

# Install Playwright browsers
uv run playwright install chromium

用法

运行服务器

# Run directly
uv run python server.py

# Or use the MCP CLI
uv run mcp run server.py

# For development with inspector
uv run mcp dev server.py

VS代码/GitHub副本配置

添加到您的VS Code settings.json或MCP配置中：

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

光标IDE配置

添加到您的Cursor MCP设置（~/.cours/MCP.json或project.Cursor/MCP.json）：

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

Claude桌面配置

添加到您的Claude Desktop配置文件中：

窗户： %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分析
`get_fix_instructions`	从模糊的投诉中生成精确的修复说明
`get_screenshot`	使用可选元素突出显示捕获屏幕截图
`get_element_details`	获取特定元素类型的详细信息
`get_accessibility_snapshot`	提取YAML格式的可访问性树
`get_dom_overview`	获取简化的DOM结构概述
`compare_viewports`	比较移动设备、平板电脑和台式机尺寸的UI
`get_tech_stack`	检测框架、库和CSS方法

分析_页

网页的完整UI分析。返回元素、问题、可访问性树、DOM结构和屏幕截图。

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

get_fix指令

修复凌乱UI的主要工具。解释模糊的用户投诉并生成精确的修复说明。

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

退货：

解释问题描述
受CSS选择器影响的元素
带有属性更改的有序修复说明
完成CSS更改以应用
其他建议

get_creenshot

捕获带有可选元素突出显示的屏幕截图。

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

获取可访问性快照

获取YAML格式的可访问性树，以了解语义结构。

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

get_dom_overview

获得简化的DOM结构概述。

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

比较视口

比较不同屏幕尺寸的UI，以确定响应问题。

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

get_tech_stock

检测网页上使用的技术栈（框架、库、CSS方法）。返回特定于框架的修复指南。

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

退货：

主要框架（React、Vue、Angular、Svelte等）
元框架（Next.js、Nuxt、Remix、Gatsby、Astro）
CSS方法（顺风、Bootstrap、CSS模块、样式化组件）
UI库（shadcn/UI、Material UI、Chakra UI、Ant Design）
针对特定框架的修复建议

支持的技术检测

JavaScript框架

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

元框架

Next.js、Nuxt、混音、Gatsby、Astro、SvelteKit、Vite

CSS框架和库

顺风CSS、Bootstrap、Bulma、Foundation
shadcn/ui，材质ui，脉轮ui，蚂蚁设计，Radix ui

CSS方法

CSS模块、样式化组件、情感
内联样式、CSS变量、Sass/SCSS

工作流示例

用户运行他们的开发服务器： npm run dev
用户告诉人工智能：“导航栏搞砸了，英雄部分有奇怪的间距”
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"
)

服务器返回精确的指令：

Interpreted Problem: User is reporting alignment, spacing issues with the navbar, hero

Affected Elements:
- nav.navbar (selector: nav.navbar)
- section.hero (selector: .hero-section)

Fix Instructions:

1. Fix spacing on navbar
   Selector: nav.navbar
   CSS Changes:
   - padding: 1rem 2rem
   - gap: 1rem
   - align-items: center

2. Fix spacing on hero
   Selector: .hero-section
   CSS Changes:
   - padding: 4rem 2rem
   - margin: 0 auto
   - max-width: 1200px

AI将精确的CSS更改应用于代码库

支持的UI元素

分析仪可以识别和分析：

导航栏 -导航栏、菜单
头球 -页面标题、横幅
页脚 -页面页脚
英雄 -英雄区、飞溅区
按钮 -按钮、CTA
链接 -锚链接
标题 -H1-H6标题
形式 -模板和模板容器
输入 -输入字段、文本区域、选择
卡片 -板卡组件、面板
侧边栏 -侧边导航
模态 -对话框、弹出窗口
下拉菜单 -下拉菜单，选择
图像 -图像、SVG
部分 -内容部分
容器 -主要容器、包装材料

检测到的问题类型

layout_breached
避免飞越
z_index_冲突
间距不一致
对齐_关闭
响应问题
无障碍
contrast_low
element_overlap
不可见元素
空容器
broke_flexbox
破碎_网格

发展

# Run with MCP inspector for debugging
uv run mcp dev server.py

# Run the test suite
uv run python test_mcp_server.py

测试覆盖范围：

查询解释（用户对元素类型的模糊查询）
跨多个测试站点加载页面
屏幕截图（整页、视口、突出显示的元素）
可访问性树提取
DOM结构提取
按类型标识元素
问题检测
全页分析
修复指令生成
视口比较（移动设备、平板电脑、台式机）
技术栈检测

测试工件保存到 test_output/ 目录：

不同视口的屏幕截图
可访问性树YAML
DOM结构文本
检测到的元素JSON
分析结果JSON
技术栈检测结果

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

贡献

欢迎投稿！请打开问题或提交拉取请求。

致谢

建于 MCP Python SDK
用途剧作家用于浏览器自动化
设计用于与 GitHub Copilot, 光标，以及克劳德