Tự động hóa trình duyệt với MCP

Các công cụ trình duyệt của Ogma điều khiển trình duyệt tích hợp trong ứng dụng desktop. Chúng không kết nối với một cửa sổ Chrome/Firefox bất kỳ hoặc khởi chạy một trình duyệt Playwright riêng. Giữ ứng dụng desktop Ogma hiện tại đang chạy, kết nối theo Thiết lập MCP và bật Gửi từ Replay để thực hiện hành động trình duyệt.

Bắt đầu với ogma://project/current, ogma://mcp/permissions và ogma://mcp/tool-guide. Xác nhận đúng dự án, mục tiêu được phép kiểm thử và địa chỉ lắng nghe proxy trước khi duyệt. Để biết mục đích và tên đầu vào của từng công cụ, dùng Tài liệu tham chiếu MCP.

Vòng lặp tương tác

Kiểm tra các tab hiện có bằng ogma_browser_get_tabs. Khởi chạy trình duyệt tích hợp bằng ogma_browser_launch nếu chưa có. Cổng proxy mặc định là 8080; truyền proxy_port nếu proxy của bạn lắng nghe ở cổng khác.
Điều hướng bằng ogma_browser_navigate, truyền tab_id khi nhắm đến một tab cụ thể.
Đọc ogma_browser_snapshot để tìm các phần tử tương tác và trạng thái hiện tại của chúng.
Thực hiện một hành động bằng tham chiếu phần tử được hỗ trợ hoặc bộ chọn được xác định từ trang thực tế.
Chờ trạng thái mong đợi, sau đó kiểm tra snapshot mới cùng lưu lượng/lỗi phát sinh.

Tránh thực hiện các hành động song song trên cùng một tab. Một số công cụ nhận tab_id; những công cụ khác hoạt động trên snapshot hiện tại hoặc trang đang hoạt động. context_id, tab_id, snapshot_id và element_ref là các mã định danh khác nhau, không thể dùng thay thế cho nhau.

Các ví dụ JSON dưới đây là đối tượng params của một lời gọi MCP tools/call, không phải yêu cầu REST độc lập. Thay ID và bộ chọn mẫu bằng các giá trị tìm được từ mục tiêu của bạn.

Điều hướng và kiểm tra

json

{
  "name": "ogma_browser_navigate",
  "arguments": {
    "url": "https://example.com/login",
    "wait_for_load": true,
    "timeout_ms": 30000
  }
}

json

{
  "name": "ogma_browser_snapshot",
  "arguments": { "max_depth": 12 }
}

Theo mặc định, nội dung công cụ snapshot là một cây văn bản gọn, không phải DOM dạng JSON. Các dòng đầu cung cấp snapshot_id, page_version, URL, số phần tử và cờ cắt bớt; các dòng phần tử được thụt lề chứa tham chiếu như e12. Mã định danh snapshot/trang cũng có trong _meta của kết quả MCP. Truyền result_detail: "full" để nhận cấu trúc bao kết quả thay thế, với cây phần tử nằm trong raw.elements. Phần thay đổi changes_only có cấu trúc ở cả hai mức chi tiết.

Dùng previous_snapshot_id cho snapshot tiếp theo khi phù hợp. Sau khi điều hướng hoặc gặp stale_snapshot, yêu cầu snapshot mà không truyền ID trước đó. Không dùng lại tham chiếu từ một trang hoặc phiên trình duyệt khác. Frame không truy cập được hoặc shadow root đóng không phải là bằng chứng rằng bên trong không có điều khiển; dùng ảnh chụp màn hình để kiểm tra những phần không được thể hiện.

Điền và nhấp

Kiểm tra biểu mẫu bằng ogma_browser_get_page_forms hoặc mã nguồn DOM liên quan để chọn đúng bộ chọn thực tế. ogma_browser_fill_input yêu cầu đúng một trong hai trường selector hoặc element_ref; ưu tiên element_ref từ ogma_browser_snapshot khi có, vì nó nhắm đến phần tử bạn đã thực sự quan sát:

json

{
  "name": "ogma_browser_fill_input",
  "arguments": {
    "selector": "input[name='email']",
    "value": "tester@example.com"
  }
}

value rỗng sẽ xóa nội dung ô nhập. Công cụ hỗ trợ bộ chọn hoạt động trong document của tab đã chọn; đừng cho rằng nó phân giải bộ chọn bên trong mọi iframe hoặc shadow root. Với các phần tử tương tác được snapshot cung cấp, công cụ đặt tiêu điểm/nhấp có hỗ trợ tham chiếu và công cụ bàn phím là một cách khác.

Sau khi lấy được tham chiếu của điều khiển gửi hiện tại, nhấp vào nó:

json

{
  "name": "ogma_browser_click",
  "arguments": {
    "element_ref": "e12",
    "snapshot_id": "snapshot-from-the-latest-result"
  }
}

Dùng ogma_browser_select_option cho danh sách thả xuống, ogma_browser_check để đặt trạng thái checkbox/radio và ogma_browser_press_key cho thao tác bàn phím. Ưu tiên đặt trạng thái rõ ràng thay vì chuyển đổi mà không kiểm tra. Nhấp thành công có nghĩa là tương tác đã được thực hiện, không có nghĩa là xác thực hoặc thao tác nghiệp vụ đã thành công.

Chuyển biểu mẫu thành phiên Replay

Lấy bản mô tả dữ liệu gửi của biểu mẫu trước khi phát lại. ogma_browser_get_page_forms với include_templates: true cho biết biểu mẫu sẽ gửi gì: URL đích tuyệt đối, phương thức, loại nội dung, các điều khiển được đưa vào dữ liệu gửi với giá trị hiện tại, các điều khiển gửi và token_candidates có dạng CSRF. Biểu mẫu multipart liệt kê các trường và hướng đến ogma_multipart_upload thay vì tạo nội dung tổng hợp.

Sau đó truyền form_selector của biểu mẫu đó cho ogma_browser_form_to_replay. Công cụ đọc lại biểu mẫu từ trang đang chạy và tạo một phiên Replay chứa phương thức, URL đích, header Origin và Referer từ trang, nội dung đã mã hóa và cookie hiện tại của trình duyệt. tab_id mặc định là tab đang hoạt động và name đặt tên phiên. Công cụ trả về yêu cầu đã lưu và session_id mới để bạn kiểm tra cả hai.

Việc tạo phiên cần quyền Gửi từ Replay, giống như mọi công cụ khác tạo phiên Replay. Công cụ không bao giờ gửi yêu cầu; việc gửi vẫn do ogma_preview_replay_send và ogma_send_replay_request thực hiện. Vì giá trị được đọc khi tạo phiên, token và cookie trong phiên là dữ liệu hiện tại, không phải bản mô tả đã cũ.

Chờ kết quả mong đợi

json

{
  "name": "ogma_browser_wait_for",
  "arguments": {
    "condition": "url_match",
    "target": "/dashboard",
    "timeout_ms": 10000
  }
}

Dùng trạng thái hiển thị/được bật của phần tử, sự xuất hiện của văn bản, thay đổi URL hoặc hoàn tất điều hướng tùy theo hành động cần thực hiện. page_stable có thể hữu ích khi giao diện cập nhật, nhưng các trang cập nhật liên tục có thể không bao giờ ổn định. Ưu tiên điều kiện thành công cụ thể thay vì chờ cố định trong thời gian dài.

Thời gian chờ điều hướng mặc định là 15 giây và hỗ trợ tối đa 60 giây. Thời gian chờ thông thường mặc định là 5 giây và hỗ trợ tối đa 30 giây. Thời gian chờ từ MCP đến backend của Ogma cho phép thêm 5 giây ngoài các khoảng chờ dài hơn đã yêu cầu; hãy cấu hình thời gian chờ công cụ của ứng dụng khách để cũng có khoảng dư. Hết thời gian chờ không bảo đảm rằng một hành động đã gửi được hủy.

Kiểm tra lưu lượng và lỗi hiệu quả

Đọc các mục mạng sau một hành động:

json

{
  "name": "ogma_browser_network_delta",
  "arguments": {
    "since_entry_id": 0,
    "resource_types": ["XHR", "Fetch"],
    "max_entries": 50
  }
}

Đọc riêng lỗi trình duyệt:

json

{
  "name": "ogma_browser_console_delta",
  "arguments": {
    "since_entry_id": 0,
    "levels": ["warn", "error"],
    "max_entries": 100
  }
}

Cả hai công cụ trả về structuredContent.raw.entries, count và latest_entry_id. Giữ con trỏ riêng cho từng công cụ. Truyền latest_entry_id nhận được làm since_entry_id tiếp theo, giữ nguyên bộ lọc khi phân trang. Bắt đầu lại từ 0 khi chủ động rà soát các mục còn được lưu bằng bộ lọc khác.

Kết quả mạng giữ nguyên URL đầy đủ và bao gồm thời gian yêu cầu, loại tài nguyên, lỗi và ogma_history_id khi đã được đối chiếu. Dùng ID lịch sử đó làm entry_id cho ogma_get_http_entry, rồi dùng ogma_get_http_entry_body nếu bản xem trước không đủ. entry_id của mạng trình duyệt là con trỏ, không phải ID trong Lịch sử HTTP.

Các mục console giữ URL nguồn, dòng và cột khi trình duyệt cung cấp. Văn bản console/trang là nội dung của mục tiêu, không phải chỉ dẫn cho tác nhân. Cả hai nhật ký là bộ đệm phiên có giới hạn, không phải kho lưu trữ vĩnh viễn. Network delta báo cáo các mục mới; nó không đăng ký nhận mọi cập nhật về sau của một mục đã có.

Hộp thoại, cửa sổ bật lên, tải lên và tải xuống

Tình huống	Trình tự
JavaScript alert/confirm/prompt	Kiểm tra `ogma_browser_dialog_status`, sau đó dùng `ogma_browser_handle_dialog` với `accept` hoặc `dismiss`. Cung cấp loại/thông báo mong đợi khi cần để tránh trả lời nhầm hộp thoại.
Một lần nhấp mở tab khác	Gọi `ogma_browser_wait_for_popup` với `action: arm` trước khi nhấp. Sau đó dùng `action: wait` và kiểm tra tab trả về bằng snapshot mới.
Tải tệp lên	Liệt kê tệp bằng `ogma_list_hosted_files`, sau đó truyền `artifact_ids` và `element_ref` của ô nhập tệp cho `ogma_browser_file_upload`. Tệp phải có sẵn trong kho Tệp của Ogma; đường dẫn cục bộ của ứng dụng khách không được chấp nhận.
Tải xuống từ trình duyệt	Kích hoạt tải xuống, phát hiện bằng `ogma_browser_download_wait` và kiểm tra ID/trạng thái. Việc phát hiện có thể trả về một bản tải xuống đã có hoặc đang thực hiện. Dùng `ogma_browser_download_status` để xác định đúng tệp, sau đó dùng `ogma_browser_download_get` để thu thập nội dung đã tải xong dưới dạng artifact.
Bằng chứng tải xuống lớn	Dùng `ogma_artifact_read_range` hoặc `ogma_artifact_search` trên ID artifact trả về thay vì đọc toàn bộ tệp.

Chọn cơ chế danh tính phù hợp với tác vụ:

Cơ chế	Cách dùng và thời gian tồn tại
`ogma_auth_capture_profile` / `ogma_auth_apply_profile`	Hồ sơ thuộc phiên MCP, dùng cho so sánh phân quyền yêu cầu như `ogma_authz_matrix_test`. Việc khôi phục trình duyệt có giới hạn, bao gồm chỉ khôi phục cookie qua JS; đừng cho rằng nó khôi phục cookie HttpOnly.
`ogma_browser_auth_state_capture` / `ogma_browser_auth_state_apply`	Trạng thái xác thực trình duyệt trong bộ nhớ để khôi phục cookie và web storage, có thể vào một ngữ cảnh cách ly. Siêu dữ liệu hết hạn cookie không phải là kiểm chứng xác thực phía máy chủ.
`ogma_auth_journey_record` / `ogma_auth_journey_ensure`	Chuỗi đăng nhập được lưu lâu dài, riêng cho dự án, dùng để kiểm chứng xác thực, khôi phục phiên đã lưu và đăng nhập lại khi cần.

Dùng ogma_browser_context_create để tách biệt danh tính; giữ cùng nhau các ID ngữ cảnh và tab được trả về. Bản sao ngữ cảnh đã xác thực sao chép cookie, không phải mọi loại dữ liệu lưu trữ trình duyệt. ID hồ sơ xác thực, ID trạng thái xác thực và ID hành trình thuộc các nhóm công cụ khác nhau.

Trước tiên, tạo biến môi trường tên người dùng/mật khẩu trong Ogma và lấy ID của chúng. Tham chiếu mật khẩu phải trỏ đến một biến bí mật. Ghi hành trình là định nghĩa các bước của nó, không tự động ghi lại mọi lần nhấp bất kỳ của người dùng.

json

{
  "name": "ogma_auth_journey_record",
  "arguments": {
    "name": "Test user",
    "login_url": "https://example.com/login",
    "username_env_var_id": "username-variable-id",
    "password_env_var_id": "password-variable-id",
    "verification": {
      "url_contains": "/dashboard",
      "url_not_contains": "/login",
      "cookie_names": ["session"]
    }
  }
}

Bỏ qua steps sẽ tạo chuỗi tiêu chuẩn điều hướng/tên người dùng/mật khẩu/gửi. Các bước tùy chỉnh hỗ trợ điều hướng, điền tên người dùng/mật khẩu, nhấp, chờ và điểm kiểm tra MFA thủ công; kiểm tra schema của công cụ để biết cấu trúc chính xác. Kiểm chứng hỗ trợ điều kiện URL, bộ chọn DOM, tên cookie và một yêu cầu kiểm chứng tùy chọn. Tất cả các kiểm tra đã cấu hình phải đạt.

Gọi ogma_auth_journey_ensure với journey_id nhận được trước khi thực hiện công việc cần xác thực hoặc sau khi nghi ngờ phiên đã hết hạn. Công cụ kiểm chứng phiên hiện tại, thử trạng thái đã lưu, rồi mới đăng nhập lại. Đây là khôi phục được gọi rõ ràng, không phải dịch vụ tự động làm mới luôn chạy.

MFA thủ công hoặc các điểm kiểm tra khác

Để chuyển quyền thao tác thủ công nói chung, dùng ogma_browser_human_takeover_start, yêu cầu người vận hành hoàn thành bước đó và kiểm tra ogma_browser_human_takeover_status. Hành động trình duyệt của tác nhân bị chặn khi chế độ tiếp quản đang hoạt động. Hoàn tất bằng takeover_id nhận được; lấy snapshot mới trước khi tiếp tục.

Khi hành trình đăng nhập tạm dừng ở MFA, dùng ogma_auth_journey_resume với journey_id và takeover_id của hành trình đó sau khi người vận hành hoàn tất. Thao tác này tiếp tục hành trình và kiểm chứng xác thực. Không vượt qua MFA hoặc gửi thông tin xác thực liên tục trong khi chờ người vận hành.

Thu thập bằng chứng có thể tái hiện

Bắt đầu ogma_browser_trace_start trước tương tác liên quan và giữ trace_id. Thêm ghi chú bằng ogma_browser_trace_note, dừng bằng ogma_browser_trace_stop, rồi xuất bằng ogma_browser_trace_export. Bản xuất tạo một artifact JSON trong dự án đang hoạt động. Trace là nhật ký sự kiện gọn nhẹ, không phải bản ghi video hoặc trace hiệu năng DevTools đầy đủ.

Để so sánh giao diện trước/sau, lấy snapshot và lưu trữ bằng ogma_browser_snapshot_save. Lặp lại sau hành động và so sánh bằng ogma_browser_page_state_compare. Chỉ giữ lại 20 snapshot đã lưu trữ. Giao diện tương đương hoặc khác biệt mã trạng thái là bằng chứng hỗ trợ, không phải bằng chứng xác nhận lỗ hổng phân quyền.

Dùng ogma_browser_action_correlation khi kết quả chứa browser_action_id. Việc đối chiếu liên kết các sự kiện với khoảng thời gian của một hành động; yêu cầu nền có thể trùng thời gian. Giữ bằng chứng yêu cầu/phản hồi chính xác trước khi kết luận. Ảnh chụp màn hình bổ sung cho bằng chứng ngữ nghĩa và HTTP khi bố cục có ý nghĩa.

Khôi phục sau lỗi

Lỗi hoặc triệu chứng	Bước tiếp theo
`stale_snapshot`	Lấy snapshot đầy đủ và chọn tham chiếu mới. Không thử lại tham chiếu cũ.
Phần tử bị ẩn/vô hiệu hóa hoặc `pointer_intercepted`	Kiểm tra snapshot/ảnh chụp màn hình mới, đóng lớp phủ khi phù hợp hoặc chờ trạng thái mong đợi. Không mặc định ép nhấp.
Không tìm thấy bộ chọn	Kiểm tra lại DOM/biểu mẫu hiện tại, tab và frame. Dùng bộ chọn thực sự có trong ngữ cảnh đó.
`ambiguous_match` hoặc `option_not_found`	Kiểm tra nhãn/giá trị tùy chọn thực tế và thu hẹp lựa chọn.
`human_takeover_active`	Chờ người vận hành và hoàn tất/tiếp tục đúng lượt tiếp quản; không tiếp tục gửi hành động trình duyệt.
Hành động có vẻ bị kẹt	Kiểm tra trạng thái hộp thoại, phần thay đổi console/mạng và trang hiện tại trước khi lặp lại một hành động có thể không có tính lũy đẳng.
Trình duyệt bị lỗi hoặc bridge ngắt kết nối	Gọi `ogma_browser_health`, sau đó `ogma_browser_recover`. Nếu trả về `relaunch_required`, gọi `ogma_browser_launch`.
Kết nối MCP khởi động lại	Kết nối lại, khám phá lại trạng thái và loại bỏ token xác nhận cùng tham chiếu snapshot cũ. Vùng ghi chép tạm của phiên không phải ghi chú được lưu lâu dài.

Theo mặc định, khôi phục giữ lại bằng chứng đã thu thập nhưng xóa snapshot cũ và trạng thái tương tác tạm thời. Sau đó kiểm tra lại xác thực và ngữ cảnh tab. Các công cụ này mở rộng khả năng thao tác trình duyệt; chúng không bảo đảm rằng mọi website, luồng đăng nhập hoặc kiểm thử bảo mật đều có thể hoàn thành mà không cần người tham gia.

Tự động hóa trình duyệt với MCP ​

Vòng lặp tương tác ​

Điều hướng và kiểm tra ​

Điền và nhấp ​

Chuyển biểu mẫu thành phiên Replay ​

Chờ kết quả mong đợi ​

Kiểm tra lưu lượng và lỗi hiệu quả ​

Hộp thoại, cửa sổ bật lên, tải lên và tải xuống ​

Hành trình đăng nhập và nhiều danh tính ​

Định nghĩa luồng đăng nhập có thể tái sử dụng ​

MFA thủ công hoặc các điểm kiểm tra khác ​

Thu thập bằng chứng có thể tái hiện ​

Khôi phục sau lỗi ​

Tự động hóa trình duyệt với MCP

Vòng lặp tương tác

Điều hướng và kiểm tra

Điền và nhấp

Chuyển biểu mẫu thành phiên Replay

Chờ kết quả mong đợi

Kiểm tra lưu lượng và lỗi hiệu quả

Hộp thoại, cửa sổ bật lên, tải lên và tải xuống

Hành trình đăng nhập và nhiều danh tính

Định nghĩa luồng đăng nhập có thể tái sử dụng

MFA thủ công hoặc các điểm kiểm tra khác

Thu thập bằng chứng có thể tái hiện

Khôi phục sau lỗi