MCP Web Testing Server (Proprietary)

Proprietary software. No public license is granted. Use, copying, modification, or distribution is permitted only under a separate written agreement with the Licensor. See: LICENSE

Overview

This repository contains an MCP server for AI-powered web application testing. It provides tools for automated crawling, application analysis, test generation, and test execution using the Model Context Protocol (MCP).

The server integrates with:

• MCP-compatible clients (Claude Desktop, custom clients)
• Playwright MCP for browser automation
• MCP Sampling for AI-powered decision making
• MCP Elicitation for interactive user input

Authorized Use Only

You may use this Software only if:

• you have a separate written agreement with the Licensor, and
• you test only systems you are authorized to test.

Any other use is prohibited. See LICENSE.

Features

• Goal-directed crawling - AI navigates web applications to achieve specified goals
• Application analysis - Automatic discovery of entities, user flows, and assertions
• Test generation - AI-generated test cases based on application analysis
• Test execution - Automated test running with evidence capture
• Progress tracking - Real-time progress notifications with budget status
• Checkpoint & resume - Crawl checkpointing for resumable operations
• Security features - Domain allowlists, injection protection, exfiltration blocking
• Resource management - webtest:// URI scheme for artifact access

Installation

npm install
npm run build

Configuration

Configuration is done via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | TRANSPORT | stdio | Transport type: stdio or http | | PORT | 3000 | HTTP port (when TRANSPORT=http) | | LOG_LEVEL | info | Log level: debug, info, warn, error | | WEBTEST_WORKSPACE_DIR | ./webtest-workspaces | Directory for analysis workspaces | | PLAYWRIGHT_MCP_COMMAND | npx | Command to spawn Playwright MCP | | PLAYWRIGHT_MCP_ARGS | @playwright/mcp@latest | Comma-separated args for Playwright MCP | | CHECKPOINT_INTERVAL | 5 | Steps between crawl checkpoints | | SCREENSHOT_FORMAT | png | Screenshot format: png or jpeg | | SCREENSHOT_QUALITY | 80 | JPEG quality (1-100) | | DEFAULT_MAX_STEPS | 50 | Default max crawl steps | | DEFAULT_MAX_MINUTES | 30 | Default max crawl duration | | DEFAULT_MAX_PAGES | 20 | Default max pages to crawl |

Available Tools

webtest_init

Initialize a new web testing analysis workspace.

Input:

{
  "url": "https://example.com",
  "focus": "User authentication flow",
  "limits": {
    "maxSteps": 50,
    "maxMinutes": 30,
    "maxPages": 20
  },
  "allowedDomains": ["example.com", "*.example.com"]
}

Output: analysisId (e.g., 2025-01-15_10-30), workspacePath

webtest_crawl_app

Perform goal-directed crawling of a web application.

Input:

{
  "analysisId": "2025-01-15_10-30",
  "goal": "Navigate to login page and explore authentication options",
  "strategy": "goal_directed",
  "limits": { "maxSteps": 30 },
  "artifacts": { "captureScreenshots": true, "captureSnapshots": true, "captureDom": true },
  "resume": false
}

Features:

• AI-powered navigation decisions via MCP Sampling
• Loop detection (DOM signatures, URL cycles, action repeats)
• Budget enforcement (steps, time, pages)
• Checkpointing every N steps (configurable)
• Elicitation for user decisions (cookie consent, modals, auth)
• Domain validation and security checks

Output: crawlId (e.g., 2025-01-15_10-30-45), crawlPath, page artifacts

webtest_analyze_app

Analyze a crawled application to extract structure and flows.

Input:

{
  "analysisId": "2025-01-15_10-30",
  "crawlId": "2025-01-15_10-30-45"
}

Output: appAnalysisUri, appAnalysisFilePath, flowsUri, flowsFilePath containing:

• Application purpose and type
• Discovered entities with fields
• User flows with steps
• Assertions (invariants, pre/postconditions)
• Security and accessibility observations

webtest_generate_tests

Generate test cases from application analysis.

Input:

{
  "analysisId": "2025-01-15_10-30",
  "testStrategy": "comprehensive",
  "maxTests": 20,
  "focusFlows": ["checkout-flow", "login-flow"]
}

Output: testsUri, testsFilePath containing test cases with:

• ID, name, purpose, category
• Preconditions and steps
• Expected outcomes

webtest_run_tests

Execute a generated test case.

Input:

{
  "analysisId": "2025-01-15_10-30",
  "testCaseId": "TC-001",
  "runOptions": {
    "captureEvidence": true,
    "stopOnFailure": true,
    "retryFailedSteps": false
  }
}

Output: runId, reportUri, step results with:

• Pass/fail status per step
• Evidence (screenshots, DOM state)
• Failure reasoning and discrepancies

Resources

The server exposes resources via the webtest:// URI scheme:

• webtest://{analysisId}/index.md - Workspace metadata and summary
• webtest://{analysisId}/crawls/{crawlId}/index.md - Crawl index with action history
• webtest://{analysisId}/crawls/{crawlId}/checkpoint.md - Crawl checkpoint state
• webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/snapshot.md - Page accessibility snapshot
• webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/screenshot.png - Page screenshot
• webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/dom.html - Page DOM
• webtest://{analysisId}/analysis/app-analysis.md - Application analysis report
• webtest://{analysisId}/analysis/flows.md - User flows with structured data
• webtest://{analysisId}/tests/tests.md - Generated test cases
• webtest://{analysisId}/runs/{runId}/report.md - Test run report
• webtest://{analysisId}/runs/{runId}/steps/{n}/snapshot.md - Step evidence snapshot

Artifact Format

All artifacts (except screenshots and DOM) use Markdown with YAML frontmatter:

---
analysisId: "2025-01-15_10-30"
url: "https://example.com"
status: "active"
# ... structured data in YAML ...
---

# Human-Readable Content

This section contains formatted markdown for easy browsing.

Benefits:

• Human-readable without special tools
• Structured data accessible via frontmatter parsing
• Works with any markdown viewer or IDE
• Git-friendly diffs

Parsing frontmatter programmatically:

import matter from "gray-matter";

const { data, content } = matter(markdownContent);
// data = parsed YAML frontmatter object
// content = markdown body

Workspace Folder Naming

Workspaces use date-time based folder names for easy identification:

• Workspace ID: YYYY-MM-DD_HH-mm (e.g., 2025-01-15_10-30)
• Crawl ID: YYYY-MM-DD_HH-mm-ss (e.g., 2025-01-15_10-30-45)

Legacy UUID-format IDs are still supported for backwards compatibility.

Prompts

The server provides prompts for guided workflows:

• webtest-start - Initialize a new analysis
• webtest-crawl - Start or continue crawling
• webtest-analyze - Analyze crawled application
• webtest-generate-tests - Generate test cases
• webtest-run-test - Execute a test case
• webtest-full-workflow - Complete end-to-end workflow

Example Workflow

1. Start analysis:
   webtest_init({ url: "https://myapp.com", focus: "checkout flow" })
   → Returns analysisId

2. Crawl the application:
   webtest_crawl_app({ analysisId, goal: "Explore product catalog and checkout" })
   → Returns crawlId, artifacts

3. Analyze the application:
   webtest_analyze_app({ analysisId, crawlId })
   → Returns app structure, flows, assertions

4. Generate test cases:
   webtest_generate_tests({ analysisId, appAnalysisUri })
   → Returns test cases

5. Run tests:
   webtest_run_tests({ analysisId, testCaseId, testsUri })
   → Returns test results with evidence

MCP Client Requirements

For full functionality, the MCP client should support:

| Capability | Required | Used For | |------------|----------|----------| | sampling | Recommended | AI-powered crawling, analysis, test generation | | elicitation | Optional | User decisions during crawl (cookie consent, auth) | | logging | Optional | Structured log delivery via MCP notifications | | resources.listChanged | Optional | Real-time resource update notifications | | resources.subscribe | Optional | Resource subscription support |

Fallback modes: When sampling is unavailable, tools return prompt resources for manual execution. When elicitation is unavailable, questions are returned in tool output.

Security

The server implements multiple security layers:

• Domain allowlists - Restrict navigation to authorized domains
• Prompt injection protection - Untrusted content demarcation in AI prompts
• Data exfiltration blocking - Prevents sensitive data leakage
• Credential elicitation blocking - Refuses to ask for passwords
• Audit logging - All AI inputs/outputs logged for review
• Sensitive data redaction - URL params, cookies, passwords redacted in logs

Getting Access

To request commercial access or a license agreement, contact: Ing. Jan Beránek — [email protected]

Security & Responsible Use

If you discover a security issue, please report it privately to the contact above. Do not open public issues containing sensitive details.

Repository Status

Unless explicitly stated in a separate agreement, this repository is provided without warranty and without support obligations.

License

Copyright (c) 2025 Ing. Jan Beránek. All rights reserved. See LICENSE.