如何启用具有实时网络访问能力的Mastra AI代理

关键要点：

• 在您连接工具之前，Mastra agents 对实时网络视而不见 — MCP 是最干净的进入方式。 一个 Mastra Agent 基于其模型和您提供的任何工具进行推理。指向 Scrapeless MCP 服务器，代理即可获取实时 Google 搜索、JavaScript 渲染及完整的反检测云浏览器，而无需手动编写任何抓取器。
• 一个 MCPClient 加上 await mcp.listTools() 可将所有功能连接起来。 使用 scrapeless 服务器条目构造 MCPClient，将 await mcp.listTools() 传入 new Agent({ tools })，代理便会获得 Google SERP 抓取器、趋势抓取器、HTML/Markdown/截图助手以及 16 个浏览器自动化工具 — 所有工具都是类型化的 TypeScript 工具。
• 代理能够根据简单提示进行搜索、渲染和驱动浏览器。 使用自然语言任务调用 agent.generate(...) 或 agent.stream(...)，Mastra 将逐步组成正确的 Scrapeless 工具调用，而不受训练截止知识的限制。
• 住宅代理和反检测由云端处理。 每个请求都通过 Scrapeless 反检测云浏览器路由，覆盖 195 个以上国家的住宅代理，因此代理在商业网站上获得的响应是已渲染且可用的，您机器上无需任何代理或指纹设置。
• 涵盖 SERP、无状态抓取和浏览器自动化的 21 种工具。 Scrapeless MCP 服务器提供 google_search、google_trends、scrape_html/scrape_markdown/scrape_screenshot，以及 16 个 browser_* 工具 — 一旦 Mastra 加载这些工具，名称空间将为 scrapeless_<tool>，每个轮次中代理规划者所引用的表面。
• 标准输入或可通过 HTTP 流传输。 使用 npx 在本地启动服务器，或将相同的 MCPClient 指向可流式传输的 HTTP 端点，以实现无服务器函数、远程工作者和 CI 运行器。
• 免费开始。 新的 Scrapeless 账户包括免费抓取浏览器运行时 — 请在 app.scrapeless.com 注册。

介绍：一款可以最终读取实时网络的 TypeScript 代理

Mastra 是一个开源的 TypeScript 框架，用于构建 AI 代理。您定义一个包含模型、一组指令和可以调用的工具的 Agent，然后可以使用 agent.generate(...) 或 agent.stream(...) 从自己的代码驱动它。它是一种在 Node 或无服务器应用中安全、清晰的方式来部署代理。Mastra 代理无法独立查看实时网络，它的知识在模型的训练截止点及您明确提供的工具处停止。

Mastra 对这个边界有明确的设计：代理对世界的访问正好是您附加的工具集。这使得工具层成为添加实时网络访问的地方 — 模型上下文协议 (MCP) 是标准、框架无关的实现方式。Mastra 通过 @mastra/mcp 包提供一流的 MCP 支持，因此任何 MCP 服务器都成为一组原生的、类型化的 Mastra 工具。在您连接一个之前，代理无法获取当前 SERP、阅读竞争对手的定价页面、检查最新的变更日志或渲染 JavaScript 仅应用。

这篇文章通过将 Scrapeless MCP 服务器连接到 Mastra 来缩小这个差距。一个 MCPClient 为代理提供 Google 搜索、JavaScript 渲染和完整的反检测云浏览器，所有这些都可以通过您已经传递给 agent.generate(...) 的自然语言提示访问。欲了解通过另一个 MCP 客户端访问相同 Scrapeless 表面的方法，请参见 Pi Agent 集成。

您可以用它做什么

• 通过 TypeScript 代理进行实时 SERP 研究。 请求代理运行 google_search 查询，并返回前几名结果的 JSON，因此研究可以在您的应用内进行，而不是单独的浏览器标签中。
• 竞争对手和定价快照。 在提示中传递 URL，让代理渲染页面并提取计划名称、价格和功能到结构化记录中，您的代码可以保留。
• 代码相关的文档和变更日志查找。 让代理获取库的当前文档或发布说明，作为干净的 markdown，并根据已渲染的文本进行推理，而不是依赖过时的 API 记忆。
• 市场和趋势检查。 使用 google_trends 拉取特定区域内某个主题的兴趣信号，然后以当前证据为基础撰写功能说明、内容计划或实验想法。
• 将 JavaScript 页面提取到类型化记录中。 将代理指向单页面应用；云浏览器进行加载，代理将结果解析为您工作流程使用的类型化对象。
• 多步骤浏览器流程。 链接 browser_goto、browser_click、browser_type 和 browser_scroll，以便代理走分页、展开面板或逐步完成向导，然后再进行提取。
• 截图捕获以供审核。 使用 scrape_screenshot 或 browser_screenshot 将呈现的页面作为图像抓取，以便代理可以返回到您的应用程序。
• 先搜索后读取的管道。 将 google_search 与 scrape_markdown 结合使用，让代理找到最顶部的结果，逐一阅读，并在单次代理回合中进行总结。

为什么选择 Scrapeless MCP 服务器

Scrapeless MCP 服务器是一个可自定义的、抗检测的桥梁，连接 AI 代理与实时网络。对于 Mastra 来说，它带来了：

• 带有 JavaScript 渲染的抗检测云浏览器。 在提取之前，页面在完整的 Scrapeless 抓取浏览器 中被水合处理，因此单页应用（SPA）、无限滚动 Feed 和懒加载面板成为 browser_goto + browser_get_html 的首选目标。
• 遍布195多个国家的住宅代理。 地理绑定查询返回本地用户看到的列表，代理出口完全由 Scrapeless 处理。
• 通过 npx 发出一个标准输入输出命令，无需抓取代码。 服务器作为子进程从 npx -y scrapeless-mcp-server 启动；除了 MCPClient 之外，没有任何东西需要构建、托管或导入到您的项目中。
• 21 种工具涵盖搜索引擎结果页面（SERP）、无状态抓取和全浏览器自动化。 google_search 和 google_trends 涉及 SERP 数据，而 scrape_html/scrape_markdown/scrape_screenshot 涉及单次页面抓取，16 个 browser_* 工具涵盖状态导航、点击、输入、滚动和截图。
• 工具以本地 Mastra 工具的形式出现。 由于 @mastra/mcp 将 MCP 工具适配为 Mastra 自有的工具类型，因此 Scrapeless 界面与您手动编写的任何工具完全一致——有类型、命名空间，并准备好供代理的计划使用。

免费计划足以将其连接并运行真实提示；当您超出它的限制时，请在 定价页面 上比较配额。在 app.scrapeless.com 上的免费计划中获取您的 API 密钥。

前提条件

• 工作站上安装 Node.js 18 或更新版本 — Mastra 针对现代 Node，stdio MCP 服务器通过 npx 启动。
• 一个配置了模型提供者的 Mastra 项目。 Mastra 的 Agent 需要一个 model；代理循环需要一个来自您接入的提供者的工作模型，然后才能运行任何工具调用。
• 一个 Scrapeless 账户和 API 密钥 — 在 app.scrapeless.com 上注册免费计划并从 设置 → API 密钥管理 中复制密钥。
• 对 TypeScript 的基本熟悉度 — 整个设置由两个包和一个小的 MCPClient 定义组成。

将 Scrapeless 连接到 Mastra

设置分为五个步骤；每个步骤均可独立验证。

1. 安装 Mastra MCP 和核心包

将 MCP 客户端包和代理核心添加到您的项目中：

npm install @mastra/mcp @mastra/core

@mastra/mcp 提供连接到 MCP 服务器的 MCPClient 类，而 @mastra/core 提供您附加工具的 Agent 类。

2. 配置 MCPClient（标准输入输出）

创建一个只有一个 scrapeless 服务器条目的 MCPClient。当存在 command 时，Mastra 会自动检测标准输入输出传输并将服务器作为子进程启动：

// npm install @mastra/mcp @mastra/core
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  id: "scrapeless-client",
  servers: {
    scrapeless: {
      command: "npx",
      args: ["-y", "scrapeless-mcp-server"],
      env: { SCRAPELESS_KEY: process.env.SCRAPELESS_KEY! },
    },
  },
});

这里有一个细节很重要：Scrapeless MCP 服务器从 SCRAPELESS_KEY 读取其密钥，而不是 SCRAPELESS_API_KEY — Scrapeless CLI 和 SDK 使用 SCRAPELESS_API_KEY，但 MCP 服务器是文档中的例外。请将密钥保存在您的环境中（export SCRAPELESS_KEY=...），并通过 env 对象传递，而不是硬编码。服务器源代码位于 github.com/scrapeless-ai/scrapeless-mcp-server。

3. 或使用 HTTP 流可传输

如果主机无法可靠地生成 npx——无服务器函数、远程工作者或 CI 沙盒——则将相同的 MCPClient 指向 Scrapeless HTTP 终端，而不是本地进程。传递 url 并通过 requestInit 将密钥设置为头部：

const mcp = new MCPClient({
  servers: {
    scrapeless: {
      url: new URL("https://api.scrapeless.com/mcp"),
      requestInit: { headers: { "x-api-token": process.env.SCRAPELESS_KEY! } },
    },
  },
});

当您提供一个 url 时，Mastra 首先尝试流式 HTTP，然后自动回退到传统的 SSE 传输。在两种模式中，相同的键值都可以使用；HTTP 可流式传递该值作为 x-api-token 头，而不是 SCRAPELESS_KEY 环境变量。在开发者工作站上，标准输入是正确的默认选项；在难以保持长时间运行的子进程的任何地方，HTTP 可流式传输是合适的默认选择。

4. 将工具附加到代理上

通过 await mcp.listTools() 加载工具，然后直接传入新的 Agent。使用这种静态方法，工具在构造时只解析一次，并命名为 serverName_toolName：

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "web-agent",
  name: "Web-Aware Agent",
  instructions: "使用 Scrapeless 工具搜索和读取实时网页。",
  model: "<your-provider-model>",
  tools: await mcp.listTools(), // -> scrapeless_google_search, scrapeless_scrape_markdown, scrapeless_browser_* ...
});

使用您的提供程序所公开的模型 — Mastra 的 Agent 接受任何提供程序模型 ID，并且工具的工作不需要特定的模型或版本。

对于动态替代方案，Mastra 还提供 await mcp.listToolsets()，该方法每次调用解析工具并将其命名为 serverName.toolName。在调用时而不是在构造时传递工具集：

const result = await agent.stream(prompt, {
  toolsets: await mcp.listToolsets(),
});

当一个客户端服务于整个应用时，listTools() 是最简单的路径；listToolsets() 适用于每个请求可能携带不同凭证或服务器选择的多租户设置。当您完成客户端时，请使用 await mcp.disconnect() 进行清理。

5. 通过列举 21 个工具进行验证

解析工具并检查其键可以确认握手已完成，服务器正在报告其完整表面：

const tools = await mcp.listTools();
console.log(Object.keys(tools));

输出列出了服务器的 21 个工具，每个都命名为 scrapeless_<tool> — Google 数据工具（scrapeless_google_search, scrapeless_google_trends），单次页面助手（scrapeless_scrape_html, scrapeless_scrape_markdown, scrapeless_scrape_screenshot），以及云浏览器原语（scrapeless_browser_create, scrapeless_browser_goto, scrapeless_browser_get_html, scrapeless_browser_get_text, scrapeless_browser_click, scrapeless_browser_type, scrapeless_browser_press_key, scrapeless_browser_scroll, scrapeless_browser_scroll_to, scrapeless_browser_screenshot, scrapeless_browser_snapshot, scrapeless_browser_wait, scrapeless_browser_wait_for, scrapeless_browser_go_back, scrapeless_browser_go_forward, scrapeless_browser_close）。

您如何实际使用它：提示您的 Mastra 代理

在连接 MCP 服务器后，您可以通过在代码中调用代理来获取实时网页数据 — 而不是手动编写工具调用。代理读取 Scrapeless MCP 服务器公开的工具列表，并根据需要选择 scrapeless_google_search、scrapeless_scrape_markdown 或 scrapeless_browser_* 工具，逐步根据自然语言任务组合它们。您这边无需编写工具 JSON。您可以通过 agent.generate(prompt) 来驱动单个回合，或者通过 agent.stream(prompt) 按令牌流式运行。

您可以粘贴的提示

工作示例

您编写（在您的 TypeScript 应用中的一次调用）：

const result = await agent.generate(
使用Scrapeless google_search工具查找“mastra ai github”的顶级结果，并将前3个结果作为{title, link}的JSON数组返回。
- 工具参数采用 camelCase：请准确传递 `sessionId`、`proxyCountry` 等字段。
- `proxyCountry` 是一种请求，而不是保证——它可以根据您帐户上配置的地区进行推迟，因此在地理定位重要时，请确认出口地区。
- 工具输出中的值是内容相关的：结果计数、排序和片段文本随着实时查询而变化。

结论：从 TypeScript 搜索、呈现和浏览

整个集成归结为一个 MCPClient 加上自然语言提示。只需提供一个 scrapeless 服务器条目，将 await mcp.listTools() 提交给 new Agent({ tools })，并在 SCRAPELESS_KEY 中输入您的密钥，Mastra 代理就可以实现实时的 Google 搜索、JavaScript 渲染和完整的反检测云浏览器——恰好是代理未单独提供的网络层。您描述任务；代理选择工具。

如果您要连接其他代理，相同的 Scrapeless MCP 服务器也可以使用：请参见 Pi Agent 集成 和 Scrapeless MCP 服务器概述 以获取完整的工具参考。将您的 API 密钥保存在 SCRAPELESS_KEY 中，开发本地时首选 stdio 传输，托管运行时时首选 HTTP 可流式传输，选择 listTools() 用于单个静态客户端，或选择 listToolsets() 用于动态每次调用集，交由代理选择工具。完整参考见 docs.scrapeless.com。

准备构建您的 AI 驱动的数据管道了吗？

加入我们的社区以申请免费计划，并与构建 Mastra + Scrapeless MCP 代理的开发人员联系：Discord · Telegram。

在 app.scrapeless.com 注册以获取免费的 Scraping Browser 运行时，并将上述集成调整为您的团队所需的 SERP、页面和区域。完整参考见 docs.scrapeless.com。

常见问题解答

问：为什么 Mastra 代理需要 MCP 服务器才能访问网络？

因为 Mastra Agent 只能调用您附加的工具，并且没有内置的网络搜索或浏览器。MCP 是一种标准的、与框架无关的方式来添加此功能，而 @mastra/mcp 将任何 MCP 服务器适配为本机 Mastra 工具。连接 Scrapeless 使代理可以在一一步中获得实时 Google 搜索、已渲染页面访问和完整的反检测云浏览器。

问：listTools() 和 listToolsets() 之间有什么区别？

await mcp.listTools() 一次性解析工具并返回使用命名空间的 serverName_toolName（例如 scrapeless_google_search）；您在构造时将结果传递给 new Agent({ tools })。await mcp.listToolsets() 每次调用解析工具并将它们命名为 serverName.toolName；在调用时通过 agent.stream(prompt, { toolsets }) 或 agent.generate(prompt, { toolsets }) 将结果传递。使用 listTools() 适用于单个静态客户端，而 listToolsets() 当每个请求可能携带不同的凭据或服务器选择时使用。

问：哪个环境变量包含 Scrapeless 密钥？

SCRAPELESS_KEY。这是文档中列出的例外——Scrapeless CLI 和 SDK 读取 SCRAPELESS_API_KEY，但 MCP 服务器读取 SCRAPELESS_KEY。在 stdio 配置中，您将其通过 env 对象作为 process.env.SCRAPELESS_KEY 传递；在 HTTP 可流式传输模式中，您将同样的值作为 x-api-token 头发送。

问：stdio 与 HTTP 可流式传输——何时使用各自？

当服务器在本地与应用一起运行时使用 stdio：Mastra 将 scrapeless-mcp-server 启动为子进程，并通过标准输入/输出与之通信。当运行时是无服务器或远程，并且无法保持本地子进程存活时使用 HTTP 可流式传输（https://api.scrapeless.com/mcp 的 url，使用 requestInit 的 x-api-token 头）。当您提供 url 时，Mastra 首先尝试 Streamable HTTP，并自动回退到传统 SSE。

问：这是否需要特定的模型？

不需要。Mastra 的 Agent 可以接受任何提供者模型 ID，因此您可以使用提供者提供的模型。Scrapeless 工具是模型无关的；选择一个擅长处理工具调用的模型，代理将以相同的方式组合 Scrapeless 工具，而不管提供者是什么。

问：我的项目中的工具如何被打上类型？

@mastra/mcp 将每个 MCP 工具转化为 Mastra 自己的工具类型，因此无废工具的显示方式与手动书写的工具完全相同——具备命名空间并为代理的计划者准备好。您通过 tools: await mcp.listTools() 附加它们，而不必自己编写工具 JSON。

问：通过代理进行网页抓取是否合法？

抓取公开可用的数据通常是被允许的，但您需要对如何使用这些数据负责。请查看每个网站的服务条款并遵守 robots.txt，记住有关个人数据和访问的规则因司法管辖区而异。如果有疑问，请就您的具体用例寻求法律建议。

问：可以在没有 Mastra 的情况下使用这个吗？

可以。无废 MCP 服务器是一个标准的 MCP 服务器，因此任何兼容 MCP 的客户端都可以调用它——或者您可以通过 JSON-RPC 直接操作它（initialize，然后是 tools/list 和 tools/call）。Mastra 是 TypeScript 应用的便利，而不是必需的。