企业官网建设流程全解析

• MCP 服务
• 浏览器控制
• AI 应用

本篇技术指南围绕 mcp-playwright（Playwright MCP Server）的 API 自动化能力展开，讲解如何借助playwright_get、playwright_post、playwright_put、playwright_patch、playwright_delete五个 MCP 工具，让 Claude Desktop、Cline、Cursor 等 AI 客户端直接调用你应用的 REST API。读完本文，你将掌握 Bearer Token、自定义请求头、Token 与 Headers 组合三种认证写法，能够以自然语言驱动 Agent 完成"创建资源 → 查询 → 更新 → 局部修改"的完整 CRUD 链路，并能从执行结果中读取状态码与响应体。

一、为什么需要用 MCP Server 做 API 自动化

mcp-playwright 本质上是一个 Model Context Protocol 服务器，除了浏览器自动化能力外，还内置了一套独立的 API 请求工具，使 LLM 可以不打开浏览器就能直接对接口发起 HTTP 请求。整套能力集中在仓库的 API 工具实现 中，共五个工具，全部以playwright_前缀命名：

这些工具由 src/tools.ts 中的createToolDefinitions()统一注册，属于 MCP 客户端可以直接调用的标准工具；在 src/tools/index.ts 的API_TOOLS常量中同样有对应列表。调用时无需启动浏览器，服务端会为请求单独创建 Playwright 的APIRequestContext（见 src/toolHandler.ts 中的ensureApiContext）。

二、五个 API 工具的完整参数说明

在动手写示例前，先明确每个工具的入参与返回值。以下参数说明与 Supported-Tools.mdx 中的定义保持一致，并补充了仓库源码中的细节。

2.1 通用入参

所有工具都支持以下三个参数（对应源码 BaseRequestArgs）：

• url(string, 必填)：目标接口地址。
• token(string, 可选)：Bearer Token。一旦提供，会被作为Authorization: Bearer <token>请求头发送。
• headers(object, 可选)：附加请求头。可用于 Basic 认证、API Key 等自定义认证方式；值的类型必须是字符串（非字符串会被校验拒绝，详见下文"请求头校验"）。

2.2 各工具差异

• playwright_get：仅有url/token/headers。返回statusCode。
• playwright_post/playwright_put/playwright_patch：在通用参数之外，还需要value(string, 必填)，即请求体数据。注意：这三个工具默认自动设置Content-Type: application/json请求头。返回statusCode与responseData（JSON 格式的响应数据）。
• playwright_delete：仅有url/token/headers。返回statusCode。

2.3 关于返回内容

从源码看，每个工具执行成功后会返回三段文本：请求目标（如GET request to <url>）、状态行（如Status: 200 OK）以及截断后的响应体。响应体最多返回前 1000 个字符，超出部分以...省略（见 requests.ts）。

三、认证示例：三种写法一次讲清

以下代码片段展示的是向 Agent 下达的自然语言指令（MCP 工具调用形式），可直接在 Claude Desktop、Cline、Cursor 中复用。

3.1 Bearer Token 认证

使用token参数即可完成 Bearer Token 认证：

// GET request with Bearer token await playwright_get({ url: 'https://api.example.com/protected-data', token: 'your-bearer-token-here' }); // POST request with Bearer token await playwright_post({ url: 'https://api.example.com/create', value: '{"name":"test"}', token: 'your-bearer-token-here' }); // DELETE request with Bearer token await playwright_delete({ url: 'https://api.example.com/resource/123', token: 'your-bearer-token-here' });

3.2 自定义 Headers 认证

使用headers参数可覆盖 Basic 认证、API Key 等非 Bearer 场景：

// Basic authentication await playwright_get({ url: 'https://api.example.com/data', headers: { 'Authorization': 'Basic dXNlcjpwYXNzd29yZA==', 'X-API-Version': '2.0' } }); // API Key authentication await playwright_post({ url: 'https://api.example.com/data', value: '{"data":"test"}', headers: { 'X-API-Key': 'your-api-key-here', 'X-Request-ID': 'unique-request-id' } }); // Custom authentication header await playwright_put({ url: 'https://api.example.com/update/123', value: '{"status":"active"}', headers: { 'X-Custom-Auth': 'custom-token', 'X-Client-ID': 'client-123' } });

3.3 组合 Token 与 Headers 的优先级规则

token和headers可以同时使用，但存在明确的优先级：

• 未在自定义 headers 中提供Authorization时：token生效，自动生成Authorization: Bearer <token>；
• 自定义 headers 中提供了Authorization时：自定义值覆盖token参数，token被忽略。

// Token takes precedence if no Authorization header in custom headers await playwright_get({ url: 'https://api.example.com/data', token: 'bearer-token', headers: { 'X-Custom-Header': 'value' } }); // Custom Authorization header overrides token parameter await playwright_get({ url: 'https://api.example.com/data', token: 'this-will-be-ignored', headers: { 'Authorization': 'Basic xyz123', // This takes precedence 'X-Custom-Header': 'value' } });

3.4 源码视角：请求头到底如何组装

这一优先级规则在源码中非常清晰。请求头由 buildHeaders 统一组装，顺序是：先写入Content-Type: application/json（仅 POST/PUT/PATCH），再写入Authorization: Bearer <token>（如果提供了token），最后用Object.assign(headers, customHeaders)将自定义头合并进来——由于后合并者覆盖先写入者，因此自定义Authorization必然覆盖token生成的同名头。源码还会在两者同时出现时输出一条警告：

Both token and Authorization header provided. Custom Authorization header will override token.

另外还有两点值得注意：

• 请求体解析：POST/PUT/PATCH 的value会先经 parseJsonSafely 尝试JSON.parse，解析成功则以对象形式发送；如果value以{或[开头但解析失败，会直接返回错误（如Failed to parse request body: ...）；若是普通字符串则原样发送。
• 请求头校验：所有工具执行前都会调用 validateHeaders 校验 headers 中每个值必须是字符串，否则返回形如Header '<name>' must be a string, got <type>的错误响应。

四、CRUD 操作完整示例

下面是一组针对公共测试接口https://api.restful-api.dev/objects的完整 CRUD 场景。你可以原样复制给 Agent 执行，它会依次完成"创建 → 按 ID 查询 → 整体更新 → 局部更新"四个步骤。

4.1 场景指令

// Basic POST request Perform POST operation for the URL https://api.restful-api.dev/objects with body { "name": "Apple MacBook Pro 16", "data": { "year": 2024, "price": 2499, "CPU model": "M4", "Hard disk size": "5 TB" } } And verify if the response has createdAt and id property and store the ID in a variable for future reference say variable productID // POST request with Bearer token authorization Perform POST operation for the URL https://api.restful-api.dev/objects with Bearer token "your-token-here" set in the headers { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-token-here' }, and body { "name": "Secure MacBook Pro", "data": { "year": 2024, "price": 2999, "CPU model": "M4 Pro", "Hard disk size": "8 TB", "security": "enhanced" } } Perform GET operation for the created ProductID using URL https://api.restful-api.dev/objects/productID and verify the response has properties like Id, name, data Perform PUT operation for the created ProductID using URL https://api.restful-api.dev/objects/productID with body { "name": "Apple MacBook Pro 16", "data": { "year": 2025, "price": 4099, "CPU model": "M5", "Hard disk size": "10 TB", "color": "Titanium" } } And verify if the response has createdAt and id property Perform PATCH operation for the created ProductID using URL https://api.restful-api.dev/objects/productID with body { "name": "Apple MacBook Pro 19 (Limited Edition)" } And verify if the response has updatedAt property with value Apple MacBook Pro 19 (Limited Edition)

4.2 场景要点拆解

• 第一条 POST 是无认证的基础创建：Agent 需校验响应中是否包含createdAt与id字段，并把返回的id存入productID变量，供后续步骤复用；
• 第二条 POST 演示"Bearer Token + 显式请求头"的写法，注意这里虽然同时写了Content-Type与Authorization，但Authorization实际也可省略——token参数会自动补上；
• GET 步骤将变量productID拼入 URL（即https://api.restful-api.dev/objects/{productID}），并校验响应是否包含id、name、data属性；
• PUT 步骤做整体替换更新，校验响应中仍存在createdAt与id；
• PATCH 步骤仅修改name字段，校验响应中的updatedAt值与新名称一致。

这套"变量传递 + 响应断言"的模式，正是 Agent 进行多步骤 API 链路验证的核心用法：每一步的输出（尤其是id）会作为后续请求的输入，形成可复用的端到端测试流。

五、查看执行结果：Request / Response / StatusCode

整个测试操作完成后，Agent 会把自动化过程的完整细节展示给你。

:::tip 你还可以从 Playwright MCP Server 的执行结果中直接查看每次请求的Request/Response/StatusCode明细，方便逐条核对每个接口调用的真实返回。

:::

从源码可以印证这一点：每个工具返回的成功响应都包含"请求目标 + 状态行 + 响应体（截断至 1000 字符）"三段文本（例如 GetRequestTool.execute），因此无论成功还是失败，你都能拿到可读的状态码与响应内容用于断言与排查。

六、请求上下文与错误处理机制

要理解这些工具为什么"开箱即用"，可以看一下底层设计：

• API 上下文按需创建：在 src/toolHandler.ts 中，当工具名命中API_TOOLS时，会调用ensureApiContext(args.url)——即request.newContext({ baseURL: url })创建一个独立的 Playwright APIRequestContext，随后注入ToolContext供工具执行（ToolContext 定义）。
• 统一异常兜底：所有 API 工具继承自抽象基类 ApiToolBase，其safeExecute方法先校验 API 上下文是否存在（不存在时返回API context not initialized错误），再包一层 try/catch，任何网络或执行异常都会转化为API operation failed: <message>的标准化错误响应。

这套机制保证：即使目标接口不可达、响应异常，Agent 也能拿到明确的错误信息，而不是卡死在一次调用上。

七、测试验证：请求构造的正确性有据可查

仓库为五个 API 工具提供了完整的单元测试，位于 requests.test.ts，覆盖以下关键断言，可作为你理解参数行为的权威参考：

• 无 token 的 GET：请求头为空对象{}；
• 带 token 的 GET：请求头精确为Authorization: Bearer test-token；
• 带自定义头的 GET：Authorization: Basic ...与自定义头原样透传；
• POST/PUT/PATCH 默认头：始终包含Content-Type: application/json，且value字符串会被解析为 JSON 对象后发送（data: { data: "test" }）；
• Token + 自定义 Authorization 同时出现：自定义头胜出，且产生警告日志；
• 非法请求头值（数字、null、undefined、数组）：返回Header '<name>' must be a string错误；
• JSON 解析失败但为合法字符串：以原始字符串发送，仅告警不中断；
• 缺少 API 上下文：返回API context not initialized。

这些测试同时验证了"请求失败会返回API operation failed"的错误路径，说明工具在异常场景下的行为也是确定性的。

八、当前限制与适用前提

:::warning 注意 当前版本的库还不够成熟，暂不支持 OAuth、Multi-form、Binary input 以及复杂的 API 请求（详见 Supported-Tools.mdx 中的警告）。如果你的业务接口涉及 OAuth2.0 授权码流、multipart/form-data 文件上传或二进制流，建议先确认服务端是否允许通过简单 JSON 交互，或考虑自行 fork 仓库补充能力（项目在 README.md 中也欢迎通过 PR 共建）。 :::

此外还需注意：

• 请求体必须能够表达为 JSON 字符串（value参数），接口需要接受application/json内容类型；
• token参数只负责自动生成 Bearer 头，OAuth 的 token 获取、刷新等完整流程需要由调用方（Agent 或你的脚本）事先完成；
• 响应体读取上限为 1000 字符的截断展示，超长响应建议结合接口分页或缩小查询范围。

九、小结：把 API 测试交给 Agent

通过 mcp-playwright 的五个 API 工具，你可以在 Claude Desktop、Cline、Cursor IDE 等任何支持 MCP 的客户端里，用一句句自然语言指令完成带认证的接口测试：Bearer Token 用token参数一行搞定，Basic/API Key 等自定义认证交给headers，两者组合时记住"自定义Authorization覆盖 token"的优先级即可。配合createdAt/id/updatedAt等响应断言与变量传递，一套完整的 CRUD 回归链路可以完全交由 Agent 驱动，而 Request/Response/StatusCode 明细则让你随时掌握每一次真实调用的结果。

• MCP 服务
• 浏览器控制
• AI 应用