剧作家MCP测试编排员
此存储库包含一个测试编排系统，该系统使用Playwright的模型上下文协议（MCP）工具和LLM对浏览器执行自然语言测试步骤。
亮点
- 自然语言→ 通过LLM执行浏览器操作
- 具有丰富快照的持久MCP连接（SSE+HTTP JSON-RPC）
- 交互式和自动化测试流程
- 干净的Python项目模板（格式化、linting、测试）
______________________________________________________________________
快速开始
# Create and activate a virtual environment (optional)
python -m venv venv
source venv/bin/activate # macOS/Linux; on Windows: .\venv\Scripts\activate
# Install dev tools
pip3 install -r requirements.txt
# Install orchestrator/client dependencies
pip3 install -r mcp-client/requirements.txt设置环境变量：
export OPENAI_API_KEY=your_key_here
export MCP_SERVER_URL=http://localhost:8000 # default验证一切正常：
python mcp-client/test_orchestrator.py test-connection______________________________________________________________________
用法（测试编排器CLI）
所有命令都从repo根运行。
# Important quick run (from mcp-client):
# python test_orchestrator.py --llm-model gpt-4o run --test-file tests/sample.txt
# Verify connections (MCP + LLM)
python mcp-client/test_orchestrator.py test-connection
# Automated run (two quoted args)
python mcp-client/test_orchestrator.py run "Verify site loads" "Navigate to example.com"
# From a test file (repo root)
python mcp-client/test_orchestrator.py --llm-model gpt-4o run -f mcp-client/tests/sample.txt
# Interactive session
python mcp-client/test_orchestrator.py interactive "Explore" "Open homepage"
# Single step
python mcp-client/test_orchestrator.py single-step "Navigate to github.com and click Sign in"常见选项：
--mcp-server-url（默认值http://localhost:8000)--openai-api-key--llm-model（默认值gpt-4例如。，gpt-4o)--max-steps（默认值50），--step-timeout（默认值30）-v/--verbose
登录中：
- 添加
--report-file mcp-client/reports/run.json编写完整的JSON会话日志（LLM、JSON-RPC、SSE、工具调用、快照、步骤结果）。
______________________________________________________________________
可用的浏览器自动化工具
导航和交互：
browser_navigate,browser_click,browser_type,browser_press_key,browser_hover,browser_drag
浏览器控件：
browser_tab_new,browser_tab_select,browser_tab_close,browser_resize,browser_close
观察与验证：
browser_snapshot,browser_take_screenshot,browser_console_messages,browser_network_requests,browser_wait_for
______________________________________________________________________
命令
看 commands.md 获取完整的命令参考，包括编排器CLI、客户端实用程序、Jenkins集成和故障排除。
______________________________________________________________________
建筑
高水位流量
1) Test Step → Orchestrator
2) Orchestrator → LLM (parse_natural_language_step + previous page_state)
3) LLM → Structured Output (TestStep with action_type, parameters, ref)
4) Orchestrator → MCP Tool Call (call_tool with parameters)
5) MCP → Tool Response (with actual browser content + page snapshot)
6) Orchestrator → Extract Page State (_extract_page_state from response)
7) Orchestrator → LLM Analysis (analyze_step_result to determine pass/fail)
8) Orchestrator → Update Context (add step result to context manager)
9) LOOP: Next step uses updated page_state and context图表
flowchart TD
A["Test Step (NL)"] --> B["Orchestrator"]
B --> C["LLM: parse_natural_language_step\n+ page_state context"]
C --> D["Structured TestStep\n(action_type, parameters, ref)"]
D --> E["MCP Tool Call\n(JSON-RPC over HTTP; SSE keep-alive)"]
E --> F["MCP Server Tools\n(browser_*, snapshot, etc.)"]
F --> G["Tool Response\n(+ page snapshot/content)"]
G --> H["Orchestrator: _extract_page_state"]
H --> I["LLM: analyze_step_result\n(pass/fail + reasoning)"]
I --> J["Context Manager: add_step_result\n(rolling context)"]
J -->|Next Step| B关键组件和协议
- JSON-RPC over HTTP：编排器使用HTTP POST向MCP服务器发送JSON-RPC请求。响应可能以标准JSON或服务器发送事件（SSE）流上的第一个事件的形式到达。保持持久的SSE连接，以实现高效的服务器通信和通知。
- MCP服务器和工具：MCP服务器公开浏览器自动化工具（例如。，
browser_navigate,browser_click,browser_snapshot)编排器使用结构化参数调用。 - LLM角色：LLM将自然语言步骤转换为结构化的工具调用，并评估工具响应，以产生通过/失败的判断和推理。它还根据滚动上下文和当前页面状态建议下一步。
- 上下文和页面状态：编排器从工具响应中提取Page_State，并维护滚动上下文（通过上下文管理器）。每次循环迭代都使用此更新的上下文和page_state来改进下一步。
______________________________________________________________________
配置
环境变量：
OPENAI_API_KEY（必填）MCP_SERVER_URL（默认值http://localhost:8000)
示例（macOS/Linux）：
export OPENAI_API_KEY=your_key_here
export MCP_SERVER_URL=http://localhost:8000______________________________________________________________________
发展
- 运行测试：
pytest - 格式代码：
black . - 棉绒编码：
flake8
______________________________________________________________________
项目结构
playwright-mcp/
├── mcp-client/
│ ├── orchestrator/ # Orchestrator core (LLM, MCP client, context)
│ ├── test_orchestrator.py # CLI entry for orchestrator
│ ├── README.md # Orchestrator overview
│ └── ORCHESTRATOR_README.md # Detailed usage and docs
├── src/ # Template app code
├── tests/ # Template tests
├── commands.md # Command reference (repo-wide)
└── README.md # This file______________________________________________________________________
故障排除
- 多个选项卡打开或浏览器会话卡住：
- 看 commands.md → “故障排除：清除挥之不去的MCP/Playwright Chrome配置文件”。
______________________________________________________________________
贡献
- 创建要素分支
- 提交前运行格式化程序和linter
- 在适用的情况下添加测试
______________________________________________________________________
许可证
麻省理工学院