Integrasi Mastra CAPTCHA Solver: Panduan MCP Praktis

Ringkasan

• MCPClient milik Mastra dapat menjalankan proses solver CAPTCHA lokal dan menemukan tool-nya melalui stdio.
• listTools() mengembalikan tool bernamespace, seperti capsolver_get_supported_captchas untuk server key contoh.
• Jalankan kueri kapabilitas tepat sebelum melibatkan model bahasa atau mengirim tugas CAPTCHA berbayar.
• Pilih tool yang dibutuhkan agen Anda alih-alih otomatis melampirkan semua kapabilitas yang ditemukan.
• Tutup klien MCP ketika pemeriksaan mandiri selesai, dan bedakan hasil solver dari penyelesaian alur kerja browser.

Integrasi solver CAPTCHA Mastra memberi aplikasi TypeScript batasan tool yang jelas untuk titik verifikasi. Alur kerja browser mungkin sudah tahu apa yang harus dilakukan sebelum dan sesudah challenge, sementara agen membutuhkan cara yang didukung untuk meminta operasi challenge. MCP menghubungkan kapabilitas tersebut tanpa memerlukan wrapper lain di atas API dasar solver.

CapSolver menyediakan server lokal pada contoh ini. Panduan ini menggunakan klien Mastra nyata untuk menemukan tool-nya dan menjalankan kueri tipe yang didukung. Lalu menjelaskan cara melampirkan subset yang sesuai ke agen dan menjaga perbedaan antara respons tool dan tugas web yang sudah selesai. Contoh ini adalah pemeriksaan integrasi lokal, tanpa situs pihak ketiga atau CAPTCHA berbayar.

Di mana tool CAPTCHA ditempatkan dalam aplikasi Mastra?

Tool CAPTCHA ditempatkan pada langkah challenge yang sudah diketahui dalam alur kerja aplikasi yang terotorisasi. Mastra mengoordinasikan tool yang diekspos ke agen; solver menjalankan operasi spesifik; kode browser atau aplikasi Anda yang menguasai langkah-langkah yang menggunakan hasilnya.

Pertimbangkan layanan QA yang menjalankan uji form yang dikendalikan pemilik. Tes sudah menyiapkan datanya dan mencapai challenge yang didukung. Operasi solver dapat memberikan jawaban yang relevan, tetapi tes tetap harus mengirim form dengan benar dan memeriksa konfirmasi yang diharapkan. Agen tidak boleh melaporkan keberhasilan hanya karena menerima respons tool yang tidak kosong.

Proyek Mastra menyediakan framework, sementara panduan koneksi MCP-nya menjelaskan antarmuka klien yang digunakan di sini. Ini adalah koneksi MCP langsung. Ini tidak menyiratkan bahwa solver adalah penyedia native di setiap produk Mastra atau katalog integrasi hosted.

Siapkan proyek integrasi lokal kecil

Siapkan proyek Node.js lokal dan environment Python sehingga setiap bagian memiliki set dependensi eksplisit. Contoh ini dieksekusi dengan Node.js 24.16.0, Python 3.12.14, @mastra/mcp 2.4.1, dan capsolver-mcp 0.1.3. Paket Mastra yang dipilih memerlukan Node.js 22.13.0 atau lebih baru; menggunakan runtime Node.js 24 yang sudah diuji menghindari ketidakcocokan dengan runtime lama.

Jalankan langkah berikut di direktori proyek baru di macOS atau 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

Berkas .mjs di bawah ini menggunakan dukungan modul ES Node. Path server di-resolve relatif terhadap direktori tempat Anda menjalankan script, jadi eksekusikan dari root proyek yang berisi py. Jika environment Python Anda berada di tempat lain, ubah path tersebut, jangan bergantung pada Python mana pun yang kebetulan pertama di PATH shell.

Tidak diperlukan kredensial model untuk pemeriksaan tool langsung ini. Respons yang digerakkan model memerlukan autentikasi penyedia model. Operasi CAPTCHA berbayar memerlukan kredensial akun solver yang sesuai dan parameter tugas. Pemisahan ini memungkinkan Anda mendiagnosis masalah instalasi sebelum melibatkan perilaku model, state browser, atau biaya akun.

Hubungkan MCPClient dan kueri tipe CAPTCHA yang didukung

Hubungkan MCPClient ke proses Python yang terinstal, temukan tool-nya, dan jalankan kueri kapabilitas. Simpan berikut ini sebagai mastra-check.mjs di direktori proyek:

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');
}

Adapter ini menggabungkan antarmuka peluncuran MCP resmi CapSolver dengan klien Mastra. Script dijalankan terhadap paket yang terinstal, termasuk pemanggilan kapabilitas dan disconnect. Script ini tidak membangun respons server palsu atau mengirim challenge.

Jalankan dari direktori proyek yang sama:

node mastra-check.mjs

Daftar yang diuji berisi capsolver_solve_captcha, capsolver_detect_captchas, capsolver_solve_on_page, capsolver_get_balance, dan capsolver_get_supported_captchas. Pemanggilan kapabilitas mengembalikan hasil terstruktur berikut:

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

Hasil ini menjelaskan handler terdaftar paket yang terinstal dan nilai tipe. Ini tidak berarti setiap produk yang tercantum di situs CapSolver tersedia melalui versi paket ini. Script juga mencetak DISCONNECTED setelah menutup klien. Eksekusi Anda mungkin menyertakan baris diagnostik server tambahan di sekitar nilai-nilai ini.

Pahami nama sebelum melampirkan tool ke agen

Mastra memberi namespace pada daftar tool yang dipipihkan dengan server key yang dikonfigurasi. Di sini, capsolver adalah server key dan get_supported_captchas adalah nama tool remote, sehingga menghasilkan capsolver_get_supported_captchas dalam objek yang dikembalikan.

Gunakan key yang dikembalikan alih-alih menebaknya dari label tampilan. Mengganti nama entri server mengubah key yang diharapkan kode Anda. Saat memindahkan konfigurasi yang sudah bekerja ke aplikasi yang lebih besar, periksa lagi tool yang ditemukan sebelum menggunakan ulang lookup atau instruksi agen yang menyebutkannya.

Referensi MCPClient mendokumentasikan discovery dan lifecycle koneksi. Simpan versi paket bersama catatan setup Anda. Salin nama metode dari referensi untuk versi yang Anda instal alih-alih menggabungkan klien terbaru dengan pemanggilan dari tutorial lama.

Pilih subset tool untuk setiap pekerjaan

Pilih subset tool berdasarkan pekerjaan yang boleh dilakukan agen. Asisten setup mungkin hanya membutuhkan kueri kapabilitas. Alur kerja yang sudah mengekstrak parameter tugas mungkin membutuhkan solving berbasis token. Alur kerja berbasis halaman memiliki dependensi browser dan kebutuhan sesi yang berbeda.

Untuk agen Mastra yang nyata, bangun objek tools dari entri relevan yang ditemukan dan berikan melalui konfigurasi tools agen yang didokumentasikan. Biarkan koneksi MCP tetap hidup selama agen dapat memanggil tool-nya. Script mandiri ini langsung disconnect karena tugasnya hanya satu kueri; menyalin lifecycle itu mentah-mentah ke agen jangka panjang akan menutup koneksi terlalu cepat.

Kueri langsung membuat transport dan data terlihat tanpa meminta model memilih tool. Setelah lolos, uji pemilihan agen secara terpisah dengan kredensial model normal dan aturan izin aplikasi Anda. Kueri langsung yang berhasil seharusnya membantu mengisolasi tes berikutnya, bukan menggantikannya.

Tukarkan Kode Bonus CapSolver Anda

Tingkatkan anggaran automasi Anda seketika!
Gunakan kode bonus CAP26 saat mengisi ulang akun CapSolver Anda untuk mendapatkan bonus 5% tambahan pada setiap pengisian — tanpa batas.
Tukarkan sekarang di Dashboard CapSolver

Hubungkan hasil tool ke alur kerja browser

Hubungkan hasil tool ke komponen yang memiliki tugas browser yang disetujui. Hasil berbasis token dan berbasis halaman membutuhkan penanganan yang berbeda, jadi tentukan antarmuka mana yang akan digunakan aplikasi sebelum menambahkan prompt agen di sekitarnya.

Jika kode Anda sudah mengetahui tipe CAPTCHA yang didukung dan parameter yang dibutuhkan, tool solving dapat menerima input terstruktur tersebut. Kode browser tetap bertanggung jawab menerapkan hasil melalui jalur integrasi yang didokumentasikan dan mengamati state aplikasi berikutnya. Pemanggilan tool yang sukses tidak menggantikan pemeriksaan itu.

Untuk tool server yang berbasis browser, instal dependensi yang didokumentasikan dan konfirmasikan cara sesi dibuat. Layanan yang dijalankan melalui perintah lokal adalah proses terpisah. Layanan ini tidak otomatis mewarisi tab terbuka, state form, atau sesi autentikasi browser lain. Core SDK adalah permukaan berbeda yang perlu dievaluasi saat program Anda harus bekerja langsung dengan objek halaman yang sudah dikendalikan.

Rekaman QA dapat menangkap tahap yang dicapai, tool yang dipilih, hasil tool, dan asersi akhir aplikasi. Field ini menjawab pertanyaan yang berbeda. Kegagalan koneksi menyangkut integrasi; error tugas menyangkut permintaan ke solver; ketiadaan state konfirmasi menyangkut alur kerja aplikasi. Jaga perbedaan itu dalam log dan pesan status ke pengguna.

Tangani kegagalan di tahap yang menyebabkannya

Tangani tahap yang gagal sebelum mengizinkan agen mengulang seluruh alur kerja. Sebagian besar kegagalan integrasi awal memiliki sejumlah kecil pemeriksaan praktis:

Sebuah panggilan API dapat berhasil di satu lapisan sementara tugas pengguna yang lebih besar belum selesai. Laporkan hasil yang benar-benar diamati. “Koneksi tool terbangun” berguna saat setup; “form terkirim” membutuhkan hasil form yang teramati.

Batasi jumlah retry untuk operasi challenge aktual. Hindari membuat tugas berbayar baru hanya untuk mendiagnosis konfigurasi. Kueri kapabilitas yang sudah bekerja menawarkan cara lebih murah untuk mengisolasi koneksi lokal. Panduan instalasi MCP resmi juga membantu ketika perintah server tidak dapat ditemukan.

Pertahankan konteks diagnostik yang berguna

Pertahankan versi paket, server key yang dikonfigurasi, nama operasi, dan apakah proses berhasil dimulai. Detail ini membantu pengembang lain mereproduksi kegagalan tanpa menerima key akun atau seluruh sesi browser. Untuk contoh ini, namespace yang hilang dan kegagalan startup server membutuhkan perbaikan berbeda meskipun keduanya awalnya tampak sebagai tool yang hilang.

Saat tugas berpindah antar pekerja, jaga rekaman aplikasi terpisah dari masa hidup klien diagnostik ini. Jangan biarkan agen mengubah objek lokal yang hilang menjadi permintaan berbayar baru secara otomatis. Aplikasi harus memutuskan apakah operasi sebelumnya masih relevan sebelum mengizinkan percobaan ulang.

Jaga integrasi pertama tetap kecil

Jaga integrasi pertama fokus pada satu alur kerja yang diizinkan dan set tool yang sempit. Contoh ini membuktikan klien dapat menemukan layanan nyata, menjalankan kueri kapabilitas non-solving, menerima data terstruktur, dan disconnect. Contoh ini tidak mengklaim model telah memilih tool yang benar atau bahwa CAPTCHA berbayar dan tugas browser telah selesai.

Dari fondasi itu, hubungkan operasi challenge yang dibutuhkan aplikasi Anda dan tambahkan uji penerimaannya. CapSolver menyediakan kapabilitas solver; aplikasi Mastra yang menentukan kapan kapabilitas itu tepat dan apa yang dihitung sebagai pekerjaan yang selesai. Siapkan kredensial di dashboard CapSolver Anda sebelum uji end-to-end terpisah tersebut.

FAQ

T: Bisakah saya menguji koneksi tanpa API key LLM?

Bisa. Contoh ini memanggil tool yang ditemukan secara langsung melalui klien MCP Mastra. Contoh ini tidak meminta model bahasa menghasilkan respons atau memilih tool.

T: Apakah kueri kapabilitas adalah solve CAPTCHA yang nyata?

Bukan. Kueri ini mengembalikan informasi handler terdaftar dan tipe CAPTCHA dari layanan yang terinstal. Kueri ini tidak memvalidasi solve berbayar atau state halaman browser.

T: Mengapa tool-nya bernama capsolver_get_supported_captchas?

Prefiks berasal dari server key capsolver. Mastra menambahkan namespace tersebut ke nama tool remote dalam daftar yang dipipihkan.

T: Haruskah setiap tool yang ditemukan tersedia untuk agen saya?

Tidak. Pilih kapabilitas yang diperlukan untuk tugas yang ditetapkan kepadanya, lalu uji pemilihan dan eksekusi terhadap izin dan alur kerja aplikasi Anda.

T: Kapan saya harus memanggil disconnect?

Disconnect ketika tidak ada pemanggilan lebih lanjut yang dibutuhkan melalui klien. Diagnostik sekali jalan dapat menutup di finally; agen yang berjalan membutuhkan koneksi sepanjang pemakaian tool.

T: Apakah ini membuktikan alur kerja browser produksi saya akan berfungsi?

Tidak. Ini memverifikasi integrasi klien–server lokal dan kueri. Produksi tetap membutuhkan kredensial yang valid, parameter tugas yang didukung, state browser yang sesuai, dan pemeriksaan aplikasi end-to-end.