Mastra 验证码求解器集成：一份实用的 MCP 指南

摘要

• Mastra 的 MCPClient 可以启动本地 CAPTCHA 解决进程，并通过 stdio 发现其工具。
• listTools() 会返回带命名空间的工具，例如针对示例服务器 key 返回 capsolver_get_supported_captchas。
• 在引入大语言模型或提交付费 CAPTCHA 任务之前，先直接执行一次能力查询。
• 只选择代理真正需要的工具，而不是自动附加所有已发现的能力。
• 在独立检查完成后关闭 MCP 客户端，并区分“求解器结果”和“浏览器工作流完成”这两种状态。

Mastra CAPTCHA 求解器集成在 TypeScript 应用中，为验证检查点提供了一个明确的工具边界。浏览器工作流可能已经知道在挑战前后该做什么，而代理需要一种受支持的方式来请求挑战操作。MCP 将这一能力连接进来，无需在求解器底层 API 之外再包一层额外封装。

本示例中提供本地服务器的是 CapSolver。本指南使用真实的 Mastra 客户端来发现其工具并执行一次“受支持类型”查询，然后说明如何为代理附加适当子集，并保持“工具响应”和“已完成网页任务”之间的区分。示例是本地集成检查，不涉及第三方网站或付费 CAPTCHA。

CAPTCHA 工具在 Mastra 应用中的位置

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 环境在其他位置，请修改路径，而不是依赖 shell PATH 中“第一个被找到的 Python”。

本次直接工具检查不需要模型凭据。基于模型的响应需要模型提供方的认证；付费 CAPTCHA 操作则需要相应求解器账号凭据和任务参数。这种分离让你可以在引入模型行为、浏览器状态或账号费用前，就先诊断安装问题。

连接 MCPClient 并查询受支持的 CAPTCHA 类型

将 MCPClient 连接到已安装的 Python 进程，发现工具并执行一次能力查询。在项目目录中将以下内容保存为 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 的客户端结合。脚本针对已安装包执行，包括能力调用和断开连接。它不会构造虚假服务器响应，也不会提交挑战。

在同一项目目录中运行：

node mastra-check.mjs

测试得到的列表包括：capsolver_solve_captcha、capsolver_detect_captchas、capsolver_solve_on_page、capsolver_get_balance 和 capsolver_get_supported_captchas。能力调用返回如下结构化结果：

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

该结果描述了已安装包的已注册处理器和类型值。这并不代表 CapSolver 网站上列出的所有产品都可通过此包版本使用。脚本在关闭客户端后还打印了 DISCONNECTED。你的运行结果中可能在这些值附近包含额外的服务器诊断行。

在为代理附加工具前先理解名称

Mastra 会使用配置的服务器 key 为扁平化后的工具列表加命名空间。此处 capsolver 是服务器 key，get_supported_captchas 是远程工具名，因此在返回对象中生成 capsolver_get_supported_captchas。

请使用返回的 key，而不是根据某个展示标签去猜测。重命名服务器条目会改变代码中应期望的 key。在将已运行的配置迁移到更大的应用中时，在复用查找逻辑或包含工具名的代理指令前，务必再次检查已发现的工具。

MCPClient 参考文档记录了发现与连接生命周期。请将包版本和你的安装笔记保存在一起，从参考文档中直接复制与你所安装版本一致的方法名，而不是拿当前客户端去套用旧教程中的调用方式。

为每项任务选择工具子集

请根据代理可能执行的工作来选择工具子集。一个安装向导可能只需要能力查询；一个已能提取任务参数的工作流可能需要面向 token 的求解；面向页面的工作流则有不同的浏览器依赖和会话要求。

对于真实的 Mastra 代理，请从相关的已发现条目中构造 tools 对象，并通过代理文档中的 tools 配置提供。只要代理有可能调用工具，就保持 MCP 连接存活。此独立脚本的工作仅为一次查询，因此会立即断开；如果不加修改就复制到长时运行代理上，会导致连接提前被关闭。

直接查询让传输与数据清晰可见，而无需让模型来选择工具。通过之后，再在正常的模型凭据和应用权限规则下单独测试代理的工具选择。一次成功的直接查询应有助于隔离后续测试，而不是取而代之。

兑换你的 CapSolver 奖励码

立刻提升你的自动化预算！
在为 CapSolver 账号充值时使用奖励码 CAP26，每次充值即可额外获得 5% 奖励——无次数上限。
现在就前往 CapSolver 控制台 兑换

将工具结果接入浏览器工作流

将工具结果传递给负责已批准浏览器任务的组件。面向 token 的结果和面向页面的结果需要不同处理方式，因此在围绕它添加代理提示前，先决定应用要使用哪种接口。

如果你的代码已经知道受支持的 CAPTCHA 类型及其必需参数，求解工具可以接收该结构化输入。浏览器代码仍需负责按文档集成路径应用结果，并观察应用的下一状态。一次成功的工具调用并不能替代这些检查。

对于服务器的基于浏览器工具，请安装其文档要求的依赖并确认会话是如何创建的。通过本地命令启动的服务是一个独立进程，不会自动继承其他浏览器的已打开标签页、表单状态或已认证会话。当你的程序需要直接与自己已控制的页面对象交互时，核心 SDK 是另一种需要评估的接口。

一条 QA 记录可以捕获已达到的阶段、选用的工具、工具结果及最终应用断言。这些字段回答的是不同问题：连接失败关乎集成；任务错误关乎求解请求；缺少确认状态则关乎应用工作流。在日志和面向用户的状态消息中要保留这些区分。

在产生失败的阶段处理失败

在允许代理重复整条工作流之前，先处理失败的那个阶段。大多数初始集成失败都有少量实用的首要检查项：

在一个层级上的API 调用可能成功，而更大范围的用户任务仍未完成。要报告实际观察到的结果。“已建立工具连接”在安装阶段很有用，而“表单已提交”则需要有表单结果可见。

针对真实挑战操作，要限制重试次数。避免仅为诊断配置问题就新建付费任务。可工作的能力查询提供了一种成本更低的方式来隔离本地连接问题。当服务器命令无法定位时，官方 MCP 安装指南也会有所帮助。

保留有用的诊断上下文

保留包版本、配置的服务器 key、操作名称以及进程是否成功启动。这些细节可以帮助其他开发者在无需账号 key 或完整浏览器会话的前提下复现失败。就本示例而言，“缺少命名空间”和“服务器启动失败”即使最初都表现为工具缺失，其修复方式也不同。

当任务在不同工作者之间转移时，要将应用记录与此诊断客户端的生命周期分开。不要让代理因为缺少本地对象就自动发起新的付费请求。应用本身应在允许再次尝试前判断之前的操作是否仍然相关。

让第一次集成尽量小而聚焦

第一次集成应聚焦于一个被允许的工作流和一小组工具。本示例证明客户端可以发现真实服务、执行非求解的能力查询、接收结构化数据并断开连接。它并不声称模型选择了正确工具，也不声称付费 CAPTCHA 和浏览器任务已完成。

在此基础上，连接应用所需的挑战操作并添加其验收测试。CapSolver 提供求解能力；Mastra 应用则决定何时适用以及何种结果才算工作完成。在执行那次独立的端到端测试前，请先在你的 CapSolver 控制台 中准备好凭据。

常见问题

问：没有 LLM API key 也能测试连接吗？

可以。示例通过 Mastra 的 MCP 客户端直接调用已发现的工具，不会让大语言模型生成响应或选择工具。

问：能力查询算一次真实的 CAPTCHA 求解吗？

不算。它返回的是已安装服务中的已注册处理器和 CAPTCHA 类型信息，不会校验一次付费求解或网页页面状态。

问：为什么工具名叫 capsolver_get_supported_captchas？

前缀来自 capsolver 服务器 key。Mastra 会在扁平列表中为远程工具名添加该命名空间。

问：所有发现到的工具都应该对代理开放吗？

不应该。仅选择其被指派任务所需的能力，然后在应用的权限和工作流之上测试工具选择和执行。

问：我该何时调用 disconnect？

当客户端不再需要发起任何调用时就应断开连接。一次性的诊断脚本可以在 finally 中关闭；运行中代理则需要在整个工具使用期间保持连接。

问：这能证明我的生产浏览器工作流一定可用吗？

不能。它验证的是本地客户端-服务器集成和查询。生产环境仍需要有效凭据、受支持的任务参数、合适的浏览器状态以及一次端到端应用检查。