📖 Hướng dẫn sử dụng MCP Tool - UI Screenshot Comparison
📋 Yêu cầu hệ thống
- Node.js >= 18.x
- VS Code với GitHub Copilot extension
- OpenAI API Key (lấy tại https://platform.openai.com/api-keys)
🚀 Cài đặt
Bước 1: Clone/Download project
cd my-mcp-server
Bước 2: Cài đặt dependencies
npm install
Bước 3: Build project
npm run build
Sau khi build thành công, file output sẽ ở: dist/index.js
⚙️ Cấu hình MCP Server trong VS Code
Bước 1: Mở VS Code Settings
Nhấn Ctrl + Shift + P → Gõ Preferences: Open User Settings (JSON)
Bước 2: Thêm cấu hình MCP
Thêm đoạn sau vào file settings.json:
{
"mcp": {
"servers": {
"my-mcp": {
"type": "stdio",
"command": "node",
"args": ["d:\\my-mcp-server\\dist\\index.js"],
"env": {
"OPENAI_API_KEY": "sk-proj-your-api-key-here"
}
}
}
}
}
⚠️ Quan trọng: Thay
sk-proj-your-api-key-herebằng OpenAI API key thật của bạn.
Bước 3: Restart MCP Server
- Nhấn
Ctrl + Shift + P - Gõ
MCP: List Servers - Tìm server
my-mcpvà click Restart
📁 Chuẩn bị dữ liệu test
Cấu trúc folder yêu cầu
test-images/
├── expectation/
│ └── baseline.png # Ảnh baseline (design/expectation)
│
└── dealers/
├── dealer-a/
│ └── screenshot.png # Screenshot của dealer A
├── dealer-b/
│ └── screenshot.png # Screenshot của dealer B
├── dealer-c/
│ └── screenshot.png # Screenshot của dealer C
└── dealer-d/
└── screenshot.png # Screenshot của dealer D
Yêu cầu:
- Mỗi dealer là một folder riêng
- Trong folder dealer chứa file ảnh (PNG/JPG/JPEG/GIF/WEBP)
- Có thể có nhiều ảnh trong một folder dealer
🎮 Cách sử dụng
Cách 1: Sử dụng trong Copilot Chat
-
Mở Copilot Chat trong VS Code (
Ctrl + Shift + I) -
Gõ prompt:
Compare dealer screenshots for "Highlights Widget" feature.
User story: Verify the highlights widget displays vehicle features correctly.
Expectation: d:\my-mcp-server\test-images\expectation\baseline.png
Dealers: d:\my-mcp-server\test-images\dealers
- Copilot sẽ tự động gọi tool và trả về kết quả
Cách 2: Chỉ định đường dẫn export Excel
Compare dealer screenshots for "Login Page" feature.
User story: Verify login form has username, password input and submit button.
Expectation: d:\my-mcp-server\test-images\expectation\login-baseline.png
Dealers: d:\my-mcp-server\test-images\dealers
Export path: d:\reports\login-page-report.xlsx
📊 Output
1. Terminal Output (trong Copilot Chat)
# UI Structure Comparison Report
## Feature: Highlights Widget
**User Story:** Verify the highlights widget displays vehicle features correctly
**Baseline:** baseline.png
---
## Results
| Dealer | Image | Score | Status | Analysis |
|----------|----------------|----------|--------|------------------------------|
| dealer-a | screenshot.png | 95/100 | PASS | UI structure matches |
| dealer-b | screenshot.png | 92/100 | PASS | UI structure matches |
| dealer-c | screenshot.png | 45/100 | FAIL | Missing highlights widget |
| dealer-d | screenshot.png | 88/100 | PASS | UI structure matches |
---
## Summary
- **PASS:** 3
- **FAIL:** 1
- **Total:** 4
---
## Excel Report
**Exported to:** d:\my-mcp-server\test-images\report-Highlights-Widget-1705734567890.xlsx
2. Excel Report (3 sheets)
| Sheet | Nội dung |
|---|---|
| Summary | Tổng quan: Feature, Total, Passed, Failed, Pass Rate |
| Results | Tất cả dealers với color-coded (xanh=PASS, đỏ=FAIL) |
| Failed Dealers | Chỉ những dealer failed để quick review |
🔧 Troubleshooting
Lỗi: "OpenAI API key required"
Nguyên nhân: Chưa cấu hình API key
Giải pháp:
- Kiểm tra
settings.jsoncóOPENAI_API_KEYchưa - Hoặc set environment variable:
$env:OPENAI_API_KEY = "sk-proj-your-key-here"
Lỗi: "Expectation image not found"
Nguyên nhân: Đường dẫn ảnh baseline sai
Giải pháp:
- Kiểm tra đường dẫn tồn tại
- Dùng đường dẫn tuyệt đối (full path)
- Kiểm tra file có extension đúng không (.png, .jpg)
Lỗi: "No dealer folders found"
Nguyên nhân: Folder dealers trống hoặc không có subfolder
Giải pháp:
- Đảm bảo có ít nhất 1 subfolder trong dealers/
- Mỗi subfolder là tên dealer (dealer-a, dealer-b,...)
Lỗi: Tool không xuất hiện trong Copilot
Nguyên nhân: MCP server chưa start hoặc cấu hình sai
Giải pháp:
Ctrl + Shift + P→MCP: List Servers- Kiểm tra server
my-mcpcó status Running không - Nếu không, click Start hoặc Restart
- Kiểm tra lại path trong
settings.json
Lỗi: "API Error: 429 Too Many Requests"
Nguyên nhân: Vượt rate limit của OpenAI
Giải pháp:
- Đợi 1 phút rồi thử lại
- Hoặc upgrade OpenAI plan
💰 Chi phí ước tính
| Số dealers | Chi phí ước tính |
|---|---|
| 10 dealers | ~$0.10 - $0.30 |
| 50 dealers | ~$0.50 - $1.50 |
| 100 dealers | ~$1.00 - $3.00 |
Chi phí phụ thuộc vào kích thước ảnh và độ phức tạp.
📝 Parameters Reference
| Parameter | Bắt buộc | Mô tả |
|---|---|---|
expectationImagePath | ✅ | Đường dẫn đến ảnh baseline |
dealersFolderPath | ✅ | Đường dẫn đến folder chứa các dealer subfolders |
featureName | ✅ | Tên feature đang test (VD: "Login Page") |
userStory | ✅ | Acceptance criteria cần verify |
openaiApiKey | ❌ | API key (nếu không set trong env) |
exportPath | ❌ | Đường dẫn export Excel (default: auto generate) |
🎯 Tips
-
Đặt tên folder dealer rõ ràng để dễ identify trong report
-
Screenshot cùng viewport size để so sánh chính xác hơn
-
User story càng cụ thể → AI analyze càng chính xác
❌ "Verify UI" ✅ "Verify the highlights widget shows vehicle features with icons and descriptions" -
Chạy test trên ít dealers trước để verify tool hoạt động đúng
📞 Support
Nếu gặp vấn đề, kiểm tra:
- Node.js version >= 18
- OpenAI API key valid và có credit
- MCP server đang running
- Đường dẫn files chính xác
Happy Testing! 🚀