# bug-sheet-mcp

MCP Server cho phép Claude Code thao tác với Google Sheets để quản lý Bug / Testcase.

## Tính năng

- Kết nối Google Sheets qua Service Account
- Đọc danh sách testcase
- Lọc testcase Fail
- Tra cứu testcase theo TC ID
- Tìm kiếm testcase theo từ khóa
- Cập nhật testcase (partial update)
- Cache dữ liệu trong RAM, tự động refresh sau khi update

## Cài đặt

### Plugin (khuyến nghị)

```bash
claude plugin install github:TrungPhuNA/bug-sheet-mcp
```

Sau khi cài, chạy `/config bug-sheet` để điền `GOOGLE_SHEET_ID`, `GOOGLE_CREDENTIALS`.

### Manual

```bash
npm install
npm run build
```

## Google Service Account

1. Truy cập [Google Cloud Console](https://console.cloud.google.com/)
2. Tạo project hoặc chọn project có sẵn
3. Vào **APIs & Services > Library**
4. Tìm và bật **Google Sheets API**

### Tạo Service Account

1. Vào **APIs & Services > Credentials**
2. Chọn **Create Credentials > Service Account**
3. Đặt tên, nhấn **Create and Continue**
4. Không cần gán role, nhấn **Done**
5. Chọn Service Account vừa tạo
6. Vào tab **Keys**
7. Chọn **Add Key > Create New Key**
8. Chọn **JSON** → nhấn **Create**
9. File JSON sẽ tự động tải về — đây là `GOOGLE_CREDENTIALS`

### Chia sẻ Sheet

Copy email của Service Account (dạng `name@project.iam.gserviceaccount.com`) và **Share** sheet với email đó với quyền **Editor**.

## Cấu hình

Copy file `.env.example` thành `.env`:

```bash
cp .env.example .env
```

Điền các giá trị:

| Variable | Mô tả |
|----------|-------|
| `GOOGLE_SHEET_ID` | ID của Google Sheet (lấy từ URL) |
| `GOOGLE_WORKSHEET` | Tên worksheet (mặc định: `Sheet1`) |
| `GOOGLE_CREDENTIALS` | Đường dẫn file JSON hoặc nội dung JSON |
| `GOOGLE_EMAIL` | Email Service Account (dùng để share sheet) |

## Build

```bash
npm run build
```

## Run

```bash
npm run start
```

Khi chạy thành công sẽ thấy log:
```
[INFO]  — Google Sheets client initialized
[INFO]  — bug-sheet-mcp server running on stdio
```

> **Lưu ý:** MCP Server dùng stdio transport, không phải HTTP. Server sẽ đợi JSON-RPC message từ stdin.

## Test

Sử dụng pretty-printer để xem kết quả dạng table:

```bash
# List toàn bộ testcases
node scripts/test-pretty.mjs list_bugs

# Chỉ testcase Fail
node scripts/test-pretty.mjs list_failed_bugs

# Chi tiết 1 testcase
node scripts/test-pretty.mjs get_bug '{"tcId":"TC07"}'

# Tìm kiếm theo keyword
node scripts/test-pretty.mjs search_bug '{"keyword":"Authorization"}'

# Cập nhật (status, actual, note, description)
node scripts/test-pretty.mjs update_bug '{"tcId":"TC07","updates":{"status":"Pass","note":"Fixed"}}'
```

Output mẫu:
```
| TC ID    | Group              | Description                         | Status   | Note                      |
|----------|--------------------|-------------------------------------|----------|---------------------------|
| TC01     | Happy path         | Đăng ký individual hợp lệ           | Pass     |                           |
| TC07     | Authorization      | Thiếu prefix Bearer                 | Fail     | Security bug: cần enforce |
```

Kết quả nếu không tìm thấy:
```
{ "message": "Bug not found" }
```

### Test với MCP Inspector (giao diện web)

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Mở browser vào URL hiển thị để test từng tool bằng GUI.

## MCP Config

Thêm vào `claude.json` hoặc `settings.json` của Claude Code:

```json
{
  "mcpServers": {
    "bug-sheet": {
      "command": "node",
      "args": ["path/to/bug-sheet-mcp/dist/index.js"],
      "env": {
        "GOOGLE_SHEET_ID": "1VhfrSfBtFGCNhk2ENGBRzxDFQuRpeVq9ZrKFx0nEACM",
        "GOOGLE_WORKSHEET": "BUG",
        "GOOGLE_CREDENTIALS": "credentials/google-service-account.json"
      }
    }
  }
}
```

> **Lưu ý:**
> - `GOOGLE_CREDENTIALS` hỗ trợ cả đường dẫn file (tính từ thư mục dự án) và nội dung JSON trực tiếp.
> - Nếu dùng Claude Code ở thư mục khác, nên dùng đường dẫn tuyệt đối hoặc nội dung JSON.

### Tích hợp vào nhiều project khác nhau

Có thể ghi đè env động khi tích hợp, mỗi project dùng một sheet riêng:

```json
{
  "mcpServers": {
    "bug-sheet": {
      "command": "/Users/phuphan/Documents/work/tool/bug-sheet-mcp/start.sh",
      "args": [],
      "env": {
        "GOOGLE_SHEET_ID": "ID_SHEET_KHAC",
        "GOOGLE_WORKSHEET": "TEN_SHEET",
        "GOOGLE_CREDENTIALS": "credentials/google-service-account.json"
      }
    }
  }
}
```

**Cơ chế ghi đè:**
1. Nếu config có `env` → dùng env đó (ưu tiên cao nhất)
2. Nếu không có `env` → tự động đọc từ file `.env` của project bug-sheet-mcp
3. Có thể override từng biến, không cần ghi hết — ví dụ chỉ đổi `GOOGLE_SHEET_ID`:

```json
{
  "mcpServers": {
    "bug-sheet": {
      "command": "/Users/phuphan/Documents/work/tool/bug-sheet-mcp/start.sh",
      "env": { "GOOGLE_SHEET_ID": "ID_SHEET_KHAC" }
    }
  }
}
```


## Format Google Sheet

Sheet cần có header (dòng đầu tiên). Header có thể ở bất kỳ thứ tự nào. Các cột hỗ trợ:

| Header | Field | Ghi chú |
|--------|-------|---------|
| TC ID | tcId | Mã testcase |
| Nhóm | group | Nhóm |
| Mô tả | description | Mô tả |
| Request Body | request | Request |
| Expected Result | expected | Kỳ vọng |
| Actual Result | actual | Thực tế |
| Status | status | Fixed (Dev) / Pass (QA) / Fail |
| Bug/Note | note | Ghi chú |

Các cột không nằm trong danh sách trên vẫn được lưu trong `raw`.

## Tools

| Tool | Input | Output |
|------|-------|--------|
| `list_bugs` | `{}` | Tất cả testcase |
| `list_failed_bugs` | `{}` | Testcase có Status = Fail |
| `get_bug` | `{ tcId }` | Chi tiết testcase |
| `search_bug` | `{ keyword }` | Kết quả tìm kiếm |
| `update_bug` | `{ tcId, updates }` | Cập nhật testcase |

## Quick Reference — gõ gì để dùng tool

| Muốn | Gõ trong Claude Code |
|------|----------------------|
| Xem hết bugs | `List all bugs trong sheet` |
| Xem bugs đang fail | `Những testcase nào đang fail?` |
| Xem chi tiết 1 bug | `Xem TC07` hoặc `check TC98` |
| Tìm bugs theo từ khóa | `Tìm bug liên quan đến Authorization` |
| Dev: báo đã fix | `Tôi đã fix TC72 rồi, cập nhật status = Fixed, note = "Đã fix Content-Type"` |
| QA: verified OK | `TC72 đã verify ok, update status = Pass` |

## Sử dụng với Claude Code

Sau khi cấu hình MCP, a có thể yêu cầu Claude Code làm việc bằng tiếng Việt:

### 1. Xem danh sách bugs

```
Liệt kê tất cả testcase trong sheet
```

### 2. Xem bugs bị Fail

```
Những testcase nào đang bị Fail?
```

### 3. Tra cứu testcase cụ thể

```
Xem chi tiết TC07
```

### 4. Tìm kiếm testcase

```
Tìm testcase liên quan đến Authorization
```

### 5. Cập nhật kết quả test

**Bước 1 — Dev fix bug:** cập nhật status = **Fixed**

```
Đã fix TC72 — API từ chối request thiếu Content-Type (trả về 415).
Cập nhật status thành Fixed, note: "Đã fix, yêu cầu Content-Type: application/json"
```

**Bước 2 — QA verify:** cập nhật status = **Pass**

```
Đã verify TC72, kết quả đúng.
Cập nhật status thành Pass.
```

Claude sẽ tự động gọi tool `update_bug` để ghi vào Google Sheet.

### 6. Kiểm tra lại sau khi update

```
Cho xem lại TC07 để verify
```