Hulupeep/mcp-ui-probe

UI-Probe: Test Any Website in Plain English

Warning Will Robinson! This is a work in progress. You ned to provide your own key so running it will cost you money. that said...openrouter has lots of free options

The Problem

Website testing is broken. You write hundreds of lines of code that breaks the moment a developer changes a button class from btn-primary to button-primary. Your tests fail not because the app is broken, but because someone moved a div or renamed an ID.

The Solution

UI-Probe is an assistant-first, Claude/MCP-native web app tester.

UI-Probe lets you test websites by describing what you want to do in plain English. No code. No selectors. Just describe it like you'd tell a human.

⚡ Not the First, But a Different Take

Tools like Testim, Mabl, and Rainforest QA already bring codeless/AI testing to market. They’re powerful, but often enterprise-heavy, SaaS-locked, and tuned for QA engineers.

UI-Probe takes a different path:

• Assistant-first → Runs natively inside Claude via MCP. You just talk to your assistant and watch it work.
• Plain English by default → No scripts, no recorders. Just tell it what you want tested.
• Beginner-friendly → PMs, designers, and non-devs can use it right away.
• Open-source + lightweight → Clone, run, hack. No vendor lock-in.
• From testing → to doing → Today: check your web flows. Tomorrow: actually run them.

From Testing → to Doing

UI-Probe doesn’t stop at testing. The same way you say:

• “✅ Test if users can sign up”

…you can also say:

• “✅ Actually sign me up for an account”
• “✅ Buy a blue shirt from the shop”
• “✅ Order me a ham + mustard sandwich from sandwich.com and deliver it”

So what starts as a QA helper can also become your personal web agent — able to test, repeat, and even perform real tasks for you.

UI Probe is not just testing — it's a universal intention layer for the web made simple.

What Makes UI-Probe Different

🚀 Stateful Testing Orchestrator vs Script Generator

Unlike standard Playwright MCP tools that create a new JavaScript file for every test, UI-Probe is a persistent, intelligent testing server that maintains context and learns from interactions.

Standard Playwright MCP:

• Creates a new .js file for each test
• No memory between tests
• You write: await page.click('#submit')
• Starts fresh browser each time
• Manual selector management

UI-Probe:

• Single persistent server managing all tests
• Maintains browser context and state
• You say: "Sign up as a new user"
• Intelligent form understanding
• Journey recording and replay

🧠 AI-Powered Intelligence Built-In

• LLM Strategy Engine - Uses GPT-4/Claude to understand UI context and intent
• Workflow Decomposer - Automatically breaks "Order a pizza" into logical steps
• Adaptive Executor - Adjusts strategy when pages behave unexpectedly
• Error Enhancer - Provides intelligent, actionable error messages
• Form Inference Engine - Automatically understands form structure, validation rules, and generates appropriate test data

📼 Journey Recording & Replay System

Complete journey management that no standard Playwright tool offers:

• Record once, replay forever - Capture complex workflows and replay them
• Journey Validation - Ensures recorded journeys remain valid
• Journey Analysis - Identifies patterns and improvements
• Journey Discovery - Automatically discovers new test paths
• Smart selector generation - Creates resilient selectors that survive UI changes

🎯 Natural Language Goal Execution

// Standard Playwright approach - you write the code:
const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://example.com');
await page.fill('#email', 'test@example.com');
await page.fill('#password', 'password123');
await page.click('button[type="submit"]');

// UI-Probe approach - just describe your goal:
run_flow({ goal: "Sign up as a new user" })

📊 Additional Unique Features

• Built-in test playground - Test pages included to try before deploying to your project
• Real-time monitoring - Watch tests run with live feedback
• Claude-native - Designed specifically for Claude Code CLI, not retrofitted
• Actually works for non-devs - PMs, designers, QA can use it immediately
• Open source - No vendor lock-in, customize as needed
• Semantic AI Resolution - Smart hybrid that uses Playwright's semantic selectors first, then falls back to LLM intelligence only when needed
• No Code Required - Unlike raw Playwright MCP where Claude must write test scripts, UI-Probe works immediately without any programming
• Deterministic JSON Responses - Every action returns structured JSON that enables conditional logic and automation:

{
  "success": true,
  "data": {
    "clicked": true,
    "selector": "button:has-text(\"Submit Form\")",
    "currentUrl": "http://localhost:8083/test/forms",
    "pageTitle": "Forms Testing - UI-Probe"
  }
}

This means you can build intelligent workflows:

# If form submission fails, try alternative flow
if response.success == false:
  navigate to backup_url
  retry with different_data

# Instead of this nightmare:
await driver.findElement(By.xpath("//div[@id='login-form']//input[@name='email']")).sendKeys("test@example.com");
await driver.findElement(By.css(".btn-submit.primary")).click();

# You can use natural language:
"Test the signup form"

# Or explicit commands when you need precision:
fill_form {"email": "test@example.com"}
click_button "Sign Up"

For Complete Beginners

Never written code? Perfect! UI-Probe is designed for you:

1. Install it (one-time setup, 5 minutes)
2. Tell it what to test in plain English
3. Get clear results - "✅ Account created" or "❌ The signup button is hidden"

Example for Non-Developers

Want to test your website's contact form every day? Just type:

# In Claude, you can be natural:
"Test the contact form on my homepage"

# Claude figures out the URL from context, or you can be explicit:
fill_form "https://mysite.com/contact" {"message": "Testing!"}

That's it. No programming required.

For Developers

UI-Probe gives you:

• Self-healing tests - Automatically adapts when UI changes
• 80% less code - One line instead of dozens
• AI-powered intelligence - Uses GPT-4/Claude to understand pages
• Clear error messages - "Button is hidden by cookie banner" vs "ElementNotInteractableException"

Quick Start (5 Minutes)

🎯 TL;DR - Get Running Quickly

npx mcp-ui-probe setup                                                      # 1. Install browsers (one-time)
echo "OPENAI_API_KEY=sk-..." > .env                                        # 2. Add API key (optional but recommended)
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash  # 3. Connect to Claude
claude                                                                       # 4. Start using!

Prerequisites

• Node.js 18+ (Download - just click "Next" through installer)
• Claude Code CLI or any terminal
• OpenAI or Anthropic API key for best results (optional - works without but poorer performance)

System Requirements

• OS: Windows, macOS, or Linux
• Node.js: Version 18 or higher
• Disk Space: ~500MB for Playwright browsers (one-time download)
• RAM: 2GB minimum, 4GB recommended

Option 1: Use with npx (Easiest - Works Everywhere!)

Step 1: Initial Setup (One-Time Only)

# Install Playwright browsers needed for web testing (~500MB, takes 2-3 minutes)
npx mcp-ui-probe setup

Step 2: Enable AI Intelligence (Optional but Recommended)

For best results with intelligent form understanding, set your API key:

# Create a .env file in your current directory
echo "OPENAI_API_KEY=your-key-here" > .env
# OR for Anthropic
echo "ANTHROPIC_API_KEY=your-key-here" > .env

Note: UI-Probe works without this, but AI features significantly improve:

• Form field understanding
• Error message clarity
• Natural language processing
• Smart element detection

Step 3: Connect to Claude Code CLI

Why this extra step? Claude Code CLI can't find npx by itself because it doesn't have access to your shell's PATH. You need to tell Claude exactly where npx is located on your computer.

Option A: Automatic Setup (Easiest - does everything for you):

# This script will:
# 1. Find where npx is installed on your computer
# 2. Add UI-Probe to Claude with the correct path
# 3. Verify everything is configured properly
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash

After running this, just restart Claude and UI-Probe will be ready to use!

Option B: Manual Setup (if automatic doesn't work):

Step 1: Find your npx path

# On macOS/Linux:
which npx
# Example output: /usr/local/bin/npx or ~/.nvm/versions/node/v20.11.0/bin/npx

# On Windows:
where npx
# Example output: C:\Program Files\nodejs\npx.cmd

Step 2: Add to Claude with the full path

# Use YOUR path from Step 1:
claude mcp add ui-probe "/full/path/to/npx" "mcp-ui-probe@latest" "start"

# Real examples:
# Standard Node:
claude mcp add ui-probe "/usr/local/bin/npx" "mcp-ui-probe@latest" "start"

# Using NVM:
claude mcp add ui-probe "$HOME/.nvm/versions/node/v22.11.0/bin/npx" "mcp-ui-probe@latest" "start"

# Windows:
claude mcp add ui-probe "C:\Program Files\nodejs\npx.cmd" "mcp-ui-probe@latest" "start"

Step 4: Start Using UI-Probe in Claude!

# Start Claude Code CLI
claude

# UI-Probe tools are now available! Try:
# - Navigate to websites
# - Analyze page elements
# - Fill and submit forms
# - Run complete test flows

Step 5: (Optional) Try the Test Playground

Want to see UI-Probe in action before testing your own sites?

# Start the built-in test server with example forms
npx mcp-ui-probe test-server   # Runs on http://localhost:8081/test
npx mcp-ui-probe test-server --port 3000   # Use custom port if 8081 is busy

# Visit http://localhost:8081/test in your browser to see the playground
# Then in Claude, try: run_flow "Sign up as new user" "http://localhost:8081/test"

Option 2: Install from Source

# Clone it (this downloads the code)
git clone https://github.com/Hulupeep/mcp-ui-probe.git
cd mcp-ui-probe

# Install it (this sets everything up)
npm install

# CRITICAL: Install browsers (one-time, takes 2-3 minutes)
npx playwright install

# Add to Claude:
claude mcp add ui-probe "node" "/path/to/mcp-ui-probe/dist/index.js"

Start Testing!

# In Claude, just describe what you want:
"Test if users can sign up on example.com"

# Or be specific:
run_flow "Go to https://example.com/signup and create an account"

How UI-Probe Works in Claude

Natural Language (Default - Just Talk Normally!)

UI-Probe understands what you want to do:

# Just describe what you want - UI-Probe figures it out:
"Test if users can sign up on example.com"
"Check if the checkout process works"
"Fill out the contact form with test data"
"Click the submit button"

Explicit Commands (When You Need Precise Control)

Sometimes you need to be specific about exactly what to do:

# Use explicit commands for precise control:
navigate "https://staging.myapp.com/login"           # Go to exact URL
fill_form "https://myapp.com/contact" {"message": "Test"}  # Fill specific fields
click_button "Submit Order"                          # Click exact button text
assert_element "div.success" "visible"               # Check specific element

Best Practice: Start with natural language. If UI-Probe needs clarification or you need precise control, switch to explicit commands.

Common Tasks

Test a Login Form

# Natural language (recommended to start):
"Test if users can log in to myapp.com"
"Check the login flow"

# Explicit commands (for precise control):
navigate "https://myapp.com/login"
fill_form {"email": "test@example.com", "password": "password123"}
click_button "Sign In"
verify_page {"expectedContent": ["Dashboard", "Welcome"]}

Test a Purchase

# Natural language:
"Buy a blue shirt from shop.com"
"Test the checkout process with a test credit card"

# Explicit commands:
navigate "https://shop.com"
click_button "Shirts"
click_button "Blue Cotton Tee"
click_button "Add to Cart"
fill_form {"card": "4111111111111111", "exp": "12/25", "cvv": "123"}
click_button "Complete Order"

Test Form Validation

# Test what happens with bad data:
fill_form "https://myapp.com/signup" {"email": "not-an-email"}
# UI-Probe tells you: "❌ Email validation error appeared"

Check if Something Exists

assert_element "https://myapp.com" "Free shipping" "visible"
# Returns: "✅ Found 'Free shipping' on page"

What Makes UI-Probe Different

Traditional Testing Tools

• Write code with specific selectors
• Tests break when UI changes
• Cryptic error messages
• Need programming knowledge
• Hundreds of lines of code

UI-Probe

• Describe in plain English
• Self-healing when UI changes
• Clear, human-friendly errors
• No programming needed
• One line does it all

Real-World Examples

E-commerce Site

# Complete purchase flow
"Buy the cheapest laptop on the site"

# UI-Probe automatically:
# - Finds the shop
# - Searches for laptops
# - Sorts by price
# - Adds to cart
# - Fills checkout
# - Completes purchase

SaaS Application

# Test free trial signup
"Sign up for a free trial with a company email"

# UI-Probe:
# - Navigates to signup
# - Detects it's a business form
# - Fills company fields
# - Uses appropriate test data
# - Verifies trial activated

Banking App

# Test money transfer
"Transfer $50 from checking to savings"

# UI-Probe:
# - Logs in securely
# - Navigates to transfers
# - Fills amount
# - Selects accounts
# - Confirms transfer

🏗️ Architecture Overview

UI-Probe is built as an intelligent, stateful testing orchestrator rather than a simple script runner:

┌─────────────────────────────────────────────────────────┐
│                     Claude Code CLI                      │
│                    (Natural Language)                    │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   MCP Server (Persistent)                │
│  ┌─────────────────────────────────────────────────┐    │
│  │            Intelligent Components               │    │
│  │  • LLM Strategy Engine (GPT-4/Claude)          │    │
│  │  • Workflow Decomposer                         │    │
│  │  • Adaptive Executor                           │    │
│  │  • Form Inference Engine                       │    │
│  │  • Error Enhancer                              │    │
│  └─────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │            Journey System                       │    │
│  │  • Journey Recorder & Player                   │    │
│  │  • Journey Validator & Analyzer                │    │
│  │  • Journey Discovery & Storage                 │    │
│  └─────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Playwright Driver (Stateful)            │    │
│  │  • Persistent browser context                   │    │
│  │  • Smart selector generation                    │    │
│  │  • Automatic retry & recovery                   │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   Your Web Application                   │
└─────────────────────────────────────────────────────────┘

Key Architectural Advantages:

1. Persistent Server - No startup overhead, maintains state across tests
2. Intelligent Layer - LLM-powered understanding, not just automation
3. Journey System - Record once, replay with variations
4. Stateful Context - Remembers login sessions, previous interactions
5. Adaptive Execution - Adjusts strategy based on page behavior

Built-in Test Playground

UI-Probe includes a comprehensive test playground to try before deploying to your project:

# Start the test server (runs on port 8081)
npm run test:server

# Visit http://localhost:8081/test in your browser to see the playground

Available Test Pages:

• Main Test Page (/test) - Complete sign-up form with validation
• Forms Testing (/test/forms) - Every input type (text, select, radio, checkbox, etc.)
• Navigation Testing (/test/navigation) - Multi-page navigation and routing
• Dynamic Content (/test/dynamic) - JavaScript-driven UI updates
• Validation Scenarios (/test/validation) - Error handling and edge cases

Test in Claude:

# Analyze form structure
analyze_ui "http://localhost:8081/test/forms"

# Fill and submit forms
fill_form "http://localhost:8081/test/forms" {"firstName": "John", "email": "john@example.com"}

# Run complete flows
run_flow(goal="Sign up as new user", url="http://localhost:8081/test")

## Configuration

### Basic (.env file)
```bash
# Make UI-Probe smarter
OPENAI_API_KEY=sk-...

# See the browser window
HEADLESS=false

# Show detailed logs
DEBUG=true

Advanced Options

# Timeout for slow sites (milliseconds)
TIMEOUT=60000

# Retry failed operations
MAX_RETRIES=5

# Take screenshots on failure
SCREENSHOT_ON_FAILURE=true

Troubleshooting

"Failed to connect" or "Connection failed" in Claude Code CLI

Problem: Claude shows ui-probe as "failed" or can't connect when you run claude mcp list.

Solution: Claude Code CLI needs the full path to npx, not just "npx".

1. Find your npx location:

   which npx  # Mac/Linux
   where npx  # Windows
   

2. Remove the broken configuration:

   claude mcp remove ui-probe
   

3. Add with the full path:

   # Use YOUR actual path from step 1
   claude mcp add ui-probe "/path/from/step1/npx" "mcp-ui-probe@latest" "start"
   

4. Start a new Claude Code session

   claude  # The MCP server will now connect properly
   

Common npx locations:

• Standard Node.js: /usr/local/bin/npx
• NVM (Node Version Manager): ~/.nvm/versions/node/vXX.XX.X/bin/npx
• Homebrew (Mac): /opt/homebrew/bin/npx
• Windows: C:\Program Files\nodejs\npx.cmd

"Port already in use" when starting test server

Solution: Use a different port:

npx mcp-ui-probe test-server --port 3000

"Navigation failed"

The site can't be reached. Check:

1. Is the URL correct?
2. Is the site running? (for localhost)
3. Run npx playwright install (if you haven't)

"Element not found"

The button/form/link isn't there. Try:

1. analyze_ui "URL" to see what's on the page
2. wait_for "URL" "element" "visible" for slow-loading content
3. Be more specific: "the blue submit button" vs just "submit"

Form won't fill

Custom form elements. Try:

1. analyze_ui to see what UI-Probe detects
2. Use click for custom dropdowns
3. Use run_flow for complex interactions

🎬 Journey Recording & Replay System

New Feature! UI-Probe now includes an intelligent journey recording system that eliminates the need to rediscover UI flows repeatedly.

⚡ Speed Up Testing by 80%

Record user interactions once, replay them instantly:

# Record a complete signup flow
journey_record_start {"name": "User Signup", "description": "Complete signup from landing page"}
# Perform your interactions...
journey_record_stop {"tags": ["auth", "signup"], "category": "user-onboarding"}

# Replay instantly later
journey_play {"journeyId": "journey_20250925_123456", "config": {"speed": 1.5}}

🤖 AI-Powered Intelligence

• Smart naming: AI generates meaningful journey names and descriptions
• Context validation: Ensures journeys only run when appropriate (can't order on a signup page)
• Self-healing selectors: Adapts to UI changes with multiple fallback strategies
• Pattern recognition: Suggests similar journeys and optimizations

🔍 Journey Discovery

# Find journeys compatible with your current page
journey_discover {"url": "https://mysite.com/login", "limit": 5}

# Search by tags, category, or success rate
journey_search {"query": "checkout", "tags": ["payment"], "minSuccessRate": 0.8}

📊 Success Tracking

Each journey tracks:

• Success rate across multiple runs
• Performance metrics and timing
• Usage statistics
• Difficulty estimation

🎯 Benefits

• 80% faster test execution by eliminating element discovery
• Self-healing - journeys adapt to UI changes automatically
• Reusable - share journeys across teams and projects
• Discoverable - AI-powered search finds relevant flows
• Reliable - context validation prevents mismatched executions

📖 See for advanced features and usage patterns.

Smart Features

Automatic Test Data

UI-Probe generates appropriate test data:

• Valid emails that pass validation
• Strong passwords that meet requirements
• Phone numbers in the right format
• Realistic names and addresses
• Test credit cards (4111111111111111)

Self-Healing Tests

When developers change:

• Class names → UI-Probe still finds the button
• IDs → Still works
• Page structure → Adapts automatically
• Text labels → Understands context

Clear Error Messages

❌ Traditional: "WebDriverException: unknown error: Element is not clickable at point (780, 532)"

✅ UI-Probe: "The submit button is hidden behind a cookie consent banner. Try dismissing the banner first."

Response Structure

MCP UI-Probe provides two types of deterministic JSON responses:

Simple Tool Responses

Individual tool commands (navigate, click_button, analyze_ui, etc.) return:

Example:

{
  "success": true,
  "data": {
    "clicked": true,
    "selector": "button:has-text(\"Submit\")",
    "currentUrl": "http://example.com/success",
    "pageTitle": "Success Page"
  }
}

Complex Test Execution Responses

Comprehensive test commands (run_flow, fill_and_submit) return detailed reports with:

• Complete test execution flow with all steps
• Performance metrics and timings
• Error collection and categorization
• Accessibility findings
• Test artifacts and evidence

This deterministic structure enables intelligent automation:

// Simple tool for conditional logic
const result = await ui_probe.click_button({ text: "Submit" });
if (result.success) {
  console.log(`Navigated to: ${result.data.currentUrl}`);
} else {
  console.log(`Failed: ${result.error}`);
}

// Complex command for full test execution
const testResult = await ui_probe.run_flow({
  goal: "Complete signup process",
  url: "http://example.com/signup"
});
console.log(`Test ${testResult.result}: ${testResult.metrics.steps} steps`)

📖 See for comprehensive details on both simple and complex response types.

API Reference

Core Testing Commands

Journey Recording & Replay Commands

📖 See for detailed parameters and response structures.

Comparison with playwright-mcp

Quick Summary

UI-Probe and playwright-mcp are complementary tools, not competitors:

• playwright-mcp: Low-level infrastructure tool providing primitive browser commands for AI agents
• UI-Probe: High-level testing application with plain English interface for end users

Key Differences

Critical Advantage: No Code Generation Required

With playwright-mcp, Claude must write and execute test code:

// Claude has to generate this for every test
await page.goto('http://example.com');
await page.fill('#email', 'test@example.com');
await page.click('button[type="submit"]');
// Error handling, retries, validation...

With UI-Probe, just describe what you want:

"Test the login form"
# That's it - no code generation needed

Deterministic JSON for Automation

Every UI-Probe action returns predictable JSON that enables conditional logic:

// UI-Probe response - always structured the same way
{
  "success": true,
  "data": {
    "formSubmitted": true,
    "validationErrors": [],
    "nextUrl": "/dashboard"
  }
}

// This enables intelligent automation:
if (!response.success) {
  // Handle failure automatically
  useAlternativeFlow();
}

The Bottom Line

• Use playwright-mcp if you're a developer building an AI agent that needs browser control
• Use UI-Probe if you want to test websites without writing code

Think of playwright-mcp as the engine and UI-Probe as the user-friendly car built around it.

→ For detailed comparison, see

Contributing

We love contributions! See .

Support

• Docs:
• Examples:
• Issues: Report problems
• Discussions: Ask questions

License

MIT - Use it however you want!

Stop writing code that breaks. Start testing like a human.

Ready? Install now or see examples