使用说明

剧作家MCP HTTP服务器

一个独立的HTTP服务，包装官方 @playwright/mcp 包，通过HTTP端点提供浏览器自动化功能。此服务允许在无法进行基于STDIO的通信的无服务器环境中使用Playwright MCP。

🎯 现在作为视觉传感器技能得到了增强 -除了浏览器自动化之外，该服务器还提供智能、隐私感知和用户友好的网络交互功能。

特性

🌐 可流式HTTP传输 -实施2025 MCP远程连接标准
🔒 承载令牌身份验证 -生产使用需要安全身份验证
🚀 无服务器兼容 -适用于无服务器/云环境（Railway、Render、Fly.io、GCP cloud Run等）
🔄 MCP v0.1兼容 -完全实现模型上下文协议规范
📡 服务器发送事件（SSE） -双向流媒体支持实时通知
🎭 完整的编剧支持 -所有Playwright浏览器自动化工具可用
🐳 Docker就绪 -包含Dockerfile，便于容器化
⚡ 生产就绪 -健康检查、正常关机、错误处理
☁️ 实时部署 -使用HTTPS预部署到Google Cloud Run（见下文）

🆕 视觉传感器技能特征

🔍 快照优先逻辑 -令牌高效的可访问性树快照（不需要完整的DOM）
🛡️ PII模糊（代理安全） -从屏幕截图中自动编辑电子邮件、信用卡、电话号码和其他个人身份信息
👤 循环中的人类（引语） -检测MFA/登录墙并请求用户输入，而不是失败
🎯 高级技能 -基于技能的工具（例如。， perform_checkout)在内部处理复杂的工作流程

看视觉传感器_技能_实现.md 详细文档。

快速开始

先决条件

Node.js 18+（建议使用LTS）
npm或纱线

安装

# Clone the repository
git clone https://github.com/mcpmessenger/playwright-mcp.git
cd playwright-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

服务器将在端口上启动 8931 默认情况下。您可以访问：

服务信息: http://localhost:8931/
健康检查: http://localhost:8931/health
MCP端点: http://localhost:8931/mcp
- 发布 -发送JSON-RPC消息（客户端到服务器）
- 获取 -使用以下命令打开SSE连接（服务器到客户端） Accept: text/event-stream

🚀 现场制作实例

该服务已部署到Google Cloud Run并准备就绪：

服务URL: https://playwright-mcp-http-server-554655392699.us-central1.run.app
健康检查: https://playwright-mcp-http-server-554655392699.us-central1.run.app/health
MCP端点: https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp（仅限POST）

您可以立即使用实时实例，而无需部署自己的实例。看使用示例在......下面

发展

# Run in development mode with auto-reload
npm run dev

配置

配置是通过环境变量完成的。创建 .env 文件或设置环境变量：

变量	默认值	描述
`PORT`	`8931`	HTTP服务器端口
`PLAYWRIGHT_BROWSER`	`chromium`	浏览器类型（chromium、firefox、webkit）
`PLAYWRIGHT_HEADLESS`	`true`	在无头模式下运行浏览器
`LOG_LEVEL`	`info`	日志记录级别（错误、警告、信息、调试）
`MAX_SESSIONS`	（无限制）	最大并发浏览器会话数
`SESSION_TIMEOUT`	（无）	会话超时（秒）
`CORS_ORIGIN`	`*`	CORS允许的来源
`AUTH_TOKEN`	（无）	用于身份验证的承载令牌（生产所需）
`AUTH_SECRET_NAME`	（无）	GCP密钥管理器密钥名称（替代AUTH_TOKEN）
`GCP_PROJECT_ID`	（自动）	GCP项目ID（如果使用AUTH_SECRET_NAME，则需要）

看 .env.example 对于模板。

认证

⚠️ 重要：对于生产部署，需要进行身份验证以符合2025 MCP Streamable HTTP标准。

设置身份验证

直接令牌 （开发/测试）：

export AUTH_TOKEN="your-secure-token-here"

GCP秘密经理 （生产-推荐）：

export AUTH_SECRET_NAME="playwright-mcp-auth-token"
export GCP_PROJECT_ID="your-project-id"

看注册_CONFIG.md 有关详细的身份验证设置说明。

使用身份验证

所有请求 /mcp 需要不记名代币：

curl -X POST http://localhost:8931/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{...}'

API文档

POST/mcp

客户端到服务器消息的主MCP协议端点。接受JSON-RPC 2.0消息。

认证：必填（不记名代币）

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "browser_navigate",
    "arguments": {
      "url": "https://example.com"
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Navigation completed"
      }
    ],
    "isError": false
  }
}

GET/健康

健康检查端点。返回服务状态。

答复：

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2024-12-01T12:00:00.000Z"
}

得到/

服务信息端点。

答复：

{
  "name": "Playwright MCP HTTP Server",
  "version": "1.0.0",
  "protocol": "MCP v0.1",
  "endpoints": {
    "mcp": "/mcp",
    "health": "/health"
  }
}

支持的MCP方法

服务器支持所有标准MCP方法：

initialize -初始化MCP连接
initialized -确认初始化
tools/list -列出可用的Playwright工具
tools/call -调用Playwright工具

可用工具

标准编剧工具

所有工具来自 @playwright/mcp 支持：

browser_navigate -导航到URL
browser_snapshot -获取可访问性快照（使用可访问性树提高令牌效率）
browser_take_screenshot -捕获屏幕截图（自动编辑PII）
browser_click -单击元素
browser_type -键入文本
browser_fill_form -填写表单字段
browser_evaluate -执行JavaScript
browser_wait_for -等待条件
browser_close -关闭浏览器/页面

自定义视觉传感器技能工具

get_accessibility_snapshot -令牌高效可访问性树快照（快照优先方法）
- 仅返回交互式元素
- 与完整DOM相比，减少令牌使用
- 针对LLM消耗进行了优化
perform_checkout -高级结账技能
- 协调完整的结账流程
- 在内部处理导航、表单填写、错误处理和重试
- 仅返回最终确认
fill_form_skill -智能表单填写
- 自动检测并填写表单字段
- 在内部使用browser_fill_form进行智能字段检测

备注：屏幕截图来自 browser_take_screenshot 在返回之前自动对PII进行编辑。登录墙和MFA要求通过通知自动触发诱导请求。

有关详细的刀具参数，请参阅剧作家MCP文档和视觉传感器_技能_实现.md.

使用服务器

从本地开始 npm install，构建(npm run build)，然后运行 npm start （或使用 npm run dev 用于开发过程中的自动重新加载）。
呼叫 /, /health，或 /mcp 通过curl/邮差/剧作家MCP客户端；这 /mcp 端点接受JSON-RPC POST请求（见下面的示例）。
通过编辑调整行为 .env 或设置环境变量，如 PORT, PLAYWRIGHT_BROWSER，以及 PLAYWRIGHT_HEADLESS.
或者，将服务容器化 docker build -t playwright-mcp-http-server . 和 docker run -p 8931:8931 ... 为了实现一致的部署。

视觉传感器技能能力

服务器自动执行以下操作：

✅ 更正个人身份信息 来自屏幕截图（电子邮件、信用卡、电话号码、SSN）
✅ 检测登录墙 并通过通知发送启发请求
✅ 提供令牌高效快照 通过可访问性树
✅ 提供高级技能 适用于复杂的工作流程

看视觉传感器_技能_实现.md 有关这些功能的详细文档。

更新GitHub存储库

在编辑之前拉取最新更改： git pull --rebase origin main.
使用 git status 要查看触摸过的文件，请使用 git add <files> 并提交描述性消息。
用推送你的树枝 git push origin HEAD 如果更改需要审查，则打开拉取请求。

示例用法

使用curl

# List available tools
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Navigate to a page
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "browser_navigate",
      "arguments": {
        "url": "https://example.com"
      }
    }
  }'

# Take a screenshot (PII automatically redacted)
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "browser_take_screenshot",
      "arguments": {
        "fullPage": true
      }
    }
  }'

# Get accessibility snapshot (token-efficient)
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_accessibility_snapshot",
      "arguments": {
        "interestingOnly": true
      }
    }
  }'

# Use high-level checkout skill
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "perform_checkout",
      "arguments": {
        "cartData": {
          "items": [{"name": "Product", "quantity": 1}],
          "shippingAddress": {"name": "...", "address": "..."},
          "paymentMethod": {"type": "card", "cardNumber": "..."}
        }
      }
    }
  }'

使用JavaScript/TypeScript

// Use the live production instance or replace with your own deployment URL
const MCP_SERVER_URL = 'https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp';
const AUTH_TOKEN = 'your-token-here'; // Required for production

// Open SSE connection for server-to-client notifications
const eventSource = new EventSource(MCP_SERVER_URL, {
  headers: {
    'Authorization': `Bearer ${AUTH_TOKEN}`
  }
});

eventSource.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  console.log('Server notification:', notification);
};

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
};

// Send JSON-RPC requests (client-to-server)
async function callPlaywrightMCP(method: string, params?: any) {
  const response = await fetch(MCP_SERVER_URL, {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AUTH_TOKEN}`
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method,
      params,
    }),
  });
  return response.json();
}

// List tools
const tools = await callPlaywrightMCP('tools/list');

// Navigate
await callPlaywrightMCP('tools/call', {
  name: 'browser_navigate',
  arguments: { url: 'https://example.com' },
});

// Take screenshot
const screenshot = await callPlaywrightMCP('tools/call', {
  name: 'browser_take_screenshot',
  arguments: { fullPage: true },
});

备注：对于生产，始终使用HTTPS并在 Authorization 头球

GET/mcp（流式HTTP）

为服务器到客户端的邮件打开服务器发送事件（SSE）连接。这实现了Streamable HTTP传输协议。

认证：必填（不记名代币）
标头: Accept: text/event-stream

例子：

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer your-token-here" \
     http://localhost:8931/mcp

连接将：

发送连接确认
转发来自剧作家流程的MCP通知
定期发送ping消息以保持连接畅通
当客户端断开连接时，优雅地关闭

备注:

发布 /mcp 用于发送JSON-RPC请求（客户端到服务器）
获取 /mcp 用于通过SSE（服务器到客户端）接收通知
在以下情况下，两个端点都需要身份验证 AUTH_TOKEN 或 AUTH_SECRET_NAME 已设置

部署

铁路

创建新的铁路项目
连接你的Git仓库
Railway将自动检测Node.js并使用 npm start
如果需要，设置环境变量
部署！

该服务将使用铁路 $PORT 环境变量自动。

渲染

在Render上创建新的Web服务
连接你的Git仓库
构建命令： npm install && npm run build
启动命令： npm start
如果需要，设置环境变量
部署！

谷歌云平台（云运行）

看 DEPLOY_GCP.md 详细说明。

通过身份验证快速部署：

# Set your project ID
export GCP_PROJECT_ID="your-project-id"

# Option 1: Deploy with bearer token (recommended)
export AUTH_MODE=token
export AUTH_TOKEN=$(openssl rand -hex 32)  # Generate secure token
chmod +x deploy-gcp.sh && ./deploy-gcp.sh

# Option 2: Deploy with Secret Manager (best for production)
export AUTH_MODE=secret
export AUTH_SECRET_NAME="playwright-mcp-auth-token"
chmod +x deploy-gcp.sh && ./deploy-gcp.sh

# Option 3: Deploy without authentication (development only - NOT recommended)
export AUTH_MODE=public
chmod +x deploy-gcp.sh && ./deploy-gcp.sh

Windows PowerShell：

$env:GCP_PROJECT_ID = "your-project-id"
$env:AUTH_MODE = "token"
$env:AUTH_TOKEN = [System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
.\deploy-gcp.ps1 -ProjectId "your-project-id"

⚠️ 安全说明：始终使用身份验证(AUTH_MODE=token 或 AUTH_MODE=secret)用于生产部署。公众访问(AUTH_MODE=public)只能用于当地发展。

或手动：

PROJECT_ID="your-project-id"
IMAGE="gcr.io/${PROJECT_ID}/playwright-mcp-http-server"

docker build -t $IMAGE .
docker push $IMAGE

gcloud run deploy playwright-mcp-http-server \
    --image $IMAGE \
    --region us-central1 \
    --platform managed \
    --allow-unauthenticated \
    --port 8931 \
    --memory 2Gi \
    --cpu 2

Fly.io

安装Fly CLI： curl -L https://fly.io/install.sh | sh
登录： fly auth login
启动应用程序： fly launch
部署： fly deploy

码头工人

# Build the image
docker build -t playwright-mcp-http-server .

# Run the container
docker run -p 8931:8931 playwright-mcp-http-server

# With environment variables
docker run -p 8931:8931 \
  -e PORT=8931 \
  -e PLAYWRIGHT_HEADLESS=true \
  playwright-mcp-http-server

Docker Compose

version: '3.8'
services:
  playwright-mcp:
    build: .
    ports:
      - "8931:8931"
    environment:
      - PORT=8931
      - PLAYWRIGHT_HEADLESS=true
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:8931/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

流式HTTP（2025 MCP标准）

此服务实现 流式HTTP 传输协议，即用于远程连接的2025 MCP标准。流式HTTP要求：

✅ 超文本传输安全协议 -Cloud Run自动提供
✅ 承载令牌身份验证 -生产使用所需
✅ 服务器发送事件（SSE） -用于服务器到客户端流式传输
✅ POST端点 -用于客户端到服务器JSON-RPC消息

注册表配置

要在MCP注册表中注册此服务，请使用以下配置：

{
  "name": "playwright-service",
  "transport": "streamable-http",
  "url": "https://your-service-url.run.app/mcp",
  "auth": {
    "type": "bearer",
    "token": "your-secure-token"
  }
}

看注册_CONFIG.md 有关完整的注册表设置说明。

建筑

该服务通过以下方式工作：

HTTP服务器 （Express）接收JSON-RPC请求和SSE连接
身份验证中间件 验证承载令牌
MCP处理器 处理请求并将其路由到Playwright
编剧流程经理 生成 @playwright/mcp 作为一个孩子的过程
STDIO通信 通过stdin/stdout处理JSON-RPC消息
SSE流媒体 将服务器通知转发给连接的客户端
响应已格式化并通过HTTP返回

这种架构允许Playwright进程独立运行，同时可以通过HTTP/HTTPS访问，并完全支持Streamable HTTP。

故障排除

服务无法启动

检查是否安装了Node.js 18+： node --version
验证是否安装了依赖项： npm install
检查日志中的错误消息

找不到Playwright浏览器

浏览器将在首次运行时自动下载
对于Docker，确保安装了系统依赖项（包含在Dockerfile中）
检查浏览器下载的网络连接

内存使用率高

考虑设置 MAX_SESSIONS 限制并发会话
确保 browser_close 在会话结束时调用
监控长时间运行的进程中的内存泄漏

超时错误

如果操作时间超过30秒，则增加请求超时
检查目标URL的网络连接
验证Playwright进程是否崩溃

发展

项目结构

playwright-mcp-http-server/
├── src/
│   ├── server.ts              # HTTP server setup
│   ├── mcp-handler.ts         # MCP protocol handler
│   ├── playwright-process.ts  # Playwright process management
│   ├── config.ts              # Configuration
│   └── types/
│       └── mcp.ts             # TypeScript types
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── Dockerfile
└── README.md

建筑

npm run build

运行测试

注：测试尚未实施，但计划在未来的版本中进行

许可证

麻省理工学院

参考文献

支持

有关问题和疑问，请在存储库上打开一个问题。

使用说明

剧作家MCP HTTP服务器

特性

🆕 视觉传感器技能特征

快速开始

先决条件

安装

🚀 现场制作实例

发展

配置

认证

设置身份验证

使用身份验证

API文档

POST/mcp

GET/健康

得到/

支持的MCP方法

可用工具

标准编剧工具

自定义视觉传感器技能工具

使用服务器

视觉传感器技能能力

更新GitHub存储库

示例用法

使用curl

使用JavaScript/TypeScript

GET/mcp（流式HTTP）

部署

铁路

渲染

谷歌云平台（云运行）

Fly.io

码头工人

Docker Compose

流式HTTP（2025 MCP标准）

注册表配置

建筑

故障排除

服务无法启动

找不到Playwright浏览器

内存使用率高

超时错误

发展

项目结构

建筑

运行测试

许可证

参考文献

支持

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

搜索引擎集成服务器