# 📖 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
```powershell
cd my-mcp-server
```
### Bước 2: Cài đặt dependencies
```powershell
npm install
```
### Bước 3: Build project
```powershell
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`:
```json
{
"mcp": {
"servers": {
"my-mcp": {
"type": "stdio",
"command": "node",
"args": ["d:\\C99\\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-here` bằng OpenAI API key thật của bạn.
### Bước 3: Restart MCP Server
1. Nhấn `Ctrl + Shift + P`
2. Gõ `MCP: List Servers`
3. Tìm server `my-mcp` và 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
1. Mở **Copilot Chat** trong VS Code (`Ctrl + Shift + I`)
2. 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
```
3. 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:\C99\my-mcp-server\test-images\expectation\login-baseline.png
Dealers: d:\C99\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:\C99\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:**
1. Kiểm tra `settings.json` có `OPENAI_API_KEY` chưa
2. Hoặc set environment variable:
```powershell
$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:**
1. `Ctrl + Shift + P` → `MCP: List Servers`
2. Kiểm tra server `my-mcp` có status **Running** không
3. Nếu không, click **Start** hoặc **Restart**
4. 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
1. **Đặt tên folder dealer rõ ràng** để dễ identify trong report
2. **Screenshot cùng viewport size** để so sánh chính xác hơn
3. **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"
```
4. **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:
1. Node.js version >= 18
2. OpenAI API key valid và có credit
3. MCP server đang running
4. Đường dẫn files chính xác
---
**Happy Testing! 🚀**
