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

Related MCP server: google-drive-mcp

Cài đặt

Plugin (khuyến nghị)

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

npm install
npm run build

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ị:

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.

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:

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

{
  "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ợ:

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

Tools

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

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