Tích hợp Trình Giải CAPTCHA Mastra: Hướng Dẫn MCP Thực Tiễn

Tóm tắt nhanh

• MCPClient của Mastra có thể khởi chạy một tiến trình solver CAPTCHA cục bộ và khám phá các tool của nó qua stdio.
• listTools() trả về các tool có namespace, ví dụ capsolver_get_supported_captchas với server key mẫu.
• Thực thi truy vấn khả năng (capability query) ngay trước khi dùng mô hình ngôn ngữ hoặc gửi một tác vụ CAPTCHA trả phí.
• Chỉ chọn các tool mà agent của bạn cần, thay vì tự động gắn mọi khả năng đã khám phá.
• Đóng MCP client khi một bước kiểm tra độc lập hoàn tất, và phân biệt kết quả solver với việc hoàn thành workflow trình duyệt.

Tích hợp solver CAPTCHA của Mastra cung cấp cho ứng dụng TypeScript một ranh giới tool rõ ràng cho điểm kiểm tra xác minh. Một workflow trình duyệt có thể đã biết cần làm gì trước và sau khi gặp thử thách, trong khi agent cần một cách được hỗ trợ để yêu cầu thao tác giải thử thách. MCP kết nối khả năng đó mà không cần thêm một lớp bao bọc quanh API nền tảng của solver.

CapSolver cung cấp server cục bộ trong ví dụ này. Hướng dẫn sử dụng Mastra client thực để khám phá các tool và thực thi một truy vấn kiểu hỗ trợ. Sau đó giải thích cách gắn một tập con phù hợp vào agent và giữ rõ ràng sự khác biệt giữa phản hồi tool và một tác vụ web đã hoàn thành. Ví dụ này là một bước kiểm tra tích hợp cục bộ, không cần website bên thứ ba hay CAPTCHA trả phí.

Công cụ CAPTCHA nằm ở đâu trong một ứng dụng Mastra?

Công cụ CAPTCHA nằm tại một bước thử thách đã biết trong một workflow ứng dụng đã được cấp quyền. Mastra điều phối các tool được phơi bày cho agent; solver thực hiện một thao tác cụ thể; mã trình duyệt hoặc mã ứng dụng của bạn sở hữu các bước sử dụng kết quả đó.

Hãy hình dung một dịch vụ QA đang chạy bài kiểm thử form do chủ sở hữu kiểm soát. Bài test đã chuẩn bị dữ liệu và đến một thử thách được hỗ trợ. Một thao tác solver có thể cung cấp câu trả lời liên quan, nhưng bài test vẫn phải gửi form đúng cách và kiểm tra xác nhận mong đợi. Agent không nên báo cáo thành công chỉ vì nó nhận được một phản hồi tool không rỗng.

Dự án Mastra cung cấp framework, trong khi hướng dẫn kết nối MCP mô tả giao diện client được sử dụng ở đây. Đây là một kết nối MCP trực tiếp. Nó không ngụ ý rằng solver là một nhà cung cấp native trong mọi sản phẩm Mastra hoặc mọi danh mục tích hợp được host.

Chuẩn bị một dự án tích hợp cục bộ nhỏ

Chuẩn bị một dự án Node.js cục bộ và một môi trường Python để mỗi phần có bộ phụ thuộc rõ ràng. Ví dụ được thực thi với Node.js 24.16.0, Python 3.12.14, @mastra/mcp 2.4.1 và capsolver-mcp 0.1.3. Gói Mastra được chọn yêu cầu Node.js 22.13.0 trở lên; dùng runtime Node.js 24 đã kiểm thử giúp tránh lỗi không tương thích với runtime cũ hơn.

Chạy các bước này trong một thư mục dự án mới trên macOS hoặc 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

File .mjs dưới đây dùng hỗ trợ ES module của Node. Đường dẫn server được resolve tương đối so với thư mục bạn chạy script, vì vậy hãy thực thi từ thư mục gốc dự án chứa py. Nếu môi trường Python của bạn nằm ở nơi khác, hãy thay đổi đường dẫn thay vì dựa vào việc Python nào tình cờ đứng đầu PATH của shell.

Không cần thông tin xác thực model cho lần kiểm tra tool trực tiếp này. Các phản hồi do model điều khiển cần xác thực từ nhà cung cấp model. Các thao tác CAPTCHA trả phí yêu cầu thông tin tài khoản solver phù hợp và tham số tác vụ. Sự tách biệt này cho phép bạn chẩn đoán lỗi cài đặt trước khi đưa hành vi của model, trạng thái trình duyệt hoặc chi phí tài khoản vào.

Kết nối MCPClient và truy vấn các loại CAPTCHA được hỗ trợ

Kết nối MCPClient tới tiến trình Python đã cài đặt, khám phá các tool và thực thi truy vấn khả năng. Lưu đoạn sau thành mastra-check.mjs trong thư mục dự án:

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 này kết hợp giao diện khởi chạy CapSolver MCP chính thức với client của Mastra. Script được thực thi với các gói đã cài, bao gồm cả lời gọi capability và thao tác ngắt kết nối. Nó không dựng sẵn một phản hồi server giả hay gửi một thử thách.

Chạy nó từ cùng thư mục dự án:

node mastra-check.mjs

Danh sách đã kiểm thử gồm capsolver_solve_captcha, capsolver_detect_captchas, capsolver_solve_on_page, capsolver_get_balance và capsolver_get_supported_captchas. Lời gọi capability trả về kết quả có cấu trúc như sau:

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

Kết quả mô tả các handler đã đăng ký và các giá trị type của gói đã cài. Nó không có nghĩa là mọi sản phẩm được liệt kê trên website CapSolver đều khả dụng qua phiên bản gói này. Script cũng in DISCONNECTED sau khi đóng client. Lần chạy của bạn có thể bao gồm thêm các dòng chẩn đoán server quanh những giá trị này.

Hiểu tên trước khi gắn tool vào agent

Mastra thêm namespace cho danh sách tool phẳng bằng server key đã cấu hình. Ở đây, capsolver là server key và get_supported_captchas là tên tool phía xa, tạo ra capsolver_get_supported_captchas trong đối tượng trả về.

Hãy dùng khóa (key) trả về thay vì đoán từ nhãn hiển thị. Đổi tên entry server sẽ thay đổi key mà mã của bạn kỳ vọng. Khi chuyển một cấu hình đang hoạt động vào ứng dụng lớn hơn, hãy kiểm tra lại các tool đã khám phá trước khi dùng lại một phép tra cứu hoặc một hướng dẫn cho agent có nhắc đến tên tool.

Tài liệu tham khảo MCPClient mô tả việc khám phá và vòng đời kết nối. Giữ lại phiên bản gói cùng với ghi chú thiết lập của bạn. Sao chép tên phương thức từ tài liệu tham khảo cho đúng phiên bản đã cài thay vì kết hợp một client hiện tại với các lời gọi trong một tutorial cũ.

Chọn một tập tool con cho từng công việc

Chọn tập tool dựa trên công việc mà agent có thể thực hiện. Một trợ lý thiết lập có thể chỉ cần truy vấn capability. Một workflow vốn đã trích xuất tham số tác vụ có thể cần giải dựa trên token. Một workflow hướng-trang có các phụ thuộc trình duyệt và yêu cầu session khác.

Với một agent Mastra thực, hãy dựng đối tượng tools từ các entry thích hợp đã khám phá và cung cấp nó qua cấu hình tools được tài liệu hóa của agent. Giữ kết nối MCP hoạt động trong suốt khoảng thời gian agent có thể gọi tool. Script độc lập này ngắt kết nối ngay vì nhiệm vụ duy nhất là một truy vấn; sao chép nguyên vòng đời đó sang một agent chạy lâu dài sẽ đóng kết nối quá sớm.

Truy vấn trực tiếp giúp bạn thấy rõ transport và dữ liệu mà không phải yêu cầu model chọn tool. Sau khi nó vượt qua, hãy kiểm thử việc chọn tool của agent một cách riêng rẽ với thông tin xác thực model bình thường và các quy tắc quyền hạn của ứng dụng. Một truy vấn trực tiếp thành công nên giúp cô lập bài test tiếp theo, không thay thế nó.

Nhận mã thưởng CapSolver của bạn

Tăng ngân sách tự động hóa ngay lập tức!
Dùng mã thưởng CAP26 khi nạp tiền vào tài khoản CapSolver để nhận thêm 5% bonus cho mỗi lần nạp — không giới hạn.
Đổi mã ngay trong Bảng điều khiển CapSolver

Kết nối kết quả tool với workflow trình duyệt

Kết nối kết quả tool với thành phần sở hữu tác vụ trình duyệt đã được phê duyệt. Kết quả kiểu token và kiểu trang (page-oriented) cần xử lý khác nhau, vì vậy hãy quyết định giao diện ứng dụng sẽ dùng trước khi thêm prompt agent xung quanh nó.

Nếu mã của bạn đã biết loại CAPTCHA được hỗ trợ và các tham số bắt buộc của nó, một tool giải có thể nhận input có cấu trúc đó. Mã trình duyệt vẫn chịu trách nhiệm áp dụng kết quả qua đường tích hợp được tài liệu hóa và quan sát trạng thái tiếp theo của ứng dụng. Một lời gọi tool thành công không thể thay thế cho các kiểm tra đó.

Với các tool dựa trên trình duyệt của server, hãy cài các phụ thuộc được tài liệu hóa và xác nhận cách session được tạo. Một service được khởi chạy qua lệnh cục bộ là một tiến trình riêng biệt. Nó không tự động kế thừa tab mở, trạng thái form hoặc session đã xác thực của một trình duyệt khác. Core SDK là một bề mặt khác cần đánh giá khi chương trình của bạn cần làm việc trực tiếp với một đối tượng trang mà nó đã kiểm soát.

Một bản ghi QA có thể lưu lại giai đoạn đã đạt tới, tool đã chọn, kết quả tool và khẳng định cuối cùng của ứng dụng. Những trường này trả lời các câu hỏi khác nhau. Lỗi kết nối liên quan đến tích hợp; lỗi tác vụ liên quan đến yêu cầu gửi tới solver; thiếu trạng thái xác nhận liên quan đến workflow ứng dụng. Hãy giữ các phân biệt đó trong log và thông điệp trạng thái cho người dùng.

Xử lý lỗi ở đúng giai đoạn sinh ra lỗi

Xử lý giai đoạn thất bại trước khi cho phép agent lặp lại toàn bộ workflow. Hầu hết lỗi tích hợp ban đầu chỉ có một nhóm nhỏ các bước kiểm tra thực tế:

Một lời gọi API có thể thành công ở một lớp trong khi tác vụ người dùng lớn hơn vẫn chưa hoàn tất. Hãy báo cáo kết quả thực sự được quan sát. “Đã thiết lập kết nối tool” hữu ích trong giai đoạn thiết lập; “đã gửi form” đòi hỏi phải quan sát được kết quả form.

Giữ số lần retry có giới hạn với các thao tác thử thách thực tế. Tránh tạo tác vụ trả phí mới chỉ để chẩn đoán cấu hình. Truy vấn capability đang hoạt động cung cấp một cách rẻ hơn để cô lập kết nối cục bộ. Hướng dẫn cài đặt MCP chính thức cũng hữu ích khi không tìm được lệnh server.

Giữ lại ngữ cảnh chẩn đoán hữu ích

Giữ lại phiên bản gói, server key đã cấu hình, tên thao tác và việc tiến trình có khởi động thành công hay không. Những chi tiết này giúp lập trình viên khác tái tạo lỗi mà không cần nhận khóa tài khoản hay toàn bộ session trình duyệt. Trong ví dụ này, thiếu namespace và lỗi khởi động server cần các cách sửa khác nhau dù ban đầu cả hai có thể đều xuất hiện như thiếu tool.

Khi một tác vụ chuyển giữa các worker, hãy giữ bản ghi ứng dụng của nó tách biệt với vòng đời của client chẩn đoán này. Đừng để agent tự động biến một object cục bộ bị thiếu thành một yêu cầu trả phí mới. Ứng dụng nên quyết định xem thao tác trước đó còn phù hợp hay không trước khi cho phép thử lại.

Giữ cho tích hợp đầu tiên nhỏ gọn

Giữ cho tích hợp đầu tiên tập trung vào một workflow được cho phép và một tập tool hẹp. Ví dụ này chứng minh client có thể khám phá dịch vụ thực, thực thi một truy vấn capability không giải CAPTCHA, nhận dữ liệu có cấu trúc và ngắt kết nối. Nó không khẳng định model đã chọn đúng tool hay CAPTCHA trả phí và tác vụ trình duyệt đã hoàn thành.

Từ nền tảng đó, hãy kết nối thao tác thử thách mà ứng dụng của bạn cần và thêm bài test chấp nhận của nó. CapSolver cung cấp khả năng solver; ứng dụng Mastra quyết định khi nào nó phù hợp và điều gì được tính là công việc đã hoàn thành. Chuẩn bị thông tin xác thực trong bảng điều khiển CapSolver trước bài test end-to-end riêng đó.

Câu hỏi thường gặp

Hỏi: Tôi có thể kiểm tra kết nối mà không cần khóa API LLM không?

Có. Ví dụ gọi trực tiếp một tool đã khám phá thông qua MCP client của Mastra. Nó không yêu cầu mô hình ngôn ngữ tạo phản hồi hay chọn tool.

Hỏi: Truy vấn capability có phải là một lần giải CAPTCHA thực không?

Không. Nó trả về thông tin handler đã đăng ký và loại CAPTCHA từ service đã cài. Nó không xác thực một lần giải trả phí hay trạng thái trang trình duyệt.

Hỏi: Tại sao tool lại tên là capsolver_get_supported_captchas?

Tiền tố đến từ server key capsolver. Mastra thêm namespace đó vào tên tool phía xa trong danh sách phẳng.

Hỏi: Có nên cho agent dùng mọi tool đã khám phá không?

Không. Hãy chọn các khả năng cần thiết cho nhiệm vụ được giao, rồi kiểm thử việc chọn và thực thi theo quyền hạn và workflow của ứng dụng.

Hỏi: Khi nào tôi nên gọi disconnect?

Ngắt kết nối khi không cần thêm lời gọi nào qua client nữa. Một chẩn đoán một-lần có thể đóng trong finally; một agent đang chạy cần giữ kết nối trong suốt thời gian sử dụng tool.

Hỏi: Điều này có chứng minh workflow trình duyệt ở môi trường production sẽ hoạt động không?

Không. Nó xác minh tích hợp client-server cục bộ và truy vấn. Production vẫn cần thông tin xác thực hợp lệ, tham số tác vụ được hỗ trợ, trạng thái trình duyệt phù hợp và một bài kiểm tra ứng dụng end-to-end.