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已安装
安装```bash
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
### 验证安装```bash
# 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)-综合分析
示例:```python
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`:```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 自定义:```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
## 故障排除
**服务器无法启动**:```bash
# 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
内存不足:```bash
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`
- 检查文件权限
## 发展
### 运行测试```bash
# (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问题
