📖 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)

Related MCP server: Screenshot Analyzer MCP

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

🔧 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

Chi phí phụ thuộc vào kích thước ảnh và độ phức tạp.

📝 Parameters Reference

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