Tiếng Việt: Puppeteer MCP With Cursor

Nếu bạn đã quen thuộc với Puppeteer MCP trên Claude Code hay Gemini CLI, thì việc mang nó vào Cursor — một IDE (môi trường phát triển tích hợp) AI-first, được fork từ VS Code — mở ra một trải nghiệm khác biệt rõ rệt: bạn vừa có toàn bộ sức mạnh của một code editor "xịn" (IntelliSense, multi-file context, Git integration...), vừa có một Agent có thể tự điều khiển trình duyệt để kiểm tra UI (giao diện người dùng) thực tế, ngay trong cùng một cửa sổ làm việc.

Điểm khác biệt lớn nhất so với các công cụ CLI thuần túy: ở Cursor, code và browser nằm cạnh nhau. Agent chạy Puppeteer để lấy screenshot, đọc console log, inspect DOM (Document Object Model — cấu trúc cây của trang HTML), rồi ngay lập tức nhảy sang mở file source code liên quan để sửa. Toàn bộ vòng lặp "quan sát — suy luận — sửa — verify" diễn ra không cần rời khỏi editor.

Bài viết này sẽ đi từ việc setup Puppeteer MCP trong Cursor, đến các workflow thực chiến cho debugging và QA (Quality Assurance — đảm bảo chất lượng), và cuối cùng là những giới hạn thật sự bạn cần biết trước khi đưa quy trình này vào công việc hàng ngày.

Connecting Puppeteer MCP to Cursor Agent Mode

Cursor hỗ trợ MCP (Model Context Protocol) theo hai cách cấu hình: qua giao diện Settings, hoặc qua file cấu hình cấp project .cursor/mcp.json. Cả hai đều dẫn đến cùng một kết quả — Agent Mode của Cursor "nhìn thấy" các tool của Puppeteer MCP server như một phần công cụ nó có thể gọi.

Cách 1: Cấu hình qua Cursor Settings UI

1. Mở Cursor, vào Cursor Settings (biểu tượng bánh răng góc trên phải, hoặc Cmd/Ctrl + Shift + J).
2. Tìm mục MCP (ở các bản Cursor cũ hơn nằm trong Features > MCP, bản mới gộp thành tab riêng MCP trong Settings).
3. Nhấn + Add new MCP server (hoặc New MCP Server).
4. Cursor sẽ mở ra một file mcp.json (global, áp dụng cho mọi project) hoặc cho bạn nhập trực tiếp tên, command, và arguments của server.
5. Điền thông tin cho Puppeteer MCP server tương tự cấu hình bên dưới, lưu lại.
6. Quay lại danh sách MCP servers trong Settings — nếu kết nối thành công, server sẽ hiển thị chấm tròn màu xanh (running) kèm số lượng tool nó cung cấp (ví dụ "6 tools enabled").

Cách 2: Cấu hình qua file .cursor/mcp.json cấp project

Cách này được khuyến khích cho môi trường team, vì file có thể commit vào repo (trừ phần secret) để cả team dùng chung cấu hình. Tạo file .cursor/mcp.json ở thư mục gốc project:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Nếu bạn dùng bản Puppeteer MCP server tự build hoặc chạy qua Docker, cấu hình có thể trông như sau:

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "DOCKER_CONTAINER=true",
        "mcp/puppeteer"
      ]
    }
  }
}

Sau khi lưu file, Cursor sẽ tự động detect thay đổi và khởi động server (nếu chưa chạy). Bạn cũng có thể vào tab MCP trong Settings, bấm nút reload cạnh tên server để force restart nếu server không tự lên.

Bật Agent Mode và xác nhận tool khả dụng

1. Mở khung chat của Cursor (Cmd/Ctrl + L cho chat thường, hoặc Cmd/Ctrl + I cho Composer).
2. Ở góc dưới khung chat, chọn chế độ Agent (thay vì Ask hoặc Edit) — đây là chế độ cho phép model tự gọi tool, bao gồm cả MCP tools, thay vì chỉ trả lời văn bản.
3. Gõ thử một câu đơn giản như: List the MCP tools you currently have access to. Nếu cấu hình đúng, Agent sẽ liệt kê các tool như puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_evaluate...
4. Khi Agent lần đầu gọi một tool thuộc Puppeteer MCP, Cursor sẽ hiện hộp thoại xác nhận (tool-approval prompt) hỏi bạn có cho phép chạy hay không. Bạn có thể chọn Run cho một lần, hoặc Run automatically for this tool/server để bỏ qua xác nhận cho các lần sau trong cùng project.

Mẹo: Đừng bật "auto-run" cho toàn bộ Puppeteer MCP ngay từ đầu, nhất là khi bạn mới làm quen. Hãy để chế độ hỏi xác nhận trong vài ngày đầu để quan sát Agent thật sự gọi tool nào, theo trình tự ra sao — việc này giúp bạn phát hiện sớm những lần Agent "đoán mò" thay vì thao tác đúng ý bạn, trước khi trao toàn quyền tự động.

Debugging Frontend Bugs from Cursor: Agent Sees the Browser, You See the Code

Đây là workflow giá trị nhất mà Puppeteer MCP mang lại cho Cursor: bạn có thể ngồi tại editor, mở sẵn các file component nghi ngờ có bug, và để Agent vừa điều khiển trình duyệt vừa đọc — thậm chí sửa — code cùng lúc.

Luồng làm việc điển hình:

1. Agent navigate đến URL cần test (puppeteer_navigate).
2. Agent tái hiện bug bằng cách click, gõ form, submit — đúng như một tester thật sự thao tác.
3. Agent chụp screenshot ở từng bước quan trọng để bạn (và chính Agent) so sánh trạng thái UI trước/sau.
4. Agent đọc console log và network log để tìm lỗi JavaScript, request bị fail, warning từ React/Vue...
5. Agent inspect DOM — kiểm tra class, attribute, disabled state của element thực tế đang render trên trang, không phải chỉ đọc code tĩnh.
6. Agent đối chiếu với source code trong workspace — mở đúng file component, tìm đoạn logic liên quan đến hành vi vừa quan sát được trên trình duyệt.
7. Agent đề xuất fix, bạn review diff ngay trong Cursor như một pull request bình thường trước khi apply.

Cái hay ở đây là bạn không cần mô tả bug bằng lời cho thật chính xác — Agent tự đi tìm bằng chứng từ browser thật, rồi khớp bằng chứng đó với code thật, thay vì đoán mò dựa trên mô tả text của bạn.

Ví dụ prompt debugging đầy đủ

Giả sử bug là: nút Submit không bị disable trong lúc form đang loading, khiến user có thể click nhiều lần và gửi trùng request.

The submit button on the checkout form doesn't disable during the loading
state, which lets users double-click and trigger duplicate order submissions.

Please investigate and fix this:

1. Navigate to http://localhost:3000/checkout
2. Fill in the form with test data (any valid values) so the Submit button
   becomes active
3. Click Submit, and immediately take a screenshot to capture the button's
   state right after the click
4. Check the DOM for the button element — inspect whether it has a
   `disabled` attribute or a `loading`/`isSubmitting` class applied during
   the request
5. Open the browser console and check for any errors or warnings logged
   during submission
6. Try clicking Submit a second time quickly (simulate a double-click) and
   check the Network tab / requests to see if two submit requests fire
7. Once you've confirmed the bug, find the relevant component in
   src/components/CheckoutForm — likely involving the `onSubmit` handler
   and the loading state variable
8. Show me the current code, explain what's missing (e.g. the `disabled`
   prop isn't bound to the loading state), and propose a fix
9. After applying the fix, repeat steps 2–6 to verify the button is
   correctly disabled and only one request is sent

Chú ý cấu trúc prompt: nó tách rõ bước tái hiện bug bằng browser (1–6), bước map sang code (7–8), và bước verify lại (9). Cách viết prompt theo trình tự rõ ràng như vậy giúp Agent không nhảy cóc — nó sẽ có bằng chứng cụ thể (screenshot, DOM state, console log) để trích dẫn khi giải thích nguyên nhân, thay vì suy đoán chung chung.

Mẹo: Luôn mở sẵn file component nghi ngờ có bug trong tab của Cursor trước khi giao task cho Agent. Khi file đã nằm trong ngữ cảnh (context) hiện tại của editor, Agent có xu hướng ưu tiên đối chiếu đúng file đó thay vì tìm kiếm lan man khắp codebase, giúp tiết kiệm số bước (step) và giảm khả năng nó sửa nhầm component tương tự ở chỗ khác.

Running UI Automation and QA Exploration Tests Directly from Cursor

Ngoài debugging bug đã biết, Puppeteer MCP trong Cursor còn cực kỳ hữu ích cho việc chạy các kịch bản automation nhiều bước (multi-step flows) và exploratory testing — dạng kiểm thử khám phá, nơi QA không theo một test case cố định mà chủ động "đi lang thang" trong app để phát hiện trạng thái bất thường, edge case chưa ai lường trước.

Với vai trò BA/QA, đây là cách bạn có thể dùng Agent như một tester ảo chạy song song với công việc thường ngày: giao cho nó một luồng nghiệp vụ (ví dụ "đăng ký tài khoản mới → xác thực email → đăng nhập → thêm sản phẩm vào giỏ → thanh toán"), để nó tự thực hiện từng bước, chụp ảnh minh chứng, và báo cáo lại bất kỳ điểm nào không như kỳ vọng.

Ví dụ prompt QA exploration

Explore the user registration and onboarding flow on
http://localhost:3000 and map out all the states you encounter.

1. Start at /signup, register a new account with a random test email
2. Try submitting the form with invalid inputs first (empty email,
   weak password, mismatched confirm-password) and screenshot each
   validation error state
3. Complete registration successfully, then follow the flow through
   email verification (use the mock verification link shown in the
   dev environment) and into the onboarding wizard
4. At each onboarding step, try clicking "Back" and "Skip" to see if
   the app handles those actions gracefully, or if it breaks/loses data
5. Try refreshing the page mid-onboarding and note whether progress is
   preserved
6. Once onboarding is complete, land on the dashboard and screenshot it
7. Summarize all the states and edge cases you found in a table:
   step, action, expected behavior, actual behavior, screenshot reference

Với dạng prompt này, bạn không yêu cầu Agent kiểm tra một assertion cụ thể — bạn để nó tự khám phá và báo cáo, đúng tinh thần exploratory testing. Kết quả trả về thường là một bảng tổng hợp giúp bạn nhanh chóng thấy được những góc khuất của app mà test case viết sẵn không bao giờ chạm tới.

Bảng các tool Puppeteer MCP thường dùng

Kết hợp các tool này, Agent có thể tự dựng nên cả một kịch bản automation phức tạp mà không cần bạn viết một dòng script Puppeteer thủ công nào — nhưng bạn vẫn hoàn toàn có thể yêu cầu nó xuất ra file test (ví dụ Playwright hoặc Jest + Puppeteer) từ chính những bước nó vừa chạy, để lưu lại thành regression test chính thức.

Mẹo: Sau khi Agent chạy xong một luồng exploratory testing, hãy yêu cầu thêm một bước: "Convert the steps above into a Playwright test file". Việc này biến một phiên khám phá ngẫu hứng thành tài sản automation lâu dài, thay vì chỉ là một lần chạy rồi bỏ.

Known Limitations and Workarounds for Puppeteer MCP in Cursor

Puppeteer MCP trong Cursor là một công cụ mạnh, nhưng không phải "cây đũa thần" — cần hiểu rõ giới hạn để dùng đúng chỗ và tránh mất thời gian debug sai hướng.

• Giới hạn số bước (step limit) và context window của Agent Mode. Với các flow dài (10–15 bước tương tác trình duyệt trở lên), Agent có thể bị cắt ngang giữa chừng, quên mất mục tiêu ban đầu, hoặc lặp lại một hành động đã làm. Nguyên nhân là toàn bộ lịch sử screenshot, DOM snapshot, console log đều ngốn context window (cửa sổ ngữ cảnh) khá nhanh.
• Tool call thỉnh thoảng thất bại lặng lẽ. Đôi khi puppeteer_click không tìm thấy selector do trang chưa render xong, hoặc do element nằm trong iframe/shadow DOM. Agent có thể không báo lỗi rõ ràng mà chỉ âm thầm "đoán" tiếp bước sau, dẫn đến kết luận sai.
• Yêu cầu xác nhận thủ công (manual approval) cho hành động nhạy cảm. Cursor sẽ chặn và hỏi lại khi Agent định thực hiện các thao tác có khả năng phá hoại (ví dụ xóa dữ liệu, submit form thanh toán thật, gọi API production). Đây là tính năng an toàn cần thiết, nhưng cũng có nghĩa các flow dài không thể chạy hoàn toàn "hands-off".
• Khác biệt giữa các model nền (underlying models) mà Cursor hỗ trợ. Cursor cho phép chọn nhiều model khác nhau cho Agent Mode (Claude, GPT, Gemini...). Khả năng dùng tool một cách chính xác, biết khi nào cần chụp screenshot để tự kiểm tra lại, khác nhau đáng kể giữa các model — cùng một prompt nhưng đổi model có thể cho kết quả chênh lệch rõ rệt về độ tin cậy.
• Môi trường trình duyệt headless (không giao diện) khác với trình duyệt local của bạn. Puppeteer MCP thường launch một Chromium headless riêng biệt, không có extension, không có cookie đăng nhập, không có session/auth state mà bạn đang dùng hằng ngày. Bug chỉ xảy ra khi đăng nhập bằng tài khoản thật, hoặc phụ thuộc vào một extension cụ thể, sẽ không tái hiện được trong môi trường này.

Workaround thực tế

• Chia nhỏ task thành nhiều lượt hội thoại thay vì giao một prompt "làm hết từ A đến Z". Sau mỗi 5–7 bước, dừng lại yêu cầu Agent tóm tắt trạng thái hiện tại trước khi tiếp tục — vừa giảm rủi ro lạc hướng, vừa giúp bạn theo dõi sát.
• Dùng persistent browser profile (chạy Puppeteer với userDataDir trỏ đến một thư mục cố định) để giữ lại cookie, session đăng nhập giữa các lần chạy, giảm khoảng cách với trình duyệt thật của bạn.
• Luôn verify thủ công sau khi Agent chạy xong một luồng dài. Đừng tin tuyệt đối vào báo cáo "mọi thứ đều pass" — tự tay mở lại app, click qua vài bước quan trọng để chắc chắn kết luận của Agent khớp với thực tế.
• Explicit hóa selector và điều kiện chờ trong prompt (ví dụ: "wait until the element with class .spinner disappears before clicking Submit") để giảm tình trạng tool call thất bại do timing.

Mẹo: Với các bug chỉ xảy ra khi đăng nhập, hãy tạo sẵn một tài khoản test cố định và yêu cầu Agent luôn đăng nhập bằng tài khoản đó ở đầu mỗi phiên, thay vì hy vọng nó tái sử dụng được session cũ — cách này ổn định hơn nhiều so với việc cố gắng đồng bộ cookie giữa trình duyệt thật và trình duyệt headless của Puppeteer MCP.