MCP UI截图分析器
一个MCP（模型上下文协议）服务器，与GitHub Copilot集成，使用 仅限本地模型 （零API成本，隐私优先设计）。
特性
- UI截图分析：对UI布局和结构的语义理解
- 调色板提取：使用OpenCV k-means提取主色
- 文本提取：通过Gemma 3视觉实现OCR功能
- Bug检测：识别布局问题和可访问性问题
- 深度级别：可配置的分析深度（快速/标准/深度）
- 智能缓存：重复分析的性能优化
当前状态
第1周MVP-完成 ✓
- ✅ 通过Ollama整合Gemma 3 12B视觉
- ✅ OpenCV颜色提取
- ✅ 结果缓存（1小时TTL）
- ✅ 已实施所有6个MCP工具（4个功能齐全）
- ✅ 错误处理和验证
- ⏳ YOLOv8组件检测（第2周）
- ⏳ 代码生成（第3周）
快速开始
先决条件
- macOS或Linux
- Python 3.10+
- 8GB+内存（建议16GB）
- Ollama已安装
安装
# 1. Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 2. Pull Gemma 3 12B model
ollama pull gemma3:12b
# 3. Activate virtual environment (already created)
source venv/bin/activate
# 4. Run the MCP server
python server.py验证安装
# Check Ollama is running
pgrep -x "ollama"
# Check models are available
ollama list
# Test server initialization
python -c "from server import mcp, gemma_analyzer; print('Server ready!')"MCP工具
1.分析_截图
具有可配置深度级别的主要分析工具。
参数:
image_path（str）：截图的绝对路径depth（str）：“快速”|“标准”|“深度”
深度级别:
- 快：仅限Gemma 3（2-4s）-基本描述
- 标准：Gemma 3+颜色（5-8s）-详细分析
- 深：完整管道（12-18s）-综合分析
示例:
# Via GitHub Copilot Chat:
Analyze the UI screenshot at /Users/me/screenshot.png
# Programmatic:
result = analyze_ui_screenshot("/path/to/screenshot.png", depth="standard")2.提取_颜色_字体
使用OpenCV k-means聚类提取主色。
参数:
image_path（str）：图像的绝对路径n_colors（int）：颜色数量（2-10，默认值：5）
退货：带有十六进制代码、RGB值和百分比的调色板
3.提取_文本
使用Gemma 3 OCR功能从UI中提取文本。
参数:
image_path（str）：截图的绝对路径
退货：提取的文本元素列表
4.检测_漏洞
检测布局问题和可访问性问题。
参数:
image_path（str）：截图的绝对路径
退货：严重性问题清单和建议
5.检测\_ \_组件
*第2周发布-YOLOv8集成*
6.生成_组件_代码
*第3周发布-代码生成*
GitHub复制集成
配置
创建 .vscode/mcp-settings.json:
{
"mcpServers": {
"ui-analyzer": {
"command": "python",
"args": ["/Users/manhhaycode/Developer/image-analysis/server.py"],
"env": {}
}
}
}在Copilot聊天中的使用
Analyze the UI screenshot at /path/to/screenshot.png
Extract colors from /path/to/design.png
Detect bugs in ~/Desktop/app-screenshot.png演出
| 操作 | 时间（CPU） | 时间（GPU） | 缓存 |
|---|---|---|---|
| 快速分析 | 2-4s | 1-2s | \<1s |
| 标准分析 | 5-8s | 2-3s | \<1s |
| 深度分析 | 12-18s | 4-6s | \<1s |
| 颜色提取 | \<1s | \<0.5s | \<0.1s |
缓存：结果缓存1小时，自动失效
项目结构
image-analysis/
├── server.py # MCP server entry point
├── config.yaml # Configuration
├── analyzers/
│ ├── gemma_analyzer.py # Ollama Gemma 3 integration
│ ├── color_extractor.py # OpenCV color extraction
│ └── __init__.py
├── orchestrator/
│ ├── cache.py # Result caching
│ └── __init__.py
├── tests/
│ ├── fixtures/ # Sample screenshots
│ └── __init__.py
├── utils/
│ └── __init__.py
└── venv/ # Virtual environment配置
编辑 config.yaml 自定义：
vision:
model: "gemma3:12b" # Primary model
fallback: "gemma3:2b" # Low RAM fallback
performance:
enable_caching: true
cache_ttl_seconds: 3600 # 1 hour
color_extraction:
default_n_colors: 5故障排除
服务器无法启动:
# Verify Ollama is running
pgrep -x "ollama" || ollama serve &
# Check Gemma 3 model
ollama list | grep gemma3:12b
# Reinstall dependencies
pip install -r requirements.txt内存不足:
# Use quantized model (6.6GB vs 9GB)
ollama pull gemma3:12b-q4
# Edit config.yaml:
vision:
model: "gemma3:12b-q4"未找到图像错误:
- 始终使用 绝对路径
- 验证文件是否存在：
ls -la /path/to/image.png - 检查文件权限
发展
运行测试
# (Tests to be implemented)
python -m pytest tests/添加新工具
- 实施分析仪
analyzers/ - 在中添加MCP工具装饰器
server.py - 集成缓存
- 更新文档
路线图
- 第1周 （完成）：MVP与Gemma 3+颜色提取+缓存✓
- 第2周：YOLOv8组件检测
- 第3-4周：代码生成、全面测试、文档编制
性能优化
该系统包括几个优化：
- 智能缓存：基于MD5的图像哈希，TTL为1小时
- 深度级别：用户控制速度和细节之间的权衡
- 延迟加载：仅在需要时加载组件
- 错误恢复：如果可选功能失败，则性能会下降
硬件要求
- 最小：8GB RAM，仅CPU（使用量化模型）
- 推荐：16GB RAM，任何GPU
- 最优：32GB RAM，8GB+VRAM的GPU
许可证
MIT许可证
贡献
欢迎投稿！请在GitHub上打开问题或PR。
支持
对于问题或疑问：
- 检查 CLAUDE.md 获取详细文档
- 查看上面的故障排除部分
- 打开GitHub问题