使用说明

E2E MCP服务器

日语版README在这里 / 日语自述

MCP（模型上下文协议）服务器，用于E2E测试，集成开发服务器管理和Playwright自动化。

非常适合像Claude Code这样的AI代理来自动化浏览器测试工作流程！

概述

E2E MCP Server解决了AI代理（Claude Code、ChatGPT、Gemini等）执行E2E测试时服务器管理的复杂性。与人工智能代理必须自己管理开发服务器状态的传统Playwright MCP实现不同，该服务器将服务器进程生命周期管理委托给MCP层，允许人工智能代理仅专注于测试逻辑。

服务器执行用户提供的服务器启动命令（具有动态端口分配和日志管理），并将返回的URL和日志路径作为会话信息进行管理。所有Playwright操作都作为MCP工具公开，当发生错误时，服务器日志和屏幕截图会自动收集并提供给AI代理。

关键能力

自动化E2E会话管理：从开发服务器启动到测试执行，再到通过MCP工具调用关闭服务器，实现完全自动化
剧作家作为MCP工具：提供作为MCP工具的主要Playwright功能，实现与现有Playwright MCP相同的可操作性
自动调试信息收集：自动收集服务器日志、屏幕截图和结构化错误详细信息，以支持AI代理的根本原因分析
多客户端支持：可通过标准MCP协议从多个AI客户端（Claude Code、ChatGPT、Gemini）访问

设计理念

服务器命令不可知：用户提供的服务器启动命令（bash、Node.js、Python等），带有JSON响应接口
会话隔离：一个会话=一个开发服务器+一个浏览器实例，防止状态污染
AI优先错误处理：结构化错误，带有AI代理自我修复功能的屏幕截图和日志
云就绪架构：适用于Cloud Run和容器环境的无状态设计

特性

集成服务器管理：启动、监视和自动关闭开发服务器
剧作家自动化：通过MCP工具执行浏览器自动化任务
AI代理友好：专为人工智能驱动的E2E测试工作流程而设计
错误处理：故障时自动截图和日志收集
会话管理：具有自动清理功能的隔离浏览器会话
云就绪：部署到Google Cloud Run或任何容器平台

需求

Node.js>=20.0.0
开发服务器启动命令（Node.js、Bash等）

安装

使用npm全局安装：

npm install -g e2e-mcp-server

或者在项目中作为开发依赖项安装：

npm install --save-dev e2e-mcp-server

快速开始

添加到您的Claude代码配置中(.mcp.json):

{
  "mcpServers": {
    "e2e-mcp": {
      "command": "npx",
      "args": ["-y", "e2e-mcp-server"]
    }
  }
}

重新启动Claude代码
MCP服务器将自动提供10个强大的E2E测试工具！

用法

作为MCP服务器（推荐：stdio模式）

在Claude代码中配置 .mcp.json:

{
  "mcpServers": {
    "e2e-mcp": {
      "command": "npx",
      "args": ["-y", "e2e-mcp-server"]
    }
  }
}

Claude Code将在需要时自动启动MCP服务器。无需手动启动服务器！

替代方案：HTTP模式（用于远程服务器）

启动HTTP服务器：

npm start

在您的 .mcp.json:

{
  "mcpServers": {
    "e2e-mcp-remote": {
      "type": "http",
      "url": "http://localhost:3000/message",
      "transport": {
        "type": "streamable-http"
      }
    }
  }
}

发展：

npm run dev

测试服务器（交互式）

使用附带的测试客户端验证服务器是否正常工作：

# Start the server in one terminal
npm start

# In another terminal, run the test client
npx tsx examples/test-client.ts

# Or run automated demo
npx tsx examples/test-client.ts --demo

看示例/TEST-CLIENT.md 详细用法。

环境变量

变量	描述	默认值
`PORT`	服务器端口	`3000`
`NODE_ENV`	环境（开发/生产）	`development`
`LOG_LEVEL`	日志级别（调试/信息/警告/错误）	`info`
`SESSION_TIMEOUT`	会话超时（毫秒）	`600000` （10分钟）
`SERVER_COMMAND_PATH`	允许的服务器启动命令路径（安全）	-
`ALLOWED_HOSTS`	逗号分隔的允许导航主机	-

MCP工具

会话管理

startSession

启动开发服务器并创建浏览器会话。

{
  "name": "startSession",
  "arguments": {
    "commandPath": "/path/to/start-server.sh",
    "args": ["--port", "3001"]
  }
}

答复：

{
  "sessionId": "uuid",
  "url": "http://localhost:3001",
  "port": 3001,
  "pid": 12345,
  "logs": {
    "stdout": "/tmp/server-stdout.log",
    "stderr": "/tmp/server-stderr.log",
    "combined": "/tmp/server-combined.log"
  }
}

stopSession

停止开发服务器并关闭浏览器会话。

{
  "name": "stopSession",
  "arguments": {
    "sessionId": "uuid",
    "commandPath": "/path/to/stop-server.sh",
    "args": []
  }
}

getSessionStatus

获取开发服务器的状态。

{
  "name": "getSessionStatus",
  "arguments": {
    "sessionId": "uuid",
    "commandPath": "/path/to/status-server.sh",
    "args": []
  }
}

剧作家操作

点击

单击页面上的元素。

{
  "name": "click",
  "arguments": {
    "sessionId": "uuid",
    "selector": "#login-button",
    "timeout": 30000
  }
}

填充

填写文本输入字段。

{
  "name": "fill",
  "arguments": {
    "sessionId": "uuid",
    "selector": "#username",
    "value": "testuser"
  }
}

截图

捕获当前页面的屏幕截图。

{
  "name": "screenshot",
  "arguments": {
    "sessionId": "uuid",
    "fullPage": false
  }
}

答复：

{
  "data": "base64-encoded-image-data",
  "path": "/tmp/screenshot-123.png"
}

评估

在页面上下文中执行JavaScript。

{
  "name": "evaluate",
  "arguments": {
    "sessionId": "uuid",
    "script": "document.title"
  }
}

获取内容

获取当前页面的HTML内容。

{
  "name": "getContent",
  "arguments": {
    "sessionId": "uuid"
  }
}

日志管理

readLogs

从会话中读取服务器日志。

{
  "name": "readLogs",
  "arguments": {
    "sessionId": "uuid",
    "logType": "combined",
    "tail": 100
  }
}

服务器启动命令界面

您的开发服务器启动命令应将JSON输出到stdout，格式如下：

启动命令(`--start`)

{
  "status": "ready",
  "url": "http://localhost:3001",
  "port": 3001,
  "pid": 12345,
  "startedAt": "2025-01-01T00:00:00.000Z",
  "logs": {
    "stdout": "/path/to/stdout.log",
    "stderr": "/path/to/stderr.log",
    "combined": "/path/to/combined.log"
  },
  "message": "Server started successfully"
}

状态命令(`--status`)

{
  "status": "running",
  "url": "http://localhost:3001",
  "uptime": 12345,
  "healthy": true
}

关机命令(`--shutdown`)

{
  "status": "stopped",
  "message": "Server stopped successfully"
}

示例实现（Node.js）

看示例/server-command.cjs 以获取完整的参考实现。

发展

克隆和设置

git clone https://github.com/hummer98/e2e-mcp-server.git
cd e2e-mcp-server
npm install
npm run build

运行测试

npm test

运行覆盖率测试

npm run test:coverage

棉绒

npm run lint
npm run lint:fix

地方发展与守望模式

npm run dev

部署

谷歌云运行

构建Docker镜像：

docker build -t gcr.io/PROJECT_ID/e2e-mcp-server .

推送到容器注册表：

docker push gcr.io/PROJECT_ID/e2e-mcp-server

部署到云运行：

gcloud run deploy e2e-mcp-server \
  --image gcr.io/PROJECT_ID/e2e-mcp-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 2Gi \
  --cpu 2 \
  --timeout 3600s

或者使用Cloud Build：

gcloud builds submit --config cloudbuild.yaml

生产环境变量

在Cloud Run配置中设置这些：

NODE_ENV=production
LOG_LEVEL=info
SESSION_TIMEOUT=600000
SERVER_COMMAND_PATH=/app/scripts/start-server.sh
ALLOWED_HOSTS=localhost,*.yourdomain.com

安全考虑

命令注入：设置 SERVER_COMMAND_PATH 将允许的服务器命令列入白名单
SSRF保护：设置 ALLOWED_HOSTS 限制导航目标
速率限制：内置速率限制可防止DoS攻击
认证：计划为生产部署提供OAuth 2.1支持

建筑

┌─────────────────┐
│  AI Agent       │
│  (Claude Code)  │
└────────┬────────┘
         │ MCP Protocol (stdio or HTTP)
         ↓
┌─────────────────┐
│  E2E MCP Server │
│  ┌───────────┐  │
│  │ Session   │  │
│  │ Manager   │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────┴─────┐  │
│  │Playwright │  │
│  │Browser    │  │
│  └───────────┘  │
└────────┬────────┘
         │ executes
         ↓
┌─────────────────┐
│  Dev Server     │
│  (Next.js, etc) │
└─────────────────┘

可用工具

MCP服务器提供了10个强大的工具：

startSession -启动开发服务器并创建浏览器会话
stopSession -停止开发服务器并关闭浏览器
getSessionStatus -获取服务器状态
导航 -导航到URL
点击 -点击元素
填充 -填写表单输入
截图 -截图
评估 -执行JavaScript
获取内容 -获取页面HTML
readLogs -读取服务器日志

发布到npm

要将此包发布到npm：

# Build the package
npm run build

# Login to npm (if not already)
npm login

# Publish (first time or updates)
npm publish

# Or publish with public access for scoped packages
npm publish --access public

发布前，请确保：

更新版本 package.json
更新 CHANGELOG.md
将存储库URL更新到实际存储库
使用以下工具在本地测试包 npm pack

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

支持

问题：https://github.com/hummer98/e2e-mcp-server/issues
文档：https://github.com/hummer98/e2e-mcp-server#readme