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:

git push origin master

Learning Outcomes

You will learn:

• MCP client-server architecture
• Browser automation using Playwright
• How to expose browser actions as MCP tools
• Why STDIO MCP can be stateless
• How to design stable browser-agent workflows
• How to generate professional HTML reports
• How AI can generate exploratory test ideas
• How to evolve from automation scripts to autonomous QA agents

Future Enhancements

• Excel reporting
• PDF reporting
• Console log capture
• Network log capture
• Accessibility checks
• Visual validation
• Login flow testing
• Checkout form validation
• Bug report generation
• AI root cause analysis
• GitHub Actions
• Docker support

Author

Neelam Pal
QA Architect | AI in Testing | MCP | Agentic AI | Quality Engineering

License

MIT License.