📖 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-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:\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:

1. Kiểm tra settings.json có OPENAI_API_KEY chưa
2. 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:

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! 🚀