मास्त्रा CAPTCHA सॉल्वर एकीकरण: एक व्यावहारिक MCP मार्गदर्शिका

संक्षेप (TL;DR)

• Mastra का MCPClient एक लोकल CAPTCHA सॉल्वर प्रोसेस लॉन्च कर सकता है और उसके टूल्स को stdio के ज़रिये ढूँढ सकता है।
• listTools() नेमस्पेस्ड टूल्स लौटाता है, जैसे इस उदाहरण में सर्वर की के लिए capsolver_get_supported_captchas।
• किसी भाषा मॉडल को शामिल करने या पेड CAPTCHA टास्क सबमिट करने से ठीक पहले एक capability क्वेरी चलाएँ।
• हर डिसकवर्ड capability को ऑटोमैटिकली अटैच करने के बजाय, सिर्फ वे टूल चुनें जिनकी आपके एजेंट को ज़रूरत है।
• जब स्टैंडअलोन जाँच पूरी हो जाए तो MCP क्लाइंट को बंद करें, और सॉल्वर के रिज़ल्ट को ब्राउज़र‑वर्कफ़्लो की completion से अलग पहचानें।

Mastra CAPTCHA सॉल्वर इंटीग्रेशन एक TypeScript एप्लिकेशन को वेरिफिकेशन चेकपॉइंट के लिए एक परिभाषित टूल सीमा देता है। ब्राउज़र वर्कफ़्लो को पहले से पता हो सकता है कि चैलेंज से पहले और बाद में क्या करना है, जबकि एजेंट को चैलेंज ऑपरेशन माँगने का एक सपोर्टेड तरीका चाहिए। MCP यह capability कनेक्ट करता है, बिना सॉल्वर के अंडरलाईंग API के ऊपर कोई अतिरिक्त रैपर माँगे।

इस उदाहरण में लोकल सर्वर CapSolver देता है। गाइड असली Mastra क्लाइंट के ज़रिये इसके टूल्स खोजता है और supported-types क्वेरी चलाता है। फिर यह समझाता है कि एजेंट को सही सबसेट कैसे अटैच करें और टूल रिस्पॉन्स तथा पूरे वेब टास्क के बीच फ़र्क कैसे बचाए रखें। उदाहरण एक लोकल इंटीग्रेशन चेक है, इसमें न कोई थर्ड‑पार्टी वेबसाइट है, न पेड CAPTCHA की ज़रूरत है।

Mastra एप्लिकेशन में CAPTCHA टूल कहाँ फिट होता है?

CAPTCHA टूल किसी अधिकृत एप्लिकेशन वर्कफ़्लो के ज्ञात चैलेंज स्टेप पर फिट होता है। Mastra यह समन्वय करता है कि एजेंट को कौन से टूल्स दिखाए जाएँ; सॉल्वर एक विशिष्ट ऑपरेशन करता है; आपका ब्राउज़र या एप्लिकेशन कोड उसके रिज़ल्ट का उपयोग करने वाले स्टेप्स के लिए ज़िम्मेदार रहता है।

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

Mastra प्रोजेक्ट फ़्रेमवर्क देता है, और इसका MCP कनेक्शन गाइड यहाँ इस्तेमाल किए गए क्लाइंट इंटरफ़ेस का वर्णन करता है। यह एक डायरेक्ट MCP कनेक्शन है। इसका यह मतलब नहीं है कि हर Mastra प्रोडक्ट या होस्टेड इंटीग्रेशन कैटलॉग में सॉल्वर एक नेटिव प्रोवाइडर है।

एक छोटा लोकल इंटीग्रेशन प्रोजेक्ट तैयार करें

एक लोकल Node.js प्रोजेक्ट और एक Python वातावरण तैयार करें ताकि हर हिस्से की डिपेंडेंसीज़ साफ़‑साफ़ अलग रहें। उदाहरण Node.js 24.16.0, Python 3.12.14, @mastra/mcp 2.4.1, और capsolver-mcp 0.1.3 के साथ चलाया गया था। चुना गया Mastra पैकेज Node.js 22.13.0 या नया चाहता है; टेस्टेड Node.js 24 रनटाइम लेने से पुराने रनटाइम का मिसमैच नहीं आता।

macOS या Linux पर किसी नए प्रोजेक्ट डायरेक्टरी में ये स्टेप चलाएँ:

npm init -y
npm install @mastra/mcp@2.4.1
python3 -m venv py
py/bin/python -m pip install capsolver-mcp==0.1.3

नीचे दी गई .mjs फ़ाइल Node के ES मॉड्यूल सपोर्ट का उपयोग करती है। सर्वर पाथ उस डायरेक्टरी से रिलेटिव रिज़ॉल्व होता है जहाँ से आप स्क्रिप्ट चलाते हैं, इसलिए इसे उसी प्रोजेक्ट रूट से चलाएँ जिसमें py मौजूद हो। अगर आपका Python वातावरण कहीं और है, तो शेल PATH पर पहले मिलने वाले Python पर निर्भर रहने की बजाय पाथ बदल दें।

इस डायरेक्ट टूल चेक के लिए किसी मॉडल क्रेडेंशियल की ज़रूरत नहीं है। मॉडल‑ड्रिवन रिस्पॉन्सेज़ के लिए मॉडल प्रोवाइडर की ऑथेंटिकेशन चाहिए होती है। पेड CAPTCHA ऑपरेशंस के लिए संबंधित सॉल्वर अकाउंट क्रेडेंशियल्स और टास्क पैरामीटर्स ज़रूरी हैं। यह विभाजन आपको इंस्टॉलेशन समस्याएँ पहचानने देता है, इससे पहले कि आप मॉडल व्यवहार, ब्राउज़र स्टेट, या अकाउंट चार्जेज़ शामिल करें।

MCPClient कनेक्ट करें और सपोर्टेड CAPTCHA टाइप्स क्वेरी करें

इंस्टॉल किए गए Python प्रोसेस से MCPClient कनेक्ट करें, टूल्स खोजें और capability क्वेरी चलाएँ। नीचे दिया कोड प्रोजेक्ट डायरेक्टरी में mastra-check.mjs नाम से सेव करें:

import { MCPClient } from '@mastra/mcp';
import { resolve } from 'node:path';

const client = new MCPClient({
  id: 'captcha-setup-check',
  servers: {
    capsolver: {
      command: resolve('py/bin/python'),
      args: ['-m', 'capsolver_mcp'],
      env: { CAPSOLVER_API_KEY: process.env.CAPSOLVER_API_KEY || '' },
    },
  },
});

try {
  const tools = await client.listTools();
  console.log('TOOLS', Object.keys(tools));
  const capabilityTool = tools.capsolver_get_supported_captchas;
  if (!capabilityTool) throw new Error('Capability tool was not discovered');
  const result = await capabilityTool.execute({});
  console.log('CAPABILITIES', JSON.stringify(result, null, 2));
} finally {
  await client.disconnect();
  console.log('DISCONNECTED');
}

यह अडैप्टर आधिकारिक CapSolver MCP लॉन्च इंटरफ़ेस को Mastra के क्लाइंट के साथ जोड़ता है। स्क्रिप्ट इंस्टॉल किए गए पैकेजों के खिलाफ चलाई गई थी, जिसमें capability कॉल और disconnect शामिल हैं। यह न कोई नकली सर्वर रिस्पॉन्स बनाती है, न कोई चैलेंज सबमिट करती है।

इसे उसी प्रोजेक्ट डायरेक्टरी से चलाएँ:

node mastra-check.mjs

टेस्ट की गई लिस्ट में capsolver_solve_captcha, capsolver_detect_captchas, capsolver_solve_on_page, capsolver_get_balance, और capsolver_get_supported_captchas शामिल थे। capability कॉल ने यह structured रिज़ल्ट दिया:

{
  "success": true,
  "registered_handlers": ["recaptcha", "cloudflare"],
  "captcha_types": ["reCaptchaV2", "reCaptchaV3", "cloudflare"]
}

रिज़ल्ट इंस्टॉल किए गए पैकेज के registered handlers और type वैल्यूज़ बताता है। इसका यह मतलब नहीं कि CapSolver वेबसाइट पर लिखे हर प्रोडक्ट को यह पैकेज वर्ज़न उपलब्ध कराता है। क्लाइंट बंद करने के बाद स्क्रिप्ट ने DISCONNECTED भी प्रिंट किया। आपकी रन में इन वैल्यूज़ के आसपास कुछ अतिरिक्त सर्वर डायग्नॉस्टिक लाइन्स भी आ सकती हैं।

एजेंट से टूल अटैच करने से पहले नाम समझें

Mastra, फ़्लैट टूल लिस्ट को कॉन्फ़िगर किए गए सर्वर की के साथ नेमस्पेस करता है। यहाँ capsolver सर्वर की है और get_supported_captchas रिमोट टूल का नाम, जो रिटर्न हुए ऑब्जेक्ट में capsolver_get_supported_captchas बनता है।

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

MCPClient reference डिस्कवरी और कनेक्शन लाइफ़साइकल डॉक्युमेंट करता है। पैकेज वर्ज़न को अपनी setup notes के साथ रखें। इंस्टॉल किए गए वर्ज़न के लिए रेफ़रेंस से मेथड नाम कॉपी करें, बजाय इसके कि किसी पुराने ट्यूटोरियल के कॉल्स को नए क्लाइंट के साथ मिलाएँ।

हर जॉब के लिए टूल का सबसेट चुनें

टूल सबसेट उस काम के आधार पर चुनें जो एजेंट कर सकता है। एक setup assistant को सिर्फ capability क्वेरी की ज़रूरत हो सकती है। जो वर्कफ़्लो पहले से टास्क पैरामीटर्स निकालता है, उसे टोकन‑ओरिएंटेड solving की ज़रूरत हो सकती है। page‑oriented वर्कफ़्लो के ब्राउज़र डिपेंडेंसीज़ और सेशन ज़रूरतें अलग होंगी।

रियल Mastra एजेंट के लिए, relevant डिसकवर्ड एंट्रीज़ से टूल्स ऑब्जेक्ट बनाकर एजेंट की documented tools कॉन्फ़िगरेशन में दें। MCP कनेक्शन उतनी देर तक ज़िंदा रखें जितनी देर एजेंट अपने टूल्स invoke कर सकता है। यह स्टैंडअलोन स्क्रिप्ट तुरंत disconnect कर देती है, क्योंकि इसका काम सिर्फ एक क्वेरी है; यही लाइफ़साइकल किसी लंबे समय चलने वाले एजेंट में ज्यों‑का‑त्यों कॉपी कर देने से कनेक्शन बहुत जल्दी बंद हो जाएगा।

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

अपना CapSolver बोनस कोड रिडीम करें

अपना ऑटोमेशन बजट तुरंत बढ़ाएँ!
CapSolver अकाउंट टॉप‑अप करते समय बोनस कोड CAP26 का उपयोग करें और हर रिचार्ज पर एक्स्ट्रा 5% बोनस पाएँ — बिना किसी लिमिट के।
इसे अभी अपने CapSolver Dashboard में रिडीम करें।

टूल रिज़ल्ट को ब्राउज़र वर्कफ़्लो से जोड़ें

टूल रिज़ल्ट को उस कंपोनेंट से जोड़ें जो अनुमोदित ब्राउज़र टास्क का मालिक है। टोकन‑ओरिएंटेड और page‑oriented रिज़ल्ट्स को अलग‑अलग हैंडलिंग की ज़रूरत होती है, इसलिए एजेंट प्रॉम्प्ट जोड़ने से पहले तय करें कि एप्लिकेशन कौन‑सा इंटरफ़ेस इस्तेमाल करेगा।

अगर आपके कोड को पहले से सपोर्टेड CAPTCHA टाइप और उसके ज़रूरी पैरामीटर्स पता हैं, तो solving टूल वही structured इनपुट ले सकता है। ब्राउज़र कोड, documented इंटीग्रेशन पाथ के ज़रिये रिज़ल्ट apply करने और एप्लिकेशन की अगली स्टेट observe करने के लिए ज़िम्मेदार रहता है। सफल टूल कॉल इन चेक्स की जगह नहीं लेता।

सर्वर के ब्राउज़र‑बेस्ड टूल्स के लिए, उनकी documented डिपेंडेंसीज़ इंस्टॉल करें और देखें कि सेशन कैसे बनता है। लोकल कमांड से लॉन्च की गई सर्विस एक अलग प्रोसेस होती है। यह किसी दूसरे ब्राउज़र के खुले टैब, फ़ॉर्म स्टेट या authenticated सेशन को अपने आप इनहेरिट नहीं करती। जब आपका प्रोग्राम किसी पहले से कंट्रोल किए गए page object के साथ सीधे काम करना चाहता हो, तो core SDK एक अलग सतह है जिसका मूल्यांकन करना चाहिए।

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

जिस स्टेज पर फ़ेलियर हुआ, वहीं उसे हैंडल करें

एजेंट को पूरा वर्कफ़्लो दुबारा चलाने देने से पहले उसी स्टेज का फ़ेलियर हैंडल करें जहाँ वह हुआ था। ज़्यादातर शुरुआती इंटीग्रेशन फ़ेलियर के लिए कुछ व्यावहारिक शुरुआती चेक काफ़ी होते हैं:

एक API कॉल एक लेयर पर सफल हो सकती है जबकि बड़ा यूज़र टास्क अधूरा रह जाए। वही रिज़ल्ट रिपोर्ट करें जो वास्तव में देखा गया। “Tool connection established” सेटअप के दौरान उपयोगी है; “फ़ॉर्म सबमिट हुआ” कहने के लिए किसी देखे गए फ़ॉर्म रिज़ल्ट की ज़रूरत है।

असल चैलेंज ऑपरेशंस के लिए retries सीमित रखें। सिर्फ कॉन्फ़िगरेशन डायग्नोज़ करने के लिए नया पेड टास्क बनाने से बचें। काम करता हुआ capability क्वेरी लोकल कनेक्शन isolate करने का सस्ता तरीका है। जब सर्वर कमांड नहीं मिल पाती, तो official MCP installation guide भी मदद करती है।

उपयोगी डायग्नॉस्टिक संदर्भ बचाएँ

पैकेज वर्ज़न, कॉन्फ़िगर किया हुआ सर्वर की, ऑपरेशन नाम और प्रोसेस सफलतापूर्वक शुरू हुआ या नहीं—इन सबको सुरक्षित रखें। ये डिटेल्स किसी दूसरे डेवलपर को यह फ़ेलियर reproduce करने में मदद करती हैं, बिना अकाउंट key या पूरे ब्राउज़र सेशन दिए। इस उदाहरण में, मिसिंग नेमस्पेस और सर्वर स्टार्टअप फ़ेलियर दोनों शुरू में “मिसिंग टूल” जैसे दिख सकते हैं, पर इनके लिए अलग‑अलग फिक्स चाहिए।

जब कोई टास्क वर्करों के बीच move होता है, तो उसकी एप्लिकेशन रिकॉर्ड को इस डायग्नॉस्टिक क्लाइंट की लाइफ़टाइम से अलग रखें। किसी एजेंट को मिसिंग लोकल ऑब्जेक्ट को ऑटोमैटिकली नए पेड रिक्वेस्ट में बदलने न दें। एप्लिकेशन को तय करना चाहिए कि क्या पिछला ऑपरेशन अभी भी प्रासंगिक है, फिर ही दूसरा प्रयास allow हो।

पहली इंटीग्रेशन को छोटा रखें

पहली इंटीग्रेशन को एक अनुमत वर्कफ़्लो और संकरे टूल सेट तक सीमित रखें। यह उदाहरण साबित करता है कि क्लाइंट असली सर्विस को खोज सकता है, नॉन‑solving capability क्वेरी चला सकता है, structured डेटा प्राप्त कर सकता है और disconnect कर सकता है। यह दावा नहीं करता कि किसी मॉडल ने सही टूल चुना या कि पेड CAPTCHA और ब्राउज़र टास्क पूरा हुआ।

उस आधार से, वह challenge ऑपरेशन जोड़ें जिसकी आपके एप्लिकेशन को ज़रूरत है और उसका acceptance टेस्ट लिखें। CapSolver solver capability देता है; Mastra एप्लिकेशन तय करता है कि यह कब उपयुक्त है और कौन‑सा काम “पूरा” माना जाएगा। उस अलग end‑to‑end टेस्ट से पहले अपने CapSolver dashboard में क्रेडेंशियल्स तैयार करें।

FAQ

प्रश्न: क्या मैं LLM API key के बिना कनेक्शन टेस्ट कर सकता हूँ?

हाँ। उदाहरण Mastra के MCP क्लाइंट के ज़रिये किसी डिसकवर्ड टूल को सीधे कॉल करता है। यह किसी भाषा मॉडल से रिस्पॉन्स बनाने या टूल चुनने को नहीं कहता।

प्रश्न: क्या capability क्वेरी असली CAPTCHA solve है?

नहीं। यह इंस्टॉल्ड सर्विस से registered handler और CAPTCHA टाइप जानकारी लौटाता है। यह न कोई पेड solve वैलिडेट करता है, न किसी ब्राउज़र पेज की स्टेट।

प्रश्न: टूल का नाम capsolver_get_supported_captchas क्यों है?

प्रिफ़िक्स capsolver सर्वर की से आता है। Mastra फ़्लैटेंड लिस्ट में रिमोट टूल नाम से पहले यह नेमस्पेस जोड़ देता है।

प्रश्न: क्या हर डिसकवर्ड टूल मेरे एजेंट को उपलब्ध होना चाहिए?

नहीं। उसके असाइन किए गए काम के लिए ज़रूरी capabilities ही चुनें, फिर सिलेक्शन और execution को अपनी एप्लिकेशन की परमीशन्स और वर्कफ़्लो के खिलाफ टेस्ट करें।

प्रश्न: मुझे disconnect कब कॉल करना चाहिए?

जब क्लाइंट के ज़रिये और कॉल्स की ज़रूरत न हो। एक one‑shot डायग्नॉस्टिक finally में बंद हो सकता है; रनिंग एजेंट को अपने टूल यूज़ के दौरान पूरा कनेक्शन चाहिए।

प्रश्न: क्या इससे साबित हो जाता है कि मेरा प्रोडक्शन ब्राउज़र वर्कफ़्लो काम करेगा?

नहीं। यह लोकल क्लाइंट‑सर्वर इंटीग्रेशन और क्वेरी वेरिफ़ाई करता है। प्रोडक्शन में फिर भी वैध क्रेडेंशियल्स, सपोर्टेड टास्क पैरामीटर्स, उपयुक्त ब्राउज़र स्टेट और end‑to‑end एप्लिकेशन चेक चाहिए होंगे।