Hugging Face smolagents + Scrapeless MCP: पाइथन में एक AI वेब स्क्रेपर बनाएं

संक्षेप में:

• एक हगिंग फेस एजेंट एक MCP पूर्व बिंदु से 21 लाइव वेब टूल प्राप्त करता है। ToolCollection.from_mcp को https://api.scrapeless.com/mcp पर इंगित करने से एक स्मोलएजेंट्स CodeAgent को ब्राउज़र नियंत्रण, पृष्ठ स्क्रैपिंग, और Google खोज और प्रवृत्तियों की सुविधा मिलती है, जबकि रेंडरिंग, प्रॉक्सी राउटिंग, और एंटी-डिटेक्शन सर्वर-साइड रहते हैं।
• होस्टेड पथ पूरी तरह से पाइथन है। एक x-api-token हेडर के साथ स्ट्रीम करने योग्य HTTP किसी भी स्थानीय सर्वर प्रक्रिया को प्रतिस्थापित करता है — नोड.जेएस नहीं, केवल एक pip install "smolagents[mcp]"।
• उपकरण क्षेत्र एक मॉडल से पहले काम करता है। केवल scrape_markdown कॉल करने पर एक साफ मार्कडाउन के रूप में एक लाइव पृष्ठ लौटता है — इस मार्गदर्शिका में डेमो पृष्ठ के लिए 4,249 वर्ण — इसलिए आप केवल एक Scrapeless API कुंजी के साथ वायरिंग का परीक्षण कर सकते हैं।
• एक AI स्क्रेपर अर्थ के अनुसार निकालता है, चयनकर्ता द्वारा नहीं। एजेंट मार्कडाउन पढ़ता है और उन क्षेत्रों को लौटाता है जिनकी आप मांग करते हैं, इसलिए एक साइट का डिज़ाइन जो CSS-चयनकर्ता स्क्रिप्ट को तोड़ देगा, आमतौर पर आपको कुछ नहीं देता।
• एक अतिरिक्त पूर्वापेक्षा एक मॉडल कुंजी है। उपकरण सूची, प्रत्यक्ष उपकरण कॉल, और एजेंट निर्माण सभी इसके बिना चलते हैं; केवल तर्क राउंड-ट्रिप को एक हगिंग फेस टोकन या किसी अन्य समर्थित प्रदाता की आवश्यकता होती है।
• शुरू करने के लिए स्वतंत्र। app.scrapeless.com पर मुफ्त योजना में अपनी API कुंजी बनाएं।

यह एकीकरण क्या सक्षम करता है

चयनकर्ता-आधारित स्क्रेपर एक शर्त है कि लक्षित पृष्ठ कभी नहीं बदलता है, और वह शर्त अक्सर हार जाती है। एक AI स्क्रेपर एक अलग स्थिति लेता है: पृष्ठ को साफ़ पाठ के रूप में लाएँ, एक भाषा मॉडल को आवश्यक क्षेत्र निकालने दें, और इस सप्ताह कीमत किस div में है, उसकी परवाह करना बंद करें।

smolagents हगिंग फेस का छोटा एजेंट पुस्तकालय है — इसके एजेंट उपकरणों को कॉल करने के लिए पाइथन लिखते हैं बजाय JSON उपकरण कॉल के। इसके पास अपनी ओर से लाइव वेब तक पहुंचने का कोई तरीका नहीं है। यह मॉडल संदर्भ प्रोटोकॉल का कार्य है: मॉडल संदर्भ प्रोटोकॉल विनिर्देशन परिभाषित करता है कि सर्वर कैसे उन टाइप किए गए उपकरणों का विज्ञापन करता है जिन्हें कोई भी क्लाइंट सूचीबद्ध और उपयोग कर सकता है। यदि प्रोटोकॉल आपके लिए नया है, तो MCP क्या है और यह कैसे काम करता है पर प्राइमर संपूर्ण अवधारणा को कवर करता है।

दोनों को एक साथ जोड़ दें और आपको कुछ दर्जन लाइनों के पाइथन में एक प्रोग्रामेटिक AI स्क्रेपर मिल जाता है: स्मोलएजेंट्स तर्क चक्र की आपूर्ति करता है, Scrapeless MCP सर्वर फेचिंग, रेंडरिंग, और खोज को कॉल करने योग्य उपकरणों के रूप में प्रदान करता है। यह गाइड उस स्क्रेपर का निर्माण चरण-दर-चरण करती है और दिखाती है कि कौन से भाग केवल एक Scrapeless कुंजी के साथ चलते हैं।

क्यों Scrapeless MCP

Scrapeless MCP सर्वर 21 टाइप किए गए उपकरणों के रूप में स्क्रैपिंग बुनियादी ढांचे का खुलासा करता है, और भारी कार्य सर्वर पर किया जाता है, आपके प्रोसेस में नहीं। scrape_html, scrape_markdown, और scrape_screenshot विभिन्न आकारों में एकल पृष्ठ कैप्चर करते हैं। सोलह browser_* उपकरण स्क्रैपिंग ब्राउज़र पर क्लाउड ब्राउज़र सत्र चलाते हैं — स्वयं विकसित क्रोमियम द्वारा संचालित एक एंटी-डिटेक्शन क्लाउड ब्राउज़र — उन कार्यों के लिए जहां एजेंट को क्लिक, टाइप और स्क्रॉल करना आवश्यक है। google_search और google_trends खोज को कवर करते हैं।

इस निर्माण के लिए तीन विशेषताएँ महत्वपूर्ण हैं:

• एक कुंजी, होस्टेड परिवहन। वही Scrapeless API कुंजी जो बाकी प्लेटफॉर्म को चलाती है, MCP पूर्व बिंदु को प्रमाणित करती है। आपका पाइथन प्रोसेस कभी भी एक ब्राउज़र या नोड सर्वर लॉन्च नहीं करता।
• मॉडल-मुक्त परीक्षण क्षमता। उपकरण सूचीबद्ध और निष्पादित होते हैं बिना किसी LLM के चक्र में, इसलिए एकीकरण को परत दर परत सिद्ध किया जा सकता है न कि एक एजेंट की तर्क के माध्यम से डिबग किया जा सके।
• मार्कडाउन-प्रथम निष्कर्षण मार्ग। एक पृष्ठ की मार्कडाउन कैप्चर इसके कच्चे HTML के आकार का एक अंश है, जिसका अर्थ है प्रति निष्कर्षण कम टोकन और मॉडल को पढ़ने के लिए कम शोर। scrape_markdown ठीक यही लौटाता है।

यहां तक कि यही पूर्व बिंदु LangChain के साथ भी लगेगा यदि वह आपकी स्टैक है — LangChain + Scrapeless MCP गाइड एडेप्टर पक्ष से समान सतह को पार करती है।

पूर्वापेक्षाएँ

• पाइथन 3.10 या नया — इस गाइड में चलने वाली प्रक्रियाएँ पाइथन 3.12 का उपयोग करती हैं।
• डैशबोर्ड से एक Scrapeless API कुंजी — डेवलपर डॉक्स कुंजी निर्माण और पूर्व बिंदु संदर्भ को कवर करती हैं।
• केवल अंतिम एजेंट राउंड-ट्रिप के लिए: एक Hugging Face टोकन (या किसी भी मॉडल प्रदाता के लिए क्रेडेंशियल जो smolagents का समर्थन करता है)। इससे पहले का हर कदम बिना इसके चलता है।

स्थापित और कॉन्फ़िगर करें

एक पैकेज जिसमें एक अतिरिक्त एजेंट पुस्तकालय और MCP क्लाइंट प्लंबिंग लाता है। ये संस्करण उस गाइड के खिलाफ लिखे गए हैं — smolagents 1.26.0, mcp 1.27.1, mcpadapt 0.1.20:

pip install "smolagents[mcp]==1.26.0"

अपने कुंजी का निर्यात करें ताकि स्क्रिप्ट इसे स्रोत कोड के बजाय वातावरण से पढ़ सकें:

export SCRAPELESS_API_KEY="sk_your_key_here"

स्ट्रीम करने योग्य HTTP के माध्यम से कनेक्ट करें और उपकरणों को सूचीबद्ध करें

कनेक्शन एक शब्दकोष है, न कि एक कॉन्फ़िगरेशन फ़ाइल। ToolCollection.from_mcp उसी पैरामीटर को स्वीकार करता है जैसे कि अंतर्निहित स्ट्रीम करने योग्य HTTP क्लाइंट, इसलिए एंडपॉइंट URL, परिवहन नाम, और प्राधिकरण हेडर एक व्यक्तिगत में चलते हैं:

# connect_and_list.py — Scrapeless MCP सर्वर के साथ हैंडशेक करें, उपकरणों की सूची बनाएं
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    names = sorted(tool.name for tool in tc.tools)
    print(f"उपकरणों की संख्या: {len(names)}")
    print("\n".join(names))

संदर्भ प्रबंधक कनेक्शन जीवनचक्र का स्वामी है: यह प्रवेश पर MCP हैंडशेक करता है और निकासी पर साफ-सुथरा डिस्कनेक्ट करता है। एक पैरामीटर के लिए एक शब्द आवश्यक है: MCP उपकरणों का विनिर्देश एक सर्वर को परिणाम सीधे पाठ या संरचित सामग्री के रूप में लौटाने की अनुमति देता है, और Scrapeless उपकरण पाठ लौटाते हैं — इसलिए structured_output=False को स्पष्ट रूप से पास करें। smolagents 1.26 चेतावनी देता है जब पैरामीटर छोड़ दिया जाता है, क्योंकि इसका डिफ़ॉल्ट भविष्य के रिलीज में बदलने के लिए निर्धारित है।

एक सही हैंडशेक उपकरणों की संख्या: 21 मुद्रित करता है इसके बाद नाम: सोलह browser_* उपकरण, google_search, google_trends, scrape_html, scrape_markdown, और scrape_screenshot।

एक stdio मार्ग भी मौजूद है, उन ग्राहकों के लिए जो एक स्थानीय सर्वर प्रक्रिया लॉन्च करना पसंद करते हैं — अलग जीवनचक्र के पीछे वही 21 उपकरण:

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": { "SCRAPELESS_KEY": "sk_your_key_here" }
    }
  }
}

केवल Python निर्माण के लिए, स्ट्रीम करने योग्य HTTP छोटा रास्ता है: pip के अलावा कुछ भी स्थापित करने की आवश्यकता नहीं है, और कुछ भी चलाना नहीं है।

मुफ्त योजना पर अपना API कुंजी प्राप्त करें: app.scrapeless.com

किसी भी मॉडल के शामिल होने से पहले scrape_markdown कॉल करें

संग्रह में हर उपकरण एक कॉल करने योग्य smolagents Tool ऑब्जेक्ट है, इसलिए स्क्रैपिंग परत को सीधे व्यायाम के रूप में संचालित किया जा सकता है — कोई एजेंट या मॉडल कुंजी शामिल नहीं है:

# call_tool.py — एक MCP उपकरण को सरल फ़ंक्शन कॉल के रूप में निष्पादित करें
import json
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    tools = {tool.name: tool for tool in tc.tools}
    raw = str(tools["scrape_markdown"](url="https://quotes.toscrape.com/"))
    # होस्टेड उपकरण "Response:" पंक्ति के बाद JSON-संकेतित स्ट्रिंग के रूप में पृष्ठ लौटाता है — इसे डिकोड करें ताकि आपको खुद Markdown मिल सके।
    body = raw.split("\n\n", 1)[1] if raw.startswith("Response:") else raw
    text = json.loads(body) if body.startswith('"') else body
    print(f"scrape_markdown ने {len(text):,} वर्णों के markdown लौटाए")
    print(text[:160])

उद्धरण डेमो साइट के खिलाफ यह 4,249 वर्णों के markdown को लौटाता है, जो पृष्ठ के शीर्षक और पहले उद्धरण के साथ शुरू होता है — पठनीय पाठ जिसमें पहले से ही पृष्ठ क्रोम हटा दिया गया है। यह एकल कॉल स्क्रैपर की पूरी प्राप्ति परत है। इसके बाद सब कुछ व्याख्या है।

उपकरणों को CodeAgent से संलग्न करें

संग्रह को एजेंट से बाइंड करना एक कन्स्ट्रक्टर है, और यह किसी भी मॉडल कॉल होने से पहले काम करता है। एजेंट वस्तु प्रत्येक MCP उपकरण को नाम द्वारा उसके अंतर्निहित final_answer के बगल में अनुक्रमित करती है:

# attach_agent.py — MCP उपकरण सतह को smolagents CodeAgent को सौंपें
import os

from smolagents import CodeAgent, InferenceClientModel, ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    model = InferenceClientModel(model_id="Qwen/Qwen2.5-72B-Instruct")
    agent = CodeAgent(tools=[*tc.tools], model=model, add_base_tools=False)
    print(sorted(agent.tools.keys()))

add_base_tools=False टूलबॉक्स को MCP टूल्स और एजेंट के इन-बिल्ट final_answer तक सीमित रखता है। एक स्क्रैपर जो केवल पेजों को लाने के लिए होना चाहिए, आप इसे और संकुचित कर सकते हैं - केवल उस टूल को पास करें जो आप चाहते हैं, जैसे कि tools=[t for t in tc.tools if t.name == "scrape_markdown"] - और मॉडल शारीरिक रूप से ब्राउज़र सत्रों या खोज कॉल्स में नहीं जा सकता जो उसे आवश्यक नहीं हैं। एक छोटा टूलबॉक्स भी एक छोटा सिस्टम प्रॉम्प्ट और मॉडल से कम गलत मोड़ का मतलब है।

प्रॉम्प्ट-चालित उपयोग: एआई स्क्रैपर रन

एक्सट्रैक्शन स्टेप एक प्रॉम्प्ट है, न कि एक पार्सर। आप एजेंट को बताते हैं कि कौन सा पेज पढ़ना है और कौन से फ़ील्ड लौटाना है, और एजेंट scrape_markdown को कॉल करने का निर्णय लेता है, परिणाम पढ़ता है, और उत्तर को संकलित करता है - smolagents प्रत्येक टूल को मॉडल के साथ Typed इनपुट के साथ विवरणित करता है, वही संरचना JSON स्कीमा स्पेसिफिकेशन मशीन-पढ़ने योग्य फ़ील्ड सीमाओं के लिए परिभाषित करती है।

नोट: यह अंतिम कदम इस मार्गदर्शिका में एकमात्र पूर्वापेक्षा है - एजेंट राउंड-ट्रिप को एक मॉडल प्रोवाइडर की आवश्यकता होती है। इसे चलाने से पहले HF_TOKEN को हगिंग फेस टोकन (या किसी अन्य प्रोवाइडर को कॉन्फ़िगर करें जो smolagents द्वारा समर्थित है) सेट करें। ऊपर दिए गए प्रत्येक ब्लॉक केवल Scrapeless कुंजी के साथ चलता है।

# run_scraper.py — मॉडल राउंड-ट्रिप (HF_TOKEN या किसी अन्य प्रोवाइडर की आवश्यकता होती है)
result = agent.run(
    "Call scrape_markdown on https://quotes.toscrape.com/ and return a JSON array "
    "of the quotes on the page. Each item must have exactly these keys: "
    "text (string), author (string), tags (array of strings). "
    "Return only the JSON array, no commentary."
)
print(result)

प्रॉम्प्ट का आकार आउटपुट आकार को नियंत्रित करता है। सटीक कुंजियों और प्रकारों का नामकरण करना, "केवल JSON अर्रे" की मांग करना, और एक रन में एक पृष्ठ रखना आपको ऐसा आउटपुट देता है जिसे आप json.loads कर सकते हैं और डाउनस्ट्रीम में मान्य कर सकते हैं। जब कोई फ़ील्ड पेज पर गायब होती है, तो एजेंट को null का उपयोग करने के लिए निर्देशित करें बजाय इसके कि वह एक मान आविष्कार करे - मॉडल आत्मविश्वासी ढंग से गैप भरते हैं जब तक कि उन्हें ऐसा करने के लिए नहीं कहा जाता।

आपको क्या मिलता है

फेच लेयर से, आपको स्ट्रिंग के रूप में मार्कडाउन प्राप्त होता है: पृष्ठ शीर्षक एक शीर्षक के रूप में, लिंक टेक्स्ट को ब्रैकेट में बरकरार रखा गया है, और बॉडी टेक्स्ट पढ़ने के क्रम में है। उद्धरण साइट से 4,249-कारक कैप्चर इस प्रकार शुरू होता है:

# [उद्धरण स्क्रैप करने के लिए](https://quotes.toscrape.com/)

[लॉगिन](https://quotes.toscrape.com/login)

“जगह जिस तरह से हमने इसे बनाया है, वह हमारे सोचने की एक प्रक्रिया है।

एजेंट रन से, आपको जो भी अनुबंध आपका प्रॉम्प्ट लागू करता है, वह मिलता है - यहाँ, {text, author, tags} वस्तुओं का एक JSON एरे, पृष्ठ पर हर उद्धरण के लिए एक। इस व्यवस्था का मूल्य उस दिन सामने आता है जब लक्षित साइट अपनी वर्ग नामों को बदलती है: मार्कडाउन अभी भी उद्धरण शामिल करता है, प्रॉम्प्ट अभी भी फ़ील्डों का नाम देता है, और स्क्रैपर अभी भी वही स्कीमा लौटाता है जबकि एक चयनकर्ता-आधारित स्क्रिप्ट कुछ भी नहीं लौटाती है।

निष्कर्ष

एकीकरण तीन छोटे कदम हैं: ToolCollection.from_mcp को होस्टेड एंडपॉइंट पर इंगित करें, सीधे scrape_markdown कॉल के साथ फेच लेयर को साबित करें, फिर टूल को CodeAgent से बाइंड करें और प्रॉम्प्ट को एक्सट्रैक्शन करने दें। प्रत्येक परत अपने आप में परीक्षण योग्य है, केवल अंतिम एक को एक मॉडल कुंजी की आवश्यकता होती है, और वह हिस्सा जो एक क्लासिक स्क्रैपर में सबसे अधिक टूटने की संभावना होती है - पार्सिंग - वही हिस्सा है जिसे मॉडल अवशोषित करता है।

क्या आप अपने एजेंट को एक असली वेब सतह देने के लिए तैयार हैं?

MCP एंडपॉइंट Scrapeless प्लेटफॉर्म के बाकी हिस्सों के साथ समान API कुंजी से प्रमाणित होता है - योजनाएँ और शामिल मात्रा प्राइसिंग पृष्ठ पर हैं। app.scrapeless.com पर मुफ्त योजना पर एक कुंजी बनाएं और ऊपर दिए गए हैंडशेक स्क्रिप्ट आपकी 21 टूल को एक मिनट के अंदर प्रिंट करेगी।

सामान्य प्रश्न

प्रश्न: एआई स्क्रैपर क्या है?

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

प्रश्न: क्या मुझे Scrapeless टूल्स को कॉल करने के लिए हगिंग फेस टोकन की आवश्यकता है?

नहीं। टूल्स को सूचीबद्ध करना, scrape_markdown को सीधे कॉल करना, और CodeAgent का निर्माण केवल Scrapeless API कुंजी के साथ प्रमाणित होता है। हगिंग फेस टोकन (या किसी अन्य प्रोवाइडर की कुंजी) के लिए केवल एक चीज की आवश्यकता होती है: agent.run() तर्क राउंड-ट्रिप।

प्रश्न: क्या मुझे स्ट्रीम करने योग्य HTTP या stdio के माध्यम से कनेक्ट करना चाहिए?

पाइथन परियोजनाओं के लिए स्ट्रीम करने योग्य HTTP का उपयोग करें: इसे किसी स्थानीय प्रक्रिया की आवश्यकता नहीं होती है और यह हेडर के साथ प्रमाणित होता है। stdio परिवहन (npx -y scrapeless-mcp-server, SCRAPELESS_KEY पर्यावरण चर के माध्यम से प्रमाणित) डेस्कटॉप MCP क्लाइंट के लिए उपयुक्त है जो स्वयं सर्वर प्रक्रियाओं का प्रबंध करते हैं। दोनों परिवहन समान टूल सतह को उजागर करते हैं।
प्रश्न: क्या एजेंट सभी 21 टूल्स के बजाय सिर्फ एक टूल का इस्तेमाल कर सकता है?

हाँ। एजेंट बनाने से पहले संग्रह को फ़िल्टर करें — tools=[t for t in tc.tools if t.name == "scrape_markdown"] — और मॉडल केवल वही टूल देखता है। एकल-उद्देश्य वाले स्क्रैपर के लिए यह अनुशंसित आकार है: सिस्टम प्रम्प्ट छोटा हो जाता है और मॉडल कभी भी ब्राउज़र सत्र शुरू नहीं कर सकता जो आप कभी भी नहीं चाहते थे।

प्रश्न: जावास्क्रिप्ट-भारी पृष्ठों या एंटी-बॉट चुनौतियों के पीछे के पृष्ठों के बारे में क्या?

रेंडरिंग सर्वर-साइड पर होती है, इसलिए आपका पायथन कोड नहीं बदलता। scrape_html और scrape_markdown वे पृष्ठ संभालते हैं जिन्हें जावास्क्रिप्ट निष्पादन की आवश्यकता होती है, और browser_* टूल्स उन फ़्लो के लिए पूर्ण क्लाउड ब्राउज़र सत्र चलाते हैं जिन्हें क्लिक करने या टाइप करने की आवश्यकता होती है। प्रॉक्सी राउटिंग और एंटी-डिटेक्शन प्रबंधित सेवा का हिस्सा हैं न कि ऐसा कुछ जिसे एजेंट को समझना होगा।

प्रश्न: स्मॉलएजेंट्स के साथ कौन से मॉडल काम करते हैं?

कोई भी प्रदाता जिसका पुस्तकालय समर्थन करता है। InferenceClientModel उन मॉडलों को कवर करता है जो हगिंग फेस इनफरेंस प्रदाताओं के माध्यम से सेवा में हैं, और पुस्तकालय OpenAIModel, AzureOpenAIModel, AmazonBedrockModel, LiteLLMModel, और स्थानीय बैकएंड जैसे TransformersModel भी प्रदान करता है — वर्तमान सूची के लिए स्मॉलएजेंट्स मॉडल संदर्भ देखें। MCP पक्ष मॉडल-निर्क्रिय है: टूल किसी भी मॉडल के ऊपर एक समान दिखते हैं।

प्रश्न: क्या आईए एजेंट के साथ स्क्रैप करना कानूनी है?

वही नियम किसी भी स्क्रैपर के लिए लागू होते हैं: केवल सार्वजनिक पृष्ठों को इकट्ठा करें, लक्षित साइट की शर्तों और रोबोट निर्देशों का सम्मान करें, मात्रा सीमित रखें, और किसी भी व्यक्तिगत डेटा को उन गोपनीयता कानूनों के तहत संभालें जो आपके लिए लागू होते हैं। एक एजेंट निकासी करने के तरीके को बदलता है, यह नहीं कि आपको क्या इकट्ठा करने की अनुमति है — जब संदेह में हों, तो कार्यभार का विस्तार करने से पहले सलाह पूछें।