# 📖 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:\\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:
```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! 🚀**