Vercel AI SDK + Scrapeless: Công cụ Web cho Các Đại lý của Bạn qua MCP

Tóm tắt:

• Vercel AI SDK kết nối với Máy chủ MCP Scrapeless bằng createMCPClient từ @ai-sdk/mcp, truyền qua endpoint và header x-api-token trong cấu hình vận chuyển.
• await client.tools() trả về tất cả 21 công cụ — scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot, và một bộ 16 công cụ browser_* — được khóa theo tên, sẵn sàng để đưa vào generateText.
• Trong AI SDK phiên bản 5 trở đi, client MCP nằm trong gói riêng: nhập createMCPClient từ @ai-sdk/mcp, không phải experimental_createMCPClient từ ai, đã bị loại bỏ.
• Mỗi công cụ đều có phương thức execute, vì vậy bạn có thể gọi tools.scrape_markdown.execute({ url }) trực tiếp và đọc lại Markdown trước khi có mô hình tham gia — không cần khóa mô hình để tải hoặc gọi công cụ.
• Chỉ cần bước generateText cần một khóa nhà cung cấp mô hình, vì đây là nơi mô hình quyết định gọi công cụ nào.
• Bắt đầu với gói miễn phí Scrapeless và cho các tác nhân TypeScript của bạn những công cụ web thực sự.

Vercel AI SDK là bộ công cụ tiêu chuẩn để xây dựng ứng dụng AI trong TypeScript, và một mô hình bên trong nó chỉ có thể hoạt động thông qua các công cụ mà bạn truyền cho nó. Không có gì trong SDK cơ bản truy cập web trực tiếp. Giao thức Ngữ cảnh Mô hình (Model Context Protocol) thu hẹp khoảng cách đó: chỉ cần chỉ định client MCP của SDK tới một máy chủ, và mọi công cụ mà máy chủ đó cung cấp trở thành công cụ AI SDK mà bạn có thể đưa thẳng vào generateText hoặc streamText.

Hướng dẫn này kết nối AI SDK với Máy chủ MCP Scrapeless, tải 21 công cụ của nó, gọi một công cụ thực sự, và sau đó trao bộ cho một mô hình — được xác minh với endpoint thực. Bước duy nhất cần một khóa nhà cung cấp mô hình là gọi tạo, và bài viết này đánh dấu chính xác nơi mà dòng đó nằm.

Những gì Máy chủ MCP Scrapeless mang lại cho một tác nhân

Máy chủ MCP Scrapeless cung cấp các công cụ thu thập dữ liệu web và trình duyệt mà một tác nhân có thể gọi trực tiếp, vì vậy lớp thu thập dữ liệu không phải là điều bạn xây dựng hoặc lưu trữ. Một kết nối phục vụ 21 công cụ: scrape_markdown và scrape_html cho nội dung trang, google_search và google_trends cho dữ liệu tìm kiếm, scrape_screenshot cho các bản chụp, và một bộ 16 công cụ browser_* điều khiển trình duyệt đám mây qua các cú click, nhập liệu, cuộn trang và chờ đợi.

Các công cụ browser_* chạy trên trình duyệt đám mây Scrapeless, vì vậy một mô hình có thể điều hướng một trang tương tác và đọc những gì thực sự được hiển thị mà không cần trình duyệt trên máy của bạn. Đối với giao thức này, MCP là gì là phần giải thích, và LangChain + Scrapeless MCP kết nối cùng một máy chủ vào một ngăn xếp Python.

Điều kiện tiên quyết

• Node.js 22 hoặc mới hơn.
• Một khóa API Scrapeless từ bảng điều khiển, xuất ra là SCRAPELESS_API_KEY.
• Một khóa nhà cung cấp mô hình như OPENAI_API_KEY chỉ dành cho bước tạo. Việc tải và gọi các công cụ không cần một khóa.

Cài đặt

Cài đặt lõi AI SDK và gói client MCP.

npm install ai@7.0.34 @ai-sdk/mcp@2.0.16

Đặt khóa Scrapeless của bạn trong shell và giữ nguyên phần giữ chỗ khỏi mã nguồn của bạn.

export SCRAPELESS_API_KEY="sk_your_key_here"

Kết nối và tải các công cụ

createMCPClient mở kết nối. Vận chuyển http mang endpoint và các header, và client.tools() thực hiện quá trình bắt tay và trả về các công cụ được khóa theo tên.

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const names = Object.keys(tools).sort();
console.log("số lượng công cụ:", names.length);
console.log("các công cụ:", names.join(", "));

await client.close();

Máy chủ trực tiếp trả về 21 công cụ, được tải với chỉ khóa Scrapeless được thiết lập.

số lượng công cụ: 21
các công cụ: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

Lớp vận chuyển và lớp thông điệp tuân theo đặc điểm kỹ thuật của Giao thức Ngữ cảnh Mô hình, mà dựa trên đặc điểm kỹ thuật JSON-RPC 2.0. AI SDK cũng chấp nhận một thể hiện vận chuyển cho stdio hoặc máy chủ SSE; máy chủ Scrapeless là một endpoint HTTP được lưu trữ, vì vậy lớp vận chuyển http là lựa chọn đúng trong trường hợp này.

Gọi một công cụ trực tiếp

Mỗi mục trong đối tượng trả về là một công cụ SDK AI đầy đủ với phương thức execute, vì vậy bạn có thể gọi một cái trước khi bất kỳ mô hình nào được kết nối. execute nhận các tham số và một ngữ cảnh gọi, và trả về một kết quả mà content của nó là một danh sách các khối.

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const result = await tools.scrape_markdown.execute(
  { url: "https://quotes.toscrape.com/" },
  { toolCallId: "call_1", messages: [] },
);
const text = result.content
  .filter((block: { type: string }) => block.type === "text")
  .map((block: { text: string }) => block.text)
  .join("");
console.log("số ký tự markdown:", text.length);
console.log("có chứa một câu trích dẫn:", text.includes("Einstein"));

await client.close();

Lần gọi trả về trang ở định dạng Markdown, và việc kiểm tra nội dung xác nhận rằng đã nhận được văn bản thực.

số ký tự markdown: 4308
có chứa một câu trích dẫn: true

Đó là hình dạng mà một mô hình nhận được từ cùng một công cụ: nội dung trang mà nó có thể lý luận. Tài liệu công cụ AI SDK MCP đề cập đến các tùy chọn vận chuyển và client.close() mà bạn nên gọi khi công việc hoàn tất.

Để một mô hình gọi các công cụ

Phân tán các công cụ vào generateText và mô hình gọi chúng khi nhiệm vụ cần. Sử dụng công cụ đa bước cần có điều kiện dừng — stepCountIs cho phép mô hình gọi một công cụ, đọc kết quả, và trả lời. Đây là bước cần có khóa nhà cung cấp mô hình.

Lưu ý: khối này cần gói nhà cung cấp @ai-sdk/openai và OPENAI_API_KEY, trong đó không có cái nào được thiết lập ở đây. Tải 21 công cụ và lệnh gọi trực tiếp scrape_markdown ở trên hoạt động mà không cần chúng. Khối được hiển thị với hình dạng chính xác của nó; chỉ có việc đi vòng qua mô hình là một khoảng cách yêu cầu.

import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  stopWhen: stepCountIs(5),
  prompt:
    "Sử dụng scrape_markdown để lấy https://quotes.toscrape.com/ và liệt kê ba câu trích dẫn đầu tiên với tác giả.",
});
console.log(text);

await client.close();

Tại thời điểm chạy, mô hình đọc lời nhắc, gọi scrape_markdown với URL, nhận lại Markdown mà lệnh gọi trực tiếp đã trả về, và viết câu trả lời. Các công cụ là những đối tượng giống nhau cho dù mô hình gọi chúng hay bạn làm.

Kết luận

Vercel AI SDK cộng với Máy chủ Scrapeless MCP là một con đường ngắn từ một mô hình trống rỗng tới một mô hình đọc web thời gian thực. createMCPClient mở kết nối, client.tools() trả về tất cả 21 công cụ, execute chứng minh một công cụ hoạt động, và việc phân tán tools vào generateText gửi tập hợp cho mô hình. Chỉ bước tạo ra cần có một khóa mô hình, vì vậy bạn có thể kết nối và kiểm tra toàn bộ bề mặt công cụ trước. Bắt đầu từ các mã trên, xác định phạm vi các công cụ theo những gì nhiệm vụ cần, và để mô hình điều khiển.

Tạo một tài khoản Scrapeless miễn phí để nhận một khóa API, và kiểm tra giá cả Scrapeless khi bạn lập kế hoạch cho một tác nhân định kỳ.

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

Q: Vercel AI SDK có cần khóa mô hình để tải công cụ MCP không?

Không. createMCPClient thực hiện bắt tay và client.tools() trả về các công cụ chỉ với khóa API Scrapeless được thiết lập, và phương thức execute của mỗi công cụ gọi nó trực tiếp. Một khóa nhà cung cấp mô hình chỉ được yêu cầu khi bạn phân tán các công cụ vào generateText hoặc streamText, vì đó là khi mô hình quyết định công cụ nào sẽ gọi.

Q: Tôi sử dụng import nào — createMCPClient hay experimental_createMCPClient?

Sử dụng createMCPClient từ @ai-sdk/mcp. Các hướng dẫn cũ nhập experimental_createMCPClient từ gói ai; client MCP đã chuyển vào gói riêng @ai-sdk/mcp, và việc xuất lại từ ai đã bị xóa. Nếu một ví dụ không thể giải quyết nhập, thường thì đây là lý do.

Q: Làm thế nào để tôi gọi một công cụ MCP mà không có mô hình?

Gọi await client.tools() và sau đó tools.<tên>.execute(args, { toolCallId, messages: [] }). Nó trả về một kết quả mà content là một danh sách các khối; đọc văn bản từ các khối văn bản. Đây là cách nhanh nhất để xác nhận kết nối và kiểm tra đầu ra của một công cụ trước khi kết nối với một mô hình.

Q: Làm thế nào để tôi kết nối với một máy chủ MCP cục bộ thay vào đó?
Chuyển một thể hiện transport cho stdio hoặc SSE thay vì đối tượng transport http, sau đó gọi client.tools() theo cách tương tự. Máy chủ MCP không có Scrapeless là một điểm cuối HTTP được lưu trữ, vì vậy hướng dẫn này sử dụng transport http.

H: Việc thu thập dữ liệu thông qua các công cụ có bị ràng buộc bởi quy tắc của mục tiêu không?

Có. Các công cụ lấy các trang công khai, và bạn vẫn có trách nhiệm tuân thủ các điều khoản của từng mục tiêu và các chỉ thị trong Giao thức loại trừ Robots. Giữ cho khối lượng ở mức giới hạn, dữ liệu công khai, và mô hình được giới hạn cho các công cụ mà nhiệm vụ thực sự cần.