MCP 服务器

QA Browser MCP Agent

An MCP server that enables browser-based QA testing of web applications using Playwright, with support for manual and AI-driven test execution and HTML reporting.

README

QA Browser MCP Agent for ToolShop

A practical Browser MCP Agent series for testing the ToolShop application using Python, FastMCP, Playwright, GitHub Models API, and professional HTML reporting.

Overview

This repository demonstrates how to build a QA Browser MCP Agent for ToolShop:

https://practicesoftwaretesting.com

The project evolves from basic browser control to autonomous AI-powered QA execution.

Who This Is For

Manual Testers
QA Engineers
Automation Testers
SDETs
QA Leads
QA Architects
Students learning MCP
Anyone learning Agentic AI for Software Testing

Architecture

User / QA Engineer
        ↓
Python Main Program
        ↓
FastMCP Client
        ↓
STDIO Transport
        ↓
FastMCP Browser Server
        ↓
Playwright
        ↓
Chrome Browser
        ↓
ToolShop Website
        ↓
Screenshots + HTML Reports

For AI versions:

User Goal
        ↓
GitHub Models API
        ↓
AI Test Plan / Exploratory Test Ideas
        ↓
Browser MCP Server
        ↓
Playwright Execution
        ↓
Professional QA Report

Versions

Version	Folder	Purpose	AI Used	HTML Report
V1	`v1_browser_control`	Browser control basics	No	No
V2	`v2_search_testing_agent`	Search functionality testing	No	Yes
V3	`v3_cart_testing_agent`	Shopping cart testing	No	Yes
V4	`v4_checkout_testing_agent`	Checkout readiness testing	No	Yes
V5	`v5_ai_exploratory_testing_agent`	AI exploratory testing	Yes	Yes
V6	`v6_autonomous_browser_qa_agent`	Autonomous browser QA	Yes	Yes

Project Structure

QA_Browser_MCP_Agent/
├── README.md
├── requirements.txt
├── .gitignore
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docs/
│   ├── architecture.md
│   ├── version-comparison.md
│   ├── troubleshooting.md
│   └── sample-goals.md
├── v1_browser_control/
├── v2_search_testing_agent/
├── v3_cart_testing_agent/
├── v4_checkout_testing_agent/
├── v5_ai_exploratory_testing_agent/
└── v6_autonomous_browser_qa_agent/

Prerequisites

Install:

Python 3.12+
Git
VS Code
Chromium via Playwright
GitHub Models access for V5/V6

Setup

cd C:\GIT\qa_mcp_series
git clone https://github.com/YOUR_USERNAME/QA_Browser_MCP_Agent.git
cd QA_Browser_MCP_Agent

python -m venv .venv
.venv\Scripts\activate

pip install -r requirements.txt
playwright install chromium

Environment Variables

Create .env in the project root only if you want V5/V6 to use GitHub Models:

GITHUB_TOKEN=your_github_models_token_here

V1 to V4 do not need this token.

V5 and V6 also include fallback logic, so they can still run if the token is missing or quota is exhausted.

Run Commands

Run all commands from project root.

python .\v1_browser_control\main.py
python .\v2_search_testing_agent\main.py
python .\v3_cart_testing_agent\main.py
python .\v4_checkout_testing_agent\main.py
python .\v5_ai_exploratory_testing_agent\main.py
python .\v6_autonomous_browser_qa_agent\main.py

Output Locations

Each version stores its own evidence:

v2_search_testing_agent/screenshots/
v2_search_testing_agent/reports/

v3_cart_testing_agent/screenshots/
v3_cart_testing_agent/reports/

v4_checkout_testing_agent/screenshots/
v4_checkout_testing_agent/reports/

v5_ai_exploratory_testing_agent/screenshots/
v5_ai_exploratory_testing_agent/reports/

v6_autonomous_browser_qa_agent/screenshots/
v6_autonomous_browser_qa_agent/reports/

Version 1: Browser Control MCP

Run:

python .\v1_browser_control\main.py

Menu:

1. Show Available MCP Tools
2. Open ToolShop and Capture Screenshot
3. Get ToolShop Homepage Info
4. Verify ToolShop Homepage Loads
0. Exit

Expected output:

v1_browser_control/screenshots/toolshop_homepage.png

Version 2: Search Testing Agent

Run:

python .\v2_search_testing_agent\main.py

Inputs:

Existing product: hammer
Invalid product: xyznotfound
Report name: search_test_report.html

Output:

v2_search_testing_agent/reports/search_test_report.html

Version 3: Cart Testing Agent

Run:

python .\v3_cart_testing_agent\main.py

Inputs:

Product: hammer
Report name: cart_test_report.html

Output:

v3_cart_testing_agent/reports/cart_test_report.html

Version 4: Checkout Testing Agent

Run:

python .\v4_checkout_testing_agent\main.py

Inputs:

Product: saw
Report name: checkout_test_report.html

Output:

v4_checkout_testing_agent/reports/checkout_test_report.html

Version 5: AI Exploratory Testing Agent

Run:

python .\v5_ai_exploratory_testing_agent\main.py

Example goals:

Perform security-oriented exploratory testing on ToolShop search
Explore ToolShop search from a usability perspective
Perform boundary testing on ToolShop search
Test ToolShop search functionality like a functional QA engineer

Output:

v5_ai_exploratory_testing_agent/reports/ai_exploratory_search_report.html

Version 6: Autonomous Browser QA Agent

Run:

python .\v6_autonomous_browser_qa_agent\main.py

Example goals:

Test ToolShop search functionality like a senior QA engineer
Perform security-focused browser QA testing on ToolShop search
Perform usability-focused testing on ToolShop product search
Perform boundary and negative testing on ToolShop search

Output:

v6_autonomous_browser_qa_agent/reports/autonomous_browser_qa_report.html

Important Concept: Why Single-Flow Tools Are Used

In MCP STDIO mode, each tool call may start a new server process. Browser state may not persist across separate menu options.

That is why this project uses stable single-flow tools:

open_toolshop_and_capture_screenshot()
run_search_functionality_tests()
run_cart_functionality_tests()
run_checkout_functionality_tests()
run_ai_exploratory_search_tests()
run_autonomous_browser_qa()

Troubleshooting Summary

Detailed troubleshooting is available in:

docs/troubleshooting.md

Common issues covered:

Browser state not persisting
Unknown tool
MCP connection closed
Missing GitHub token
Same AI results for every goal
GitHub Models rate limit
Playwright timeout
Checkout button not found
Screenshot links not opening
Browser executable missing

Git Commands

Check status:

git status

Recommended .gitignore should exclude:

.env
.venv/
__pycache__/
screenshots/
reports/
*.html
*.png

Commit:

git add README.md requirements.txt .gitignore LICENSE CHANGELOG.md CONTRIBUTING.md docs/ v1_browser_control/ v2_search_testing_agent/ v3_cart_testing_agent/ v4_checkout_testing_agent/ v5_ai_exploratory_testing_agent/ v6_autonomous_browser_qa_agent/
git commit -m "Add QA Browser MCP Agent with six progressive versions"
git push origin main

If your branch is master: