可视化UI调试代理MCP

这是一个自主调试的MCP服务器，它通过Playwright使AI模型能够分析、调试和与Web界面交互。该服务器让任何AI模型（即使是没有内置视觉能力的模型）都能够对网页进行视觉检查，发现UI错误，测试用户工作流程，并验证应用程序性能——所有这些都不需要人工干预。

自主UI调试代理

这个MCP服务器作为一个由AI驱动的自主调试代理，可以：

• 执行全面的视觉分析 对Web应用程序
• 检测UI问题 通过检查视觉元素及其属性
• 自动测试常见的用户工作流程 无需手动创建测试脚本
• 验证API端点 并验证后端响应
• 跟踪不同版本间的视觉变化
• 监控控制台日志 以查找错误和警告
• 分析性能指标 以识别瓶颈
• 生成详细的报告 包含截图和建议

该服务器设计为智能工作，重用浏览器会话，避免不必要的文件创建，并专注于您应用程序最重要的方面。

安装选项

使用MCP网关（推荐）

安装此MCP服务器最简单的方法是通过任何兼容MCP的网关：

bash

例如使用Claude网关

claude-gateway install visual-ui-debug-agent-mcp

快速安装脚本

使用我们的一行安装脚本：

bash
curl -s https://raw.githubusercontent.com/samihalawa/visual-ui-debug-agent-mcp/main/scripts/install-global.sh | bash

NPM安装

对于全局安装，可以通过npm：

bash

全局安装

npm install -g visual-ui-debug-agent-mcp

启动服务器

visual-ui-debug-agent-mcp

Docker Hub安装

对于容器化部署：

bash

从Docker Hub拉取镜像

docker pull samihalawa/visual-ui-debug-agent-mcp:latest

运行容器

docker run -p 8080:8080 samihalawa/visual-ui-debug-agent-mcp:latest

Smithery集成

此包完全兼容Smithery，使用包含的配置文件：

bash

使用Smithery安装

smithery install visual-ui-debug-agent-mcp

或者使用您的API密钥运行

npm run smithery:key YOUR_SMITHERY_API_KEY

完整的安装和使用说明，请参阅Smithery集成指南。

工具完整参考

主要视觉分析工具

1. enhanced_page_analyzer 🔍

提供带有交互元素映射、性能指标和视觉检查的网页综合分析。

javascript
const analysis = await mcp.callTool("enhanced_page_analyzer", {
url: "https://example.com/dashboard",
includeConsole: true,
mapElements: true,
fullPage: true
});

2. ui_workflow_validator 🔄

通过执行并验证一系列UI交互来自动测试完整的用户旅程。

javascript
const result = await mcp.callTool("ui_workflow_validator", {
startUrl: "https://example.com/login",
taskDescription: "用户登录流程",
steps: [
{ description: "输入用户名", action: "fill", selector: "#username", value: "test" },
{ description: "输入密码", action: "fill", selector: "#password", value: "pass" },
{ description: "点击登录", action: "click", selector: "button[type= submit ]" },
{ description: "验证仪表板加载", action: "verifyElementVisible", selector: ".dashboard" }
],
captureScreenshots: "all"
});#### 3. visual_comparison 👁️

比较两个网页或UI状态以识别视觉差异。

javascript
const diff = await mcp.callTool("visual_comparison", {
url1: "https://example.com/before",
url2: "https://example.com/after",
threshold: 0.05
});

4. screenshot_url 📸

捕获任何URL的高质量截图，并可选择全页或特定元素。

javascript
const screenshot = await mcp.callTool("screenshot_url", {
url: "https://example.com/profile",
fullPage: true,
device: "iPhone 13"
});

5. batch_screenshot_urls 📷

在一个操作中对多个URL进行截图，以便高效比较。

javascript
const screenshots = await mcp.callTool("batch_screenshot_urls", {
urls: ["https://example.com/page1", "https://example.com/page2"],
fullPage: true
});

用户流程测试工具

6. navigation_flow_validator 🧭

测试多步骤导航序列并进行验证。

javascript
const navResult = await mcp.callTool("navigation_flow_validator", {
startUrl: "https://example.com",
steps: [
{ action: "click", selector: "a.products" },
{ action: "wait", waitTime: 1000 },
{ action: "click", selector: ".product-item" }
],
captureScreenshots: true
});

7. api_endpoint_tester 🔌

测试多个API端点并验证响应以进行后端验证。

javascript
const apiTest = await mcp.callTool("api_endpoint_tester", {
url: "https://api.example.com/v1",
endpoints: [
{ path: "/users", method: "GET" },
{ path: "/products", method: "GET" }
],
authToken: "Bearer token123"
});

DOM和性能分析

8. dom_inspector 🔬

详细检查DOM元素及其属性。

javascript
const elementInfo = await mcp.callTool("dom_inspector", {
url: "https://example.com",
selector: "nav.main-menu",
includeChildren: true,
includeStyles: true
});

9. console_monitor 📟

监控并捕获控制台日志以检测错误。

javascript
const logs = await mcp.callTool("console_monitor", {
url: "https://example.com/app",
filterTypes: ["error", "warning"],
duration: 5000
});

10. performance_analysis ⚡

测量和分析页面加载性能指标。

javascript
const perfMetrics = await mcp.callTool("performance_analysis", {
url: "https://example.com/dashboard",
iterations: 3
});

低级Playwright控制

11. screenshot_local_files 📁

对本地HTML文件进行截图。

javascript
const localScreenshot = await mcp.callTool("screenshot_local_files", {
filePath: "/path/to/local/file.html"
});

12. 直接Playwright操作

完整的低级Playwright控制集，用于精确自动化：

• playwright_navigate: 导航到特定URL
• playwright_click: 点击元素
• playwright_iframe_click: 点击iframe内的元素
• playwright_fill: 填充表单字段
• playwright_select: 选择下拉选项
• playwright_hover: 悬停在元素上
• playwright_evaluate: 在页面上下文中运行JavaScript
• playwright_console_logs: 获取控制台日志
• playwright_get_visible_text: 提取可见文本
• playwright_get_visible_html: 获取可见HTML
• playwright_go_back: 后退
• playwright_go_forward: 前进
• playwright_press_key: 按键盘键
• playwright_drag: 拖放元素
• playwright_screenshot: 截图

自主调试工作流

MCP服务器可以通过组合工具自主执行完整的调试工作流。例如：

视觉回归测试

javascript
// 1. 分析当前版本
const currentAnalysis = await mcp.callTool("enhanced_page_analyzer", {...});

// 2. 与先前版本比较
const comparisonResult = await mcp.callTool("visual_comparison", {...});

// 3. 生成视觉差异报告
const report = await mcp.callTool("ui_workflow_validator", {...});### 端到端用户流程验证
javascript
// 1. 从登录流程开始
const loginResult = await mcp.callTool("ui_workflow_validator", {...});

// 2. 验证核心功能
const featureResults = await mcp.callTool("navigation_flow_validator", {...});

// 3. 测试 API 端点
const apiResults = await mcp.callTool("api_endpoint_tester", {...});

性能优化

javascript
// 1. 分析初始性能
const initialPerformance = await mcp.callTool("performance_analysis", {...});

// 2. 识别加载缓慢的元素
const elementPerformance = await mcp.callTool("dom_inspector", {...});

// 3. 监控控制台错误
const consoleErrors = await mcp.callTool("console_monitor", {...});

可视化分析示例

元素映射

MCP 服务器会自动映射页面上的所有交互元素，使 AI 模型能够轻松理解 UI 结构。

可视化比较

可视化比较工具突出显示不同 UI 状态之间的差异，非常适合捕捉意外的视觉变化。

集成选项

与 Smithery 集成

yaml

smithery.yaml 配置

startCommand:
type: stdio
configSchema:
type: object
properties:
port:
type: number
description: MCP 服务器的端口号
debug:
type: boolean
description: 启用调试模式

与 GLAMA 集成

json
// glama.json 配置
{
"name": "visual-ui-debug-agent-mcp",
"version": "1.0.2",
"settings": {
"port": 8080,
"headless": true,
"maxConcurrentSessions": 5
}
}

与非视觉模型集成

MCP 服务器将视觉信息转换为结构化数据，这些数据可以被任何 AI 模型使用，即使它们没有视觉能力：

javascript
// 模型接收关于视觉元素的结构化数据
{
"interactiveElements": [
{
"tagName": "button",
"text": "提交",
"bounds": {"x": 120, "y": 240, "width": 100, "height": 40},
"visible": true
},
// 更多元素...
]
}

CI/CD 集成

此 MCP 服务器包括用于持续集成和部署的 GitHub Actions 工作流：

• 构建和测试：验证代码质量
• NPM 发布：自动化包发布
• Docker 发布：创建并推送 Docker 镜像
• Smithery 发布：部署到 Smithery 平台

许可证

本项目根据 ISC 许可证获得许可。