Bug Sheet

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

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 [email protected]) 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.

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

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