项目简介

PlayWord 是一个利用AI简化Web测试自动化的工具。该仓库包含了PlayWord项目的核心库、命令行工具以及一个基于Model Context Protocol (MCP) 实现的服务器模块。

PlayWord MCP 服务器 ('@playword/mcp') 是 PlayWord 的后端服务，专门设计用于接收遵循 MCP 标准的请求，并通过 PlayWord 核心库执行网页自动化任务。它通过 JSON-RPC 协议与 LLM 客户端通信，将自然语言指令转换为具体的浏览器操作（如点击、输入、导航等）和断言。

主要功能点

托管 PlayWord 功能: 将 PlayWord 的网页自动化能力（基于 Playwright）通过 MCP 协议暴露给 LLM 客户端。
工具注册与执行: 注册并执行 MCP 工具，例如 'CallPlayWord' 工具用于接收自然语言指令并调用 PlayWord 核心功能，'ClosePlayWord' 工具用于关闭浏览器实例。
浏览器实例管理: 管理 Playwright 浏览器上下文和页面实例，确保自动化操作的执行环境。
会话管理: 为 MCP 客户端提供独立的自动化会话。
能力声明: 向客户端声明其提供的工具能力。
支持 Stdio 传输: 使用标准的输入输出流进行通信，易于与多种 MCP 客户端集成。

安装步骤

确保已安装 Node.js: PlayWord 需要 Node.js 版本 >= 20。

安装 PlayWord 库: PlayWord MCP 服务器是 PlayWord 项目的一部分。通过 npm 或 yarn 安装：

npm install @playword/mcp @playword/core playwright-core dotenv @modelcontextprotocol/sdk yargs -g
# 或者使用 yarn
# yarn global add @playword/mcp @playword/core playwright-core dotenv @modelcontextprotocol/sdk yargs

注意: 安装 'playwright-core' 而非完整的 'playwright'，并在使用前确保已安装对应的浏览器二进制文件（例如 'npx playwright install chromium'）。'dotenv' 用于加载环境变量，'@modelcontextprotocol/sdk' 是 MCP SDK，'yargs' 用于命令行参数解析。

服务器配置 (供 MCP 客户端参考)

MCP 服务器通常由 MCP 客户端根据配置启动。以下是一个典型的 MCP 客户端用于启动 PlayWord MCP 服务器的 JSON 配置示例：

{
  "mcpServers": {
    "playword": {
      "command": "npx",
      "args": [
        "@playword/mcp",
        "--browser", "chromium",  // 指定使用的浏览器类型 (可选，默认为 chrome)
        "--headless", "false",     // 是否在无头模式下运行浏览器 (可选，默认为 false，即有头模式)
        "--ai-options", "openAIApiKey=YOUR_OPENAI_API_KEY", // 配置AI服务，可多次指定，格式为 key=value
        "--ai-options", "model=gpt-4o-mini" // 例如：指定OpenAI API Key 和 模型
        // 其他可选的AI配置参数，如 googleApiKey=<YOUR_GOOGLE_API_KEY>, anthropicApiKey=<YOUR_ANTHROPIC_API_KEY>, voyageAIApiKey=<YOUR_VOYAGEAI_API_KEY>, baseURL=<CUSTOM_BASE_URL>
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY" // 或者通过环境变量传递 AI API Key
      }
    }
  }
}

参数说明:

'command': 启动 PlayWord MCP 服务器的可执行文件路径或命令，通常使用 'npx' 来运行全局或项目依赖的 '@playword/mcp' 命令。
'args': 传递给 'command' 的参数数组。
- '@playword/mcp': 指定要执行的 PlayWord MCP 服务器模块。
- '--browser <type>': 指定 Playwright 使用的浏览器类型 ('chrome', 'chromium', 'firefox', 'msedge', 'webkit')。
- '--headless <boolean>': 控制浏览器是否在无头模式下运行。
- '--ai-options <key=value>': 配置 PlayWord 内部使用的 AI 模型参数，如 API 密钥、模型名称、Base URL 等。可以重复此参数来传递多个配置项。
'env': 一个键值对对象，用于设置启动 PlayWord MCP 服务器进程时的环境变量，常用于传递敏感信息如 API Key。

基本使用方法

PlayWord MCP 服务器设计为由兼容 MCP 协议的 LLM 客户端（如 VS Code 中的 MCP 客户端扩展）启动和交互。用户通常不需要直接从命令行启动服务器。

一旦 MCP 客户端配置并启动 PlayWord MCP 服务器，LLM 客户端即可通过 MCP 协议调用服务器提供的工具。

例如 (通过MCP客户端调用工具的逻辑描述):

LLM 客户端发送一个 'tools/call' 请求给 PlayWord MCP 服务器，指定工具名称为 'CallPlayWord'，并传递参数 '{"input": "Navigate to https://www.google.com"}'。
PlayWord MCP 服务器接收请求，找到 'CallPlayWord' 工具，并执行其 'handle' 函数。
'CallPlayWord' 工具调用 PlayWord 核心的 'playword.say("Navigate to https://www.google.com")' 方法。
PlayWord 核心库使用 Playwright 控制浏览器导航到 Google 网站。
操作完成后，'playword.say' 返回结果。
'CallPlayWord' 工具将结果封装成 MCP 工具响应格式，发送回 LLM 客户端。
LLM 客户端接收响应，并可能根据结果继续与用户交互或调用其他工具。

MCP 客户端负责处理与用户的交互（如接收自然语言指令）和与 MCP 服务器的通信（构建并发送 JSON-RPC 请求），而 PlayWord MCP 服务器则负责执行实际的网页自动化逻辑。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供 MCP 客户端参考)

基本使用方法

信息