MCP 让客户端通过统一协议发现并调用工具。FlashData 通过远程 Streamable HTTP 端点提供 Google Search 和 YouTube 数据工具。本教程连接 Node.js 客户端,列出可用工具定义,并且仅在你显式启用时执行搜索。
这是协议集成指南。如果您希望将普通 Python 函数注册到智能体框架中,请使用 为 AI 智能体添加 Google 和 YouTube 搜索工具.
安装 SDK,并将 API 密钥保存在服务器上
使用 Node.js 22 或更高版本。示例使用的是 FlashData 文档中已验证的官方 MCP SDK 版本。请将 API 密钥保存在服务器环境中,不要嵌入浏览器构建产物、公开代码仓库或 MCP 端点 URL 中。
mkdir flashdata-mcp-client
cd flashdata-mcp-client
npm init -y
npm install @modelcontextprotocol/[email protected]
export FLASHDATA_API_KEY='your-api-key'
端点为 https://data.flashdata.dev/mcp。身份验证使用 X-API-Key 请求头。你无需启动本地 FlashData 服务器。此连接使用 Streamable HTTP,而不是 stdio 命令。
连接、查看工具,并按需执行一次搜索
将此文件保存为 mcp-search.mjs。默认情况下,它调用 listTools() ,并打印可用工具名称和 Google Search 的输入结构。发现工具不会执行付费数据查询。
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error("Set FLASHDATA_API_KEY first.");
const client = new Client({ name: "search-example", version: "1.0.0" });
try {
await client.connect(new StreamableHTTPClientTransport(
new URL("https://data.flashdata.dev/mcp"),
{ requestInit: { headers: { "X-API-Key": key } } },
));
const { tools } = await client.listTools();
console.log("Available tools:", tools.map(tool => tool.name));
const search = tools.find(tool => tool.name === "google_search");
if (!search) throw new Error("google_search is not available to this client.");
console.log("Search input schema:", JSON.stringify(search.inputSchema, null, 2));
if (process.env.RUN_SEARCH === "1") {
const result = await client.callTool({
name: "google_search",
arguments: { query: process.env.SEARCH_QUERY ?? "MCP protocol",
gl: "us", hl: "en", num: 3, page: 1, mode: "realtime" },
});
if (result.isError) {
console.error(JSON.stringify(result, null, 2));
process.exitCode = 1;
} else {
console.log(JSON.stringify(result, null, 2));
}
} else {
console.log("Discovery complete. Set RUN_SEARCH=1 to submit a billable query.");
}
} finally {
await client.close();
}
node mcp-search.mjs
# Run only when you are ready to submit a search using account Credits:
RUN_SEARCH=1 SEARCH_QUERY='MCP protocol' node mcp-search.mjs
MCP 参数采用扁平结构
REST 和 MCP 以不同的请求结构描述同一个搜索任务。REST 查询将国家和语言控制项放在 params。MCP 工具接收 gl, hl, num 和 page 直接放在 arguments;不要发送 REST 的 params 对象传给 MCP 工具。不支持的字段会被拒绝。
对于 YouTube,请先检查工具 schema,再构造调用。转录文本工具接受 video_id, language 和 auto; auto 选择现有的自动字幕轨道或上传者提供的字幕轨道。它不会为没有字幕的视频生成字幕。
处理异步任务和大型结果
使用 mode: "async" ,用于获取任务回执而非实时结果。保留返回的任务 ID,并通过以下字段传入: job_id 设为 get_job。已完成的任务在以下字段中包含原始响应: output;结果在完成后保留 24 小时。读取任务不会再次提交查询。
大型结果可能以 JSON 文本块返回,其中包含 result_id 和 next_offset。调用 get_result ,使用同一个密钥,并持续使用返回的偏移量,直到 next_offset 为 null。解析前请按顺序拼接分块。限额按 UTF-16 代码单元计算,而不是按行数或字节数计算。结果缓存有效期为 10 分钟,每个密钥最多保留四个大型结果,也可能提前逐出结果。
要将视频或音频交付到您的存储,请调用 youtube_download,指定 storage 目标,并使用授予 youtube_download 权限的 API Key。保存返回的任务 ID,然后用 get_job 查询状态。对于文件型 Bulk 处理,请使用 Bulk 处理 API.
根据实际情况处理失败
HTTP 交互成功,仍可能返回包含以下字段的工具结果: isError: true;请检查该字段。工具错误会保留有用的上游状态和请求标识。再次尝试前,请修正无效参数、权限或积分余额问题。
超时或连接丢失并不能证明查询未执行。对于 query_outcome_unknown,重新提交前请检查请求历史记录。此客户端有意不对付费工具调用进行自动循环重试。上游大型响应的大小上限为 4 MiB,因此请先使用较小的结果数量。
查询沿用您现有的积分定价,MCP 不额外收费。请阅读 MCP 参考文档, MCP 概览 和 定价 ,然后再为生产客户端选择并发数或批量请求大小。