הוספת פתרון CAPTCHA לסוכן ה-AI שלכם באמצעות MCP

ההורדה הרשמית של @solvethree/sdk כוללת את קובץ ההפעלה solvethree-mcp. התצורות שלהלן משתמשות ב-npx כדי להריץ אותו מכתובת ה-URL של החבילה שסופקה. אין נקודת קצה מתארחת של MCP שצריך להזין.

• ודאו ש-npx זמין בסביבה שבה פועל מארח ה-MCP שלכם.
• הגדירו את SOLVETHREE_API_KEY למפתח ה-API של סביבת העבודה שלכם בסביבת המארח. אל תכללו אותו בקוד דפדפן או בפרומפטים.
• הגדירו את SOLVETHREE_PROXY באותה סביבה. כלי ה-reCAPTCHA קורא את הפרוקסי היחיד שלו מהמשתנה הזה, ולא מהבקשה לכלי.

במארח שמקבל תצורת MCP ב-JSON, הוסיפו את רשומת השרת הזו:

{
  "mcpServers": {
    "solvethree": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz",
        "solvethree-mcp"
      ]
    }
  }
}

עבור Codex, השתמשו במקום זאת בתצורת TOML הזו. הרשומה env_vars שלה מעבירה את שני המשתנים מסביבת המארח; היא אינה מגדירה את הערכים שלהם.

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

הפעילו או טענו מחדש את המארח כשהמשתנים האלה זמינים בסביבה. בדקו שהוא חושף את solvethree_capabilities,‏ solvethree_create_recaptcha,‏ solvethree_create_kasada,‏ solvethree_create_tmpt ו-solvethree_get_task.

לפני יצירת משימת reCAPTCHA, הגדירו את פרופיל אתר היעד וודאו שהוא פעיל עבור סביבת העבודה שלכם. שליחת שם מארח ופעולה דרך MCP אינה יוצרת את הפרופיל הזה.

השתמשו ב-solvethree_capabilities כדי לבדוק את היכולות הזמינות. עבור reCAPTCHA v3 Enterprise, קראו ל-solvethree_create_recaptcha עם הבקשה הבאה:

{
  "site": "accounts.example.com",
  "action": "login",
  "requestId": "agent-login-001",
  "waitMs": 0
}

החליפו את accounts.example.com באתר היעד שלכם ואת login בפעולה שהאפליקציה שלכם צריכה. בחרו requestId למשימה הלוגית הזו ושמרו אותו יחד עם הבקשה. כאשר waitMs מוגדר לאפס, אחזרו את התוצאה בנפרד במקום להמתין להשלמה בקריאה הזו.

כל קריאת יצירה דרך MCP מחייבת requestId, אף שהשדה הזה הוא אופציונלי ב-API המשימות שבבסיסו. השתמשו ב-1–64 תווי ASCII: אותיות, ספרות, קווים תחתונים או מקפים.

1. 1.

   שמרו את מזהה המשימה שהוחזר

   יצירת המשימה אינה התוצאה. שמרו את מזהה המשימה כדי שהסוכן יוכל לאחזר את אותה משימה.

2. 2.

   קראו ל-solvethree_get_task

   השתמשו במזהה המשימה שהוחזר מקריאת היצירה. אם המצב הוא pending או solving, אחזרו שוב את המשימה מאוחר יותר. אף אחד מהמצבים האלה אינו מכיל פתרון שמיש.

3. 3.

   טיפול במצב הסופי

   במצב ready, העבירו את הפתרון לאינטגרציה שלכם עם הדפדפן או האפליקציה. במצב failed, בדקו את errorCode ואת error והפסיקו לתשאל את המשימה הזו.

עבור reCAPTCHA, שלחו את solution.token דרך הדפדפן או בקשת האפליקציה שלכם. הגדירו את הכותרות User-Agent ו-sec-ch-ua שלה לפי userAgent ו-secChUa שהוחזרו, והשתמשו שוב בפרוקסי שהוגדר ב-SOLVETHREE_PROXY. אם הספק שלכם מחליף נקודות יציאה, הקפידו להצמיד את החיבור לאותה הפעלת פרוקסי.

Kasada מחזירה כותרות ו-Ticketmaster TMPT מחזירה ערך גולמי של קובץ Cookie. השתמשו בפלט המתאים למשימה שביקשתם; אי אפשר להשתמש בתוצאות האלה זו במקום זו.

שרת ה-MCP אינו מפעיל דפדפן ואינו ממלא טפסים. המארח שלו מקבל נתוני פתרון פרטיים, והיישום שלכם מבצע את השליחה. בדקו בנפרד את תגובת היעד: ready פירושו ש-solvethree יצרה פתרון, ולא שהיעד קיבל אותו.

חריגה מזמן ההמתנה לחיבור אינה מוכיחה שיצירת המשימה נכשלה. אם קיבלתם מזהה משימה, אחזרו אותה. אחרת, חזרו על אותה בקשת יצירה עם אותו requestId ועם אותם נתוני קלט למשימה כדי לשחזר את המשימה הקיימת. אל תיצרו מזהה חדש רק משום שהתגובה אבדה.

שימוש חוזר במזהה בקשה עם נתוני קלט שונים למשימה יוצר התנגשות. אם המשימה עצמה נכשלה, קראו את השגיאה שלה לפני שתחליטו מה לשנות; שליחה חוזרת ועיוורת של נתוני קלט לא תקינים לא תתקן אותם. להבחנה בין שגיאות בקשה לכשלי משימה, ראו שגיאות CAPTCHA API.