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

npm install

Google Service Account

1. Truy cập Google Cloud Console
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:

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

npm run build

Run

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:

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

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:

{
  "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.

## 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 | Pass / 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 |

## 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

Sau khi fix bug, yêu cầu Claude cập nhật:

Đã verify TC72 — API từ chối request thiếu Content-Type (trả về 415). Cập nhật status thành Pass, note: "Đã fix, yêu cầu Content-Type là bắt buộc"

Hoặc yêu cầu cụ thể:

Cập nhật TC07:

• status = Pass
• actual = API trả về 401 đúng
• note = Đã fix Bearer format

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