Puppeteer MCP via Claude Code CLI & VS Code

Nếu bạn đã quen thuộc với Puppeteer MCP (MCP server cho phép AI agent điều khiển trình duyệt thật để chụp màn hình, đọc DOM, bắt console log), câu hỏi tiếp theo là: làm sao gắn nó vào workflow hằng ngày của một dev hoặc QA engineer đang dùng Claude Code? Bài này đi thẳng vào phần thực hành: cài đặt, kết nối, và ba kịch bản sử dụng thực tế nhất — debug frontend, chạy QA tự động, và khám phá UI theo kiểu exploratory testing.

Claude Code là CLI (command-line interface) chính thức của Anthropic, chạy trực tiếp trong terminal hoặc tích hợp vào VS Code qua extension. Nó hỗ trợ MCP (Model Context Protocol) như một cơ chế native — nghĩa là bạn không cần viết code, không cần build custom tool, chỉ cần khai báo server và Claude tự biết cách gọi các tool bên trong.

Installing and Connecting Puppeteer MCP to Claude Code

Trước tiên, đảm bảo bạn đã cài Claude Code CLI:

npm install -g @anthropic-ai/claude-code

Kiểm tra phiên bản để chắc chắn CLI đã sẵn sàng:

claude --version

Cách 1: Đăng ký qua lệnh `claude mcp add`

Cách nhanh và được khuyến nghị nhất là dùng lệnh có sẵn của CLI, không cần tự tay sửa file JSON:

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Giải thích cú pháp: phần trước dấu -- là tên định danh (identifier) bạn đặt cho MCP server (ở đây là puppeteer), phần sau -- là câu lệnh thực sự dùng để khởi chạy server đó. Claude Code sẽ tự lưu cấu hình này lại, không cần bạn restart thủ công gì thêm ở lần chạy tiếp theo.

Nếu muốn server chỉ áp dụng cho project hiện tại (thay vì global cho mọi project), thêm scope --scope project:

claude mcp add puppeteer --scope project -- npx -y @modelcontextprotocol/server-puppeteer

Cách 2: Khai báo trực tiếp trong file cấu hình JSON

Nếu team bạn muốn version-control cấu hình MCP cùng với repo (để cả team dùng chung setup), tạo file .mcp.json ở root project:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": false}"
      }
    }
  }
}

Lưu ý PUPPETEER_LAUNCH_OPTIONS với "headless": false rất hữu ích khi debug — bạn sẽ thấy cửa sổ trình duyệt thật mở lên, quan sát song song với Claude thay vì chạy ẩn (headless). Với global config, đường dẫn tương ứng là ~/.claude/settings.json (áp dụng cho mọi project trên máy bạn).

Xác thực kết nối

Sau khi đăng ký, mở một phiên Claude Code (claude trong terminal) rồi gõ lệnh slash:

/mcp

Claude sẽ liệt kê tất cả MCP server đang kết nối, trạng thái (connected / failed), và số lượng tool khả dụng từ mỗi server. Ngoài ra có thể kiểm tra nhanh từ ngoài terminal, không cần mở session:

claude mcp list

Kết quả mong đợi trông giống như sau:

puppeteer: npx -y @modelcontextprotocol/server-puppeteer - ✓ Connected

Nếu thấy ✗ Failed to connect, nguyên nhân phổ biến nhất là máy chưa có Node.js đủ mới, hoặc npx bị chặn network khi tải package lần đầu — thử chạy tay npx -y @modelcontextprotocol/server-puppeteer một lần để xem log lỗi trực tiếp.

Dùng trong VS Code

Nếu bạn cài extension "Claude Code" cho VS Code, MCP server đã đăng ký qua CLI sẽ tự động available trong panel chat của extension — không cần cấu hình lại lần hai, vì extension đọc chung file cấu hình với CLI. Cách làm việc thực tế: mở integrated terminal trong VS Code, chạy claude như bình thường, hoặc dùng trực tiếp panel chat bên cạnh code editor để vừa xem code vừa ra lệnh cho agent — tiện khi bạn cần đối chiếu UI đang chạy với source code ngay lúc đó.

Permission — quyền hạn cần lưu ý

Puppeteer MCP điều khiển một trình duyệt thật, có thể truy cập bất kỳ URL nào, kể cả nội bộ hoặc production nếu bạn không cẩn thận. Vài điểm cần khóa trước khi giao việc cho agent:

Mặc định Claude Code sẽ hỏi xin phép (permission prompt) trước khi gọi tool MCP lần đầu trong session — đừng tắt tính năng này trừ khi bạn chắc chắn về phạm vi thao tác.
Nếu muốn giới hạn agent chỉ được điều hướng tới các domain nội bộ (ví dụ localhost), nên thống nhất trong prompt system hoặc trong file CLAUDE.md của project rằng agent không được tự ý navigate ra domain production.
Với thao tác có thể gây side-effect thật (submit form, xóa dữ liệu, thanh toán thử), luôn yêu cầu agent dừng lại xác nhận trước khi click nút "Submit" hoặc "Delete".

Mẹo: Đăng ký Puppeteer MCP ở scope project (không phải global) cho các repo có tính nhạy cảm cao — vừa tránh agent lỡ tay điều hướng nhầm project khác trong cùng máy, vừa giúp file .mcp.json được commit vào repo để cả team dùng chung cấu hình nhất quán.

Debugging Frontend Issues: Letting the Claude Agent Navigate, Inspect, and Diagnose

Đây là use case giá trị nhất của Puppeteer MCP trong Claude Code: biến một bug report mơ hồ ("nút submit không hoạt động") thành root cause cụ thể, chỉ trong một lượt trao đổi. Thay vì bạn tự mở DevTools, tự đọc console, tự inspect element — bạn mô tả bug, Claude tự làm toàn bộ các bước đó và trả về kết luận.

Cách agent suy luận (reasoning) ở đây khác hẳn việc chỉ đọc code tĩnh: Claude kết hợp ba nguồn tín hiệu cùng lúc — ảnh chụp màn hình (để hiểu bối cảnh trực quan, layout, trạng thái UI hiện tại), cây DOM (structure và attribute của các element, giúp xác định selector nào đang trỏ đúng/sai phần tử), và console log (bắt lỗi JavaScript, warning, network failure). Khi ba nguồn này khớp nhau — ví dụ ảnh chụp cho thấy nút bị mờ (disabled), DOM cho thấy attribute disabled="true", console log cho thấy một request /api/validate trả về 500 — Claude ghép lại thành một chuỗi nhân quả rõ ràng thay vì đoán mò.

Ví dụ prompt debug đầy đủ

Bug report từ user: "Khi tôi điền form đăng ký ở trang /signup và bấm nút
'Create Account', không có gì xảy ra. Nút vẫn sáng nhưng không phản hồi."

Hãy giúp tôi xác định root cause bằng các bước sau:
1. Navigate tới http://localhost:3000/signup
2. Điền form với dữ liệu hợp lệ: email "test@example.com",
   password "SecurePass123!", confirm password khớp
3. Chụp screenshot trước khi bấm submit
4. Bấm nút có text "Create Account"
5. Chờ 2 giây, sau đó chụp screenshot lần nữa để so sánh trạng thái
6. Đọc toàn bộ console log (console errors và warnings) phát sinh
   trong quá trình trên
7. Inspect DOM của nút submit bằng selector button[type="submit"]
   — lấy toàn bộ attribute (disabled, class, data-* nếu có)
8. Kiểm tra network tab / các request được gọi khi bấm nút (nếu có
   error status code, ghi lại rõ endpoint và status)

Sau khi thu thập đủ dữ liệu, hãy tổng hợp báo cáo gồm:
- Root cause cụ thể (không phải đoán, phải dựa trên bằng chứng đã thu thập)
- Đoạn code / config nào trong repo (nếu tìm được) gây ra lỗi này
- Đề xuất fix cụ thể

Với prompt dạng này, Claude không chỉ trả lời "nút bị lỗi" chung chung — nó sẽ trích dẫn chính xác: ảnh chụp cho thấy nút không đổi trạng thái, console log in ra TypeError: Cannot read properties of undefined (reading 'trim') tại dòng nào, và selector DOM cho thấy nút thật ra có disabled do một điều kiện validate bị sai logic. Đây chính là điểm khác biệt so với việc chỉ hỏi Claude đọc code — agent xác nhận hành vi thật trên trình duyệt thật trước khi kết luận.

Một số lệnh inspect hữu ích khi trao đổi tiếp

Sau báo cáo đầu tiên, bạn có thể yêu cầu đào sâu thêm:

"Inspect toàn bộ children của <form id='signup-form'> và liệt kê input nào thiếu attribute name."
"Chụp screenshot ở viewport mobile (375x667) để xem layout có bị vỡ không."
"Lấy computed style của phần tử .error-message — kiểm tra xem display có đang là none dù đã có nội dung lỗi hay không."

Mẹo: Khi mô tả bug, luôn kèm theo bước tái hiện (repro steps) cụ thể như trong ví dụ trên — Claude debug chính xác hơn hẳn khi có kịch bản rõ ràng để thực thi, thay vì chỉ nhận một câu mô tả cảm tính như "trang bị lỗi".

Automating QA Scenarios: UI Flows, Edge Cases, and Regression Checks via Claude Code

Với QA engineer, giá trị lớn nhất không nằm ở việc debug một bug đơn lẻ, mà ở khả năng giao cho Claude chạy toàn bộ một luồng nghiệp vụ (flow) nhiều bước, tự phát hiện bất thường, và trả về báo cáo có cấu trúc — giống như một tester thật đang thao tác thủ công nhưng nhanh và nhất quán hơn.

Ba nhóm kịch bản QA phổ biến nhất khi dùng Puppeteer MCP:

Multi-step UI flow: luồng đăng ký, luồng checkout, luồng quên mật khẩu — nhiều bước liên tiếp, mỗi bước phụ thuộc kết quả bước trước.
Edge case testing: input không hợp lệ (email sai định dạng, password quá ngắn), giá trị biên (boundary value — số lượng đơn hàng bằng 0, bằng số tối đa cho phép, ký tự đặc biệt trong tên).
Regression check: so sánh trạng thái UI hiện tại với ảnh chụp/mô tả hành vi đã biết là đúng (known-good), để phát hiện thứ gì đó âm thầm bị thay đổi sau một lần deploy.

Ví dụ prompt QA — chạy full checkout flow

Bạn là QA agent. Hãy thực hiện test luồng checkout trên
http://localhost:3000 theo kịch bản sau và báo cáo kết quả từng bước
(PASS/FAIL), kèm screenshot tại các điểm quan trọng:

1. Navigate tới trang chủ, thêm sản phẩm đầu tiên vào giỏ hàng
2. Vào giỏ hàng, xác nhận số lượng và tổng tiền hiển thị đúng
3. Bấm "Checkout", điền thông tin giao hàng hợp lệ
4. Test edge case: để trống trường "Postal code" rồi bấm Continue
   — xác nhận có hiển thị lỗi validate, không cho qua bước tiếp theo
5. Điền lại postal code hợp lệ, tiếp tục sang bước thanh toán
6. Test edge case: nhập số thẻ không đủ 16 số — xác nhận hệ thống
   chặn và hiển thị thông báo lỗi rõ ràng
7. Nhập thông tin thẻ test hợp lệ (dùng thẻ test mode), hoàn tất đơn hàng
8. Xác nhận trang "Order confirmation" hiển thị đúng mã đơn hàng

Sau khi hoàn tất, so sánh giao diện trang confirmation với ảnh chụp
đã lưu ở /qa-baselines/checkout-confirmation.png (nếu có sẵn) và báo
cáo bất kỳ khác biệt bố cục nào đáng chú ý.

Bảng các tool call Puppeteer MCP thường dùng trong kịch bản QA

Bước nghiệp vụ	Tool MCP tương ứng	Mục đích
Mở trang cần test	`puppeteer_navigate`	Điều hướng tới URL, khởi tạo phiên trình duyệt
Điền form	`puppeteer_fill`	Nhập giá trị vào input theo selector
Bấm nút/link	`puppeteer_click`	Kích hoạt hành động, chuyển bước trong flow
Ghi lại trạng thái UI	`puppeteer_screenshot`	Lưu ảnh làm bằng chứng, so sánh regression
Kiểm tra nội dung/element	`puppeteer_evaluate`	Chạy đoạn JS nhỏ để đọc DOM, kiểm tra điều kiện cụ thể
Bắt lỗi runtime	Console log capture	Phát hiện lỗi JS ẩn không hiển thị trên UI

Mẹo: Luôn yêu cầu Claude báo cáo theo format PASS/FAIL rõ ràng cho từng bước (không chỉ mô tả chung chung "mọi thứ hoạt động tốt") — format này giúp bạn copy thẳng vào test report hoặc ticket, và dễ dàng phát hiện bước nào âm thầm fail mà không chặn luồng chính.

Exploring UI Behavior and Mapping Interaction Paths with Puppeteer MCP

Ngoài debug và QA theo kịch bản có sẵn, Puppeteer MCP còn cho phép một kiểu kiểm thử ít được khai thác: exploratory testing (kiểm thử khám phá) — để Claude tự do click qua toàn bộ ứng dụng như một người dùng tò mò, ghi lại mọi trạng thái (state) mà nó đến được, rồi dựng thành một bản đồ (sitemap) các đường đi tương tác. Cách này đặc biệt hữu ích khi bạn kế thừa một codebase cũ không có tài liệu, hoặc muốn rà soát toàn diện trước một đợt release lớn.

Khác với QA flow ở H2 trước (đi theo kịch bản định sẵn), ở đây bạn giao cho Claude quyền tự quyết định "click vào đâu tiếp theo" trong giới hạn cho phép, và yêu cầu nó tự ghi chép lại hành trình.

Ví dụ prompt exploratory testing

Hãy đóng vai một exploratory tester. Bắt đầu từ
http://localhost:3000, thực hiện các bước sau:

1. Navigate tới trang chủ, chụp screenshot, liệt kê tất cả link và
   nút bấm khả dụng (interactive elements) trên trang
2. Với mỗi link/nút, thử click vào (không lặp lại trang đã ghé qua),
   ghi nhận URL đích và tiêu đề trang sau khi click
3. Nếu gặp link dẫn tới URL trả về lỗi 404 hoặc trang trắng, ghi lại
   là "broken link" kèm URL cụ thể
4. Nếu gặp nút bấm không gây ra thay đổi nào trên UI và không có
   console log nào được ghi (không network request, không thay đổi
   DOM), ghi lại là "dead button" nghi vấn
5. Với mỗi trang, kiểm tra nhanh: có thẻ <img> nào thiếu attribute
   alt không, có nút nào thiếu label rõ ràng cho screen reader không
   (accessibility check cơ bản)
6. Giới hạn độ sâu tối đa 3 cấp điều hướng tính từ trang chủ, và
   dừng lại nếu tổng số trang khám phá vượt quá 20 để tránh vòng lặp

Sau khi khám phá xong, tổng hợp:
- Một sitemap dạng cây (tree) thể hiện các trang đã tới được và
  đường link nối giữa chúng
- Danh sách broken link / dead button phát hiện được
- Danh sách vấn đề accessibility (khả năng tiếp cận) đáng chú ý

Kết quả trả về thường là một cấu trúc dễ đọc kiểu:

/ (Trang chủ)
├── /products (Danh sách sản phẩm)
│   ├── /products/:id (Chi tiết sản phẩm) — OK
│   └── /products/:id/reviews — 404 (broken link)
├── /about — OK
└── /contact
    └── nút "Send message" — không phản hồi, không request,
        không console log (nghi ngờ dead button)

Bản đồ này có giá trị lâu dài: bạn có thể lưu lại làm tài liệu tham chiếu cho những lần regression test sau, hoặc đối chiếu với sitemap kỳ trước để phát hiện những trang/route mới phát sinh ngoài ý muốn (ví dụ route debug quên xóa trước khi lên production).

Mẹo: Luôn đặt giới hạn rõ ràng về độ sâu điều hướng và tổng số trang trong prompt (như bước 6 ở ví dụ trên) — nếu không, agent có thể rơi vào vòng lặp vô tận giữa các trang liên kết chéo nhau, hoặc tốn quá nhiều lượt gọi tool một cách không cần thiết.