MCP से ब्राउज़र स्वचालन

Ogma के ब्राउज़र उपकरण उसके अंतर्निहित डेस्कटॉप ब्राउज़र को नियंत्रित करते हैं। वे किसी भी मनमानी Chrome या Firefox विंडो से नहीं जुड़ते और अलग Playwright ब्राउज़र शुरू नहीं करते। वर्तमान Ogma डेस्कटॉप ऐप चालू रखें, MCP सेटअप के अनुसार कनेक्ट करें और ब्राउज़र कार्रवाइयों के लिए दोबारा अनुरोध भेजना सक्षम करें।

ogma://project/current, ogma://mcp/permissions और ogma://mcp/tool-guide से शुरू करें। ब्राउज़ करने से पहले अपेक्षित परियोजना, अधिकृत लक्ष्य और प्रॉक्सी लिसनर की पुष्टि करें। हर उपकरण के उद्देश्य और इनपुट नामों के लिए MCP संदर्भ उपयोग करें।

इंटरैक्शन का चक्र

ogma_browser_get_tabs से मौजूदा टैब की जाँच करें। अंतर्निहित ब्राउज़र उपलब्ध न हो, तो ogma_browser_launch से उसे लॉन्च करें। उसका डिफ़ॉल्ट प्रॉक्सी पोर्ट 8080 है; आपका लिसनर दूसरा पोर्ट उपयोग करता हो, तो proxy_port दें।
ogma_browser_navigate से नेविगेट करें और किसी विशिष्ट टैब को लक्षित करते समय tab_id दें।
इंटरैक्टिव तत्व और उनकी वर्तमान स्थिति जानने के लिए ogma_browser_snapshot पढ़ें।
समर्थित तत्व संदर्भ या वास्तविक पृष्ठ से प्राप्त सिलेक्टर का उपयोग करके एक कार्रवाई करें।
अपेक्षित स्थिति की प्रतीक्षा करें, फिर नया स्नैपशॉट और उससे उत्पन्न ट्रैफ़िक तथा त्रुटियों की जाँच करें।

एक ही टैब पर समानांतर कार्रवाइयों से बचें। कुछ उपकरण tab_id स्वीकार करते हैं; दूसरे वर्तमान स्नैपशॉट या सक्रिय पृष्ठ पर काम करते हैं। context_id, tab_id, snapshot_id और element_ref अलग-अलग पहचानकर्ता हैं और एक-दूसरे की जगह उपयोग नहीं किए जा सकते।

नीचे के JSON उदाहरण params ऑब्जेक्ट दिखाते हैं, जो MCP tools/call में दिया जाता है; वे स्वतंत्र REST अनुरोध नहीं हैं। उदाहरण की ID और सिलेक्टर को अपने लक्ष्य से खोजे गए मानों से बदलें।

नेविगेट करें और जाँचें

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 }
}

डिफ़ॉल्ट रूप से स्नैपशॉट उपकरण की सामग्री एक संक्षिप्त टेक्स्ट ट्री होती है, JSON DOM नहीं। उसकी हेडर पंक्तियाँ snapshot_id, page_version, URL, तत्वों की संख्या और सामग्री कटने के फ़्लैग देती हैं; इंडेंट की गई तत्व पंक्तियों में e12 जैसे संदर्भ होते हैं। स्नैपशॉट और पृष्ठ के पहचानकर्ता MCP परिणाम के _meta में भी होते हैं। इसके बजाय संरचित आवरण पाने के लिए result_detail: "full" दें, जिसमें तत्वों का ट्री raw.elements के अंतर्गत होता है। changes_only का अंतर दोनों विवरण स्तरों पर संरचित होता है।

उचित होने पर अगले स्नैपशॉट के लिए previous_snapshot_id उपयोग करें। नेविगेशन या stale_snapshot के बाद उस पिछली ID के बिना स्नैपशॉट माँगें। किसी दूसरे पृष्ठ या ब्राउज़र सत्र के संदर्भ दोबारा उपयोग न करें। पहुँच से बाहर फ़्रेम या बंद शैडो रूट इस बात का साक्ष्य नहीं है कि उसमें कोई नियंत्रण नहीं है; दृश्य अंतराल की जाँच के लिए स्क्रीनशॉट उपयोग करें।

भरें और क्लिक करें

वास्तविक सिलेक्टर चुनने के लिए ogma_browser_get_page_forms या संबंधित DOM स्रोत से फ़ॉर्म की जाँच करें। ogma_browser_fill_input के लिए selector या element_ref में से ठीक एक आवश्यक है; उपलब्ध होने पर element_ref को प्राथमिकता दें जो ogma_browser_snapshot से मिला है, क्योंकि वह उसी तत्व को लक्षित करता है जिसे आपने वास्तव में देखा है:

json

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

खाली value इनपुट साफ़ कर देता है। सिलेक्टर सहायक चुने गए टैब के दस्तावेज़ में काम करता है; यह न मानें कि वह हर iframe या शैडो रूट के भीतर सिलेक्टर ढूँढ सकता है। स्नैपशॉट में उपलब्ध इंटरैक्टिव तत्वों के लिए संदर्भ-आधारित फ़ोकस और क्लिक तथा कीबोर्ड उपकरण दूसरा रास्ता देते हैं।

वर्तमान सबमिट नियंत्रण का संदर्भ मिलने के बाद उस पर क्लिक करें:

json

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

ड्रॉपडाउन के लिए ogma_browser_select_option, चेकबॉक्स या रेडियो की स्थिति सेट करने के लिए ogma_browser_check और कीबोर्ड कार्रवाइयों के लिए ogma_browser_press_key उपयोग करें। बिना स्थिति देखे टॉगल करने के बजाय स्पष्ट स्थिति परिवर्तन करें। सफल क्लिक का अर्थ है कि इंटरैक्शन चला, यह नहीं कि प्रमाणीकरण या कारोबारी कार्रवाई सफल हुई।

फ़ॉर्म को रीप्ले सत्र में बदलें

रीप्ले करने से पहले फ़ॉर्म से भेजे जाने वाले अनुरोध का रूप देखें। ogma_browser_get_page_forms, include_templates: true के साथ यह बताता है कि फ़ॉर्म क्या भेजेगा: कार्रवाई का पूर्ण URL, विधि, सामग्री का प्रकार, वर्तमान मानों सहित भेजे जाने वाले नियंत्रण, सबमिट नियंत्रण और CSRF जैसे token_candidates। मल्टीपार्ट फ़ॉर्म अपने फ़ील्ड की सूची देते हैं और कृत्रिम बॉडी बनाने के बजाय ogma_multipart_upload की ओर निर्देशित करते हैं।

फिर उस फ़ॉर्म का form_selector, ogma_browser_form_to_replay को दें। वह लाइव पृष्ठ से फ़ॉर्म को फिर से पढ़ता है और विधि, कार्रवाई का URL, पृष्ठ के Origin और Referer हेडर, एन्कोडेड बॉडी तथा ब्राउज़र की वर्तमान कुकी वाला रीप्ले सत्र बनाता है। tab_id डिफ़ॉल्ट रूप से सक्रिय टैब होता है और name सत्र का नाम देता है। वह सहेजा गया अनुरोध और नया session_id लौटाता है ताकि आप दोनों की पुष्टि कर सकें।

अन्य सभी रीप्ले सत्र बनाने वाले उपकरणों की तरह सत्र बनाने के लिए दोबारा अनुरोध भेजना अनुमति आवश्यक है। उपकरण कभी अनुरोध नहीं भेजता; भेजने का काम ogma_preview_replay_send और ogma_send_replay_request के पास रहता है। चूँकि मान सत्र बनाते समय पढ़े जाते हैं, उसमें टोकन और कुकी वर्तमान होते हैं, पुराने रूप से लिए गए नहीं।

अपेक्षित परिणाम की प्रतीक्षा करें

json

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

कार्रवाई से अपेक्षित काम के अनुसार तत्व का दिखाई देना या सक्षम होना, पाठ की मौजूदगी, URL में बदलाव या नेविगेशन पूरा होना उपयोग करें। रेंडर किए गए अपडेट के लिए page_stable मदद कर सकता है, लेकिन लगातार अपडेट होने वाले पृष्ठ कभी स्थिर नहीं हो सकते। लंबे निश्चित विराम के बजाय सफलता की विशिष्ट शर्त चुनें।

नेविगेशन की प्रतीक्षा डिफ़ॉल्ट रूप से 15 सेकंड है और अधिकतम 60 सेकंड समर्थित है। सामान्य प्रतीक्षा डिफ़ॉल्ट रूप से 5 सेकंड है और अधिकतम 30 सेकंड समर्थित है। Ogma का MCP-से-बैकएंड टाइमआउट माँगी गई लंबी प्रतीक्षाओं से अतिरिक्त 5 सेकंड की गुंजाइश देता है; क्लाइंट का अपना उपकरण टाइमआउट भी पर्याप्त अतिरिक्त समय के साथ सेट करें। टाइमआउट होना यह सुनिश्चित नहीं करता कि सबमिट की गई कार्रवाई रद्द हो गई है।

ट्रैफ़िक और त्रुटियों की कुशल जाँच

कार्रवाई के बाद नेटवर्क प्रविष्टियाँ पढ़ें:

json

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

ब्राउज़र की त्रुटियाँ अलग से पढ़ें:

json

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

दोनों उपकरण structuredContent.raw.entries, count और latest_entry_id लौटाते हैं। हर उपकरण के लिए अलग कर्सर रखें। लौटाए गए latest_entry_id को अगले since_entry_id के रूप में दें और परिणामों के पृष्ठ बदलते समय फ़िल्टर वही रखें। अलग फ़िल्टर से सहेजी गई प्रविष्टियों की जानबूझकर समीक्षा करते समय फिर 0 से शुरू करें।

नेटवर्क परिणाम पूरे URL सुरक्षित रखते हैं और उनमें अनुरोध का समय, संसाधन का प्रकार, त्रुटियाँ तथा संबंधित होने पर ogma_history_id शामिल होते हैं। उस इतिहास ID को entry_id के रूप में ogma_get_http_entry को दें, फिर पूर्वावलोकन अपर्याप्त हो तो ogma_get_http_entry_body उपयोग करें। ब्राउज़र नेटवर्क का entry_id कर्सर है, HTTP इतिहास की ID नहीं।

ब्राउज़र द्वारा दिए जाने पर कंसोल प्रविष्टियाँ स्रोत URL, पंक्ति और कॉलम सुरक्षित रखती हैं। कंसोल या पृष्ठ का पाठ लक्ष्य की सामग्री है, एजेंट के निर्देश नहीं। दोनों लॉग सीमित सत्र बफ़र हैं, स्थायी संग्रह नहीं। नेटवर्क डेल्टा नई प्रविष्टियाँ बताता है; वह मौजूदा प्रविष्टि के हर बाद के अपडेट की सदस्यता नहीं है।

डायलॉग, पॉपअप, अपलोड और डाउनलोड

स्थिति	क्रम
JavaScript अलर्ट, पुष्टि या इनपुट प्रॉम्प्ट	`ogma_browser_dialog_status` की जाँच करें, फिर `ogma_browser_handle_dialog` को `accept` या `dismiss` के साथ उपयोग करें। गलत डायलॉग का उत्तर देने से बचने के लिए आवश्यकता होने पर अपेक्षित प्रकार या संदेश दें।
क्लिक से दूसरा टैब खुलता है	क्लिक करने से पहले `ogma_browser_wait_for_popup` को `action: arm` के साथ कॉल करें। फिर `action: wait` उपयोग करें और लौटाए गए टैब को नए स्नैपशॉट से जाँचें।
फ़ाइल अपलोड	`ogma_list_hosted_files` से फ़ाइलों की सूची लें, फिर `artifact_ids` और फ़ाइल इनपुट का `element_ref`, `ogma_browser_file_upload` को दें। फ़ाइलें पहले से Ogma के फ़ाइल भंडार में होनी चाहिए; क्लाइंट के स्थानीय पथ स्वीकार नहीं होते।
ब्राउज़र डाउनलोड	डाउनलोड शुरू करें, `ogma_browser_download_wait` से उसे पहचानें और उसकी ID तथा स्थिति जाँचें। पहचान किसी मौजूदा या चल रहे डाउनलोड को लौटा सकती है। इच्छित फ़ाइल पहचानने के लिए `ogma_browser_download_status` उपयोग करें, फिर पूरा हुआ कंटेंट आर्टिफ़ैक्ट के रूप में लेने के लिए `ogma_browser_download_get` उपयोग करें।
बड़ा डाउनलोड किया गया साक्ष्य	पूरी फ़ाइल पढ़ने के बजाय लौटाई गई आर्टिफ़ैक्ट ID पर `ogma_artifact_read_range` या `ogma_artifact_search` उपयोग करें।

काम के अनुसार पहचान का तंत्र चुनें:

तंत्र	उपयोग और जीवनकाल
`ogma_auth_capture_profile` / `ogma_auth_apply_profile`	MCP सत्र की प्रोफ़ाइल, जो `ogma_authz_matrix_test` जैसी अनुरोध प्राधिकरण तुलना में उपयोग होती हैं। ब्राउज़र में बहाल करने की सीमाएँ हैं, जैसे केवल JS से कुकी बहाल करना; यह न मानें कि HttpOnly कुकी बहाल हो जाती हैं।
`ogma_browser_auth_state_capture` / `ogma_browser_auth_state_apply`	कुकी और वेब स्टोरेज बहाल करने के लिए मेमोरी में ब्राउज़र प्रमाणीकरण स्थितियाँ, वैकल्पिक रूप से अलग संदर्भ में। कुकी की समाप्ति का मेटाडेटा सर्वर की ओर प्रमाणीकरण की पुष्टि नहीं है।
`ogma_auth_journey_record` / `ogma_auth_journey_ensure`	स्थायी, परियोजना-विशिष्ट लॉगिन क्रम जो प्रमाणीकरण की पुष्टि करते हैं, सहेजा गया सत्र बहाल करते हैं और आवश्यकता होने पर लॉगिन दोहराते हैं।

पहचान अलग रखने के लिए ogma_browser_context_create उपयोग करें; उसकी लौटाई गई संदर्भ और टैब ID साथ रखें। प्रमाणीकृत संदर्भ का क्लोन कुकी कॉपी करता है, ब्राउज़र के हर प्रकार का स्टोरेज नहीं। प्रमाणीकरण प्रोफ़ाइल ID, प्रमाणीकरण स्थिति ID और प्रक्रिया ID अलग उपकरण समूहों से संबंधित हैं।

पहले Ogma में उपयोगकर्ता नाम और पासवर्ड के परिवेश चर बनाएँ और उनकी ID लें। पासवर्ड का संदर्भ गुप्त चर की ओर होना चाहिए। प्रक्रिया रिकॉर्ड करना उसके चरण तय करता है; यह उपयोगकर्ता के मनमाने क्लिक अपने-आप रिकॉर्ड नहीं करता।

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"]
    }
  }
}

steps छोड़ देने पर नेविगेट करने, उपयोगकर्ता नाम और पासवर्ड भरने तथा सबमिट करने का मानक क्रम बनता है। कस्टम चरण नेविगेशन, उपयोगकर्ता नाम और पासवर्ड भरने, क्लिक, प्रतीक्षा और मैन्युअल MFA चेकपॉइंट का समर्थन करते हैं; उनके सटीक रूप के लिए उपकरण का स्कीमा देखें। सत्यापन URL की शर्तों, DOM सिलेक्टर, कुकी के नाम और वैकल्पिक सत्यापन अनुरोध का समर्थन करता है। कॉन्फ़िगर की गई सभी जाँच सफल होनी चाहिए।

प्रमाणीकृत काम से पहले या समाप्ति का संदेह होने पर ogma_auth_journey_ensure को लौटाए गए journey_id के साथ कॉल करें। वह वर्तमान सत्र का सत्यापन करता है, सहेजी गई स्थिति आज़माता है और उसके बाद ही लॉगिन दोहराता है। यह स्पष्ट रूप से बुलाई गई रिकवरी है, हमेशा चलने वाली स्वचालित रिफ़्रेश सेवा नहीं।

मैन्युअल MFA या अन्य चेकपॉइंट

सामान्य मैन्युअल नियंत्रण हस्तांतरण के लिए ogma_browser_human_takeover_start उपयोग करें, ऑपरेटर से चरण पूरा करने को कहें और ogma_browser_human_takeover_status जाँचें। नियंत्रण हस्तांतरण सक्रिय रहने पर एजेंट की ब्राउज़र कार्रवाइयाँ अवरुद्ध रहती हैं। लौटाए गए takeover_id से इसे पूरा करें; आगे बढ़ने से पहले नया स्नैपशॉट लें।

जब लॉगिन प्रक्रिया MFA पर रुकती है, तो ऑपरेटर के पूरा करने के बाद ogma_auth_journey_resume को उस प्रक्रिया के journey_id और takeover_id के साथ उपयोग करें। यह प्रक्रिया जारी रखता है और प्रमाणीकरण का सत्यापन करता है। ऑपरेटर की प्रतीक्षा करते समय MFA बायपास न करें और बार-बार क्रेडेंशियल सबमिट न करें।

दोहराए जा सकने वाले साक्ष्य कैप्चर करें

संबंधित इंटरैक्शन से पहले ogma_browser_trace_start शुरू करें और उसका trace_id रखें। ogma_browser_trace_note से नोट्स जोड़ें, ogma_browser_trace_stop से रोकें, फिर ogma_browser_trace_export से निर्यात करें। निर्यात सक्रिय परियोजना में JSON आर्टिफ़ैक्ट बनाता है। ट्रेस हल्के इवेंट लॉग होते हैं, वीडियो रिकॉर्डिंग या DevTools के पूर्ण प्रदर्शन ट्रेस नहीं।

UI की पहले और बाद की तुलना के लिए स्नैपशॉट लें और ogma_browser_snapshot_save से संग्रहित करें। कार्रवाई के बाद दोहराएँ और ogma_browser_page_state_compare से तुलना करें। केवल 20 संग्रहित स्नैपशॉट रखे जाते हैं। UI की समानता या स्थिति कोड में अंतर सहायक साक्ष्य है, प्राधिकरण भेद्यता का प्रमाण नहीं।

ogma_browser_action_correlation उपयोग करें जब परिणाम में browser_action_id हो। सहसंबंध इवेंट को कार्रवाई के समय-अंतराल से जोड़ता है; पृष्ठभूमि अनुरोध उसी अवधि में आ सकते हैं। निष्कर्ष निकालने से पहले अनुरोध और प्रतिक्रिया के सटीक साक्ष्य सुरक्षित रखें। लेआउट महत्वपूर्ण होने पर स्क्रीनशॉट अर्थ-आधारित और HTTP साक्ष्यों के पूरक होते हैं।

त्रुटियों से रिकवरी

त्रुटि या लक्षण	अगला चरण
`stale_snapshot`	पूरा स्नैपशॉट लें और नया संदर्भ चुनें। पुराने संदर्भ से दोबारा प्रयास न करें।
तत्व छिपा या अक्षम है, या `pointer_intercepted`	नया स्नैपशॉट या स्क्रीनशॉट जाँचें, उचित होने पर ऊपर की परतें बंद करें या अपेक्षित स्थिति की प्रतीक्षा करें। डिफ़ॉल्ट रूप से ज़बरदस्ती क्लिक न करें।
सिलेक्टर नहीं मिला	वर्तमान DOM या फ़ॉर्म, टैब और फ़्रेम की फिर जाँच करें। उस संदर्भ में वास्तव में मौजूद सिलेक्टर उपयोग करें।
`ambiguous_match` या `option_not_found`	विकल्पों के वास्तविक लेबल और मान देखें और चयन अधिक सटीक करें।
`human_takeover_active`	ऑपरेटर की प्रतीक्षा करें और सही नियंत्रण हस्तांतरण पूरा करें या फिर शुरू करें; ब्राउज़र कार्रवाइयाँ देते न रहें।
कार्रवाई अटकी लगती है	ऐसी कार्रवाई दोहराने से पहले, जिसका दोबारा चलना अतिरिक्त प्रभाव डाल सकता है, डायलॉग की स्थिति, कंसोल और नेटवर्क डेल्टा तथा वर्तमान पृष्ठ जाँचें।
ब्राउज़र क्रैश हुआ या ब्रिज डिस्कनेक्ट हुआ	`ogma_browser_health` और फिर `ogma_browser_recover` कॉल करें। यदि वह `relaunch_required` लौटाए, तो `ogma_browser_launch` कॉल करें।
MCP कनेक्शन दोबारा शुरू हुआ	फिर कनेक्ट करें, स्थिति दोबारा खोजें और पुराने पुष्टि टोकन तथा स्नैपशॉट संदर्भ छोड़ दें। सत्र के अस्थायी स्क्रैचपैड स्थायी नोट्स नहीं हैं।

रिकवरी डिफ़ॉल्ट रूप से कैप्चर किए गए साक्ष्य सुरक्षित रखती है, लेकिन पुराने स्नैपशॉट और अस्थायी इंटरैक्शन स्थिति साफ़ करती है। बाद में प्रमाणीकरण और टैब के संदर्भ की फिर जाँच करें। ये उपकरण ब्राउज़र कवरेज बेहतर करते हैं; वे यह सुनिश्चित नहीं करते कि हर वेबसाइट, लॉगिन प्रवाह या सुरक्षा परीक्षण मानवीय मदद के बिना पूरा हो सकता है।

MCP से ब्राउज़र स्वचालन ​

इंटरैक्शन का चक्र ​

नेविगेट करें और जाँचें ​

भरें और क्लिक करें ​

फ़ॉर्म को रीप्ले सत्र में बदलें ​

अपेक्षित परिणाम की प्रतीक्षा करें ​

ट्रैफ़िक और त्रुटियों की कुशल जाँच ​

डायलॉग, पॉपअप, अपलोड और डाउनलोड ​

लॉगिन प्रक्रियाएँ और कई पहचान ​

दोबारा उपयोग किया जा सकने वाला लॉगिन तय करें ​

मैन्युअल MFA या अन्य चेकपॉइंट ​

दोहराए जा सकने वाले साक्ष्य कैप्चर करें ​

त्रुटियों से रिकवरी ​

MCP से ब्राउज़र स्वचालन

इंटरैक्शन का चक्र

नेविगेट करें और जाँचें

भरें और क्लिक करें

फ़ॉर्म को रीप्ले सत्र में बदलें

अपेक्षित परिणाम की प्रतीक्षा करें

ट्रैफ़िक और त्रुटियों की कुशल जाँच

डायलॉग, पॉपअप, अपलोड और डाउनलोड

लॉगिन प्रक्रियाएँ और कई पहचान

दोबारा उपयोग किया जा सकने वाला लॉगिन तय करें

मैन्युअल MFA या अन्य चेकपॉइंट

दोहराए जा सकने वाले साक्ष्य कैप्चर करें

त्रुटियों से रिकवरी