Blop Mcp — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Blop Mcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Most AI testing tools can click through pages. Teams still do not know whether they should ship.
blop turns browser execution into release decisions by combining business-critical journey context, evidence-heavy QA runs, and risk governance in one MCP-native control plane.
You do not write test code. You ask in chat, then ship with auditable evidence, prioritized risk, and a clear go/no-go recommendation.
Compatible MCP clients: Cursor, Claude Code, and other clients that support MCP tool/resource workflows.
docs/DOC_CONTRACT.mddocs/AGENT_CONTEXT_PACK.mddocs/oss_core_competitive_analysis.mddocs/capability_placement_open_core.mdIt plugs into Cursor or Claude Code as an MCP tool — meaning you just ask it to run tests in a chat window, the same way you'd ask a colleague.
blop://...) are for low-token retrieval and planning..blop/ and runs/).blop is not just a browser runner. The broader product thesis is that release decisions should reflect product context such as customer goals, acceptance criteria, and release scope. This OSS repo mainly implements the local execution and evidence plane today, but the docs and interfaces should still frame those runs as inputs into a roadmap-aware release-confidence workflow.
Generic browser agents optimize for test execution throughput. blop optimizes for decision quality under uncertainty.
| Dimension | Generic AI browser runner | blop MCP-native approach |
|---|---|---|
| Output shape | Mostly conversational text | Structured contracts + typed envelopes via blop_v2_get_surface_contract and v2 resources |
| Context handling | Re-run flows to recover context | Read blop://... resources first (inventory, context-graph, artifact-index, stability-profile) |
| Ops model | One-shot execution focus | Async run lifecycle with health stream, run states, and artifact indexing |
| Release decisions | Manual interpretation | Risk scoring, incident clustering, remediation drafts, telemetry correlation |
| Client portability | Tooling-specific patterns | Standard MCP tool/resource model across Cursor, Claude Code, and compatible clients |
Proof points in implementation:
src/blop/tools/v2_surface.pysrc/blop/storage/sqlite.pysrc/blop/reporting/results.pyIf your release process needs a deterministic answer to "can we ship this safely?", blop is purpose-built for that question.
| What | Where to get it | Takes | |
|---|---|---|---|
| Python 3.11 or newer | python.org/downloads | 5 min | |
uv (fast Python installer) | Run `curl -LsSf https://astral.sh/uv/install.sh \ | sh` in Terminal | 1 min |
| Google API key (free tier works) | aistudio.google.com/app/apikey | 2 min | |
| Cursor or Claude Code | cursor.com or npm i -g @anthropic-ai/claude-code | 5 min | |
| Chromium runtime | Installed by playwright install chromium --with-deps --no-shell | 2-5 min |
Open Terminal and run these commands one at a time:
# 1. Go into the blop folder
cd /path/to/blop-mcp
# 2. Create a Python environment
uv venv && source .venv/bin/activate
# 3. Install blop
uv pip install -e .
# 4. Install the browser blop controls
playwright install chromium --with-deps --no-shellYou should see no errors. If you do, check the Troubleshooting section below.
blop-mcp now supports a standard Python distribution path for PyPI publishing while preserving the blop and blop-mcp CLI commands.
Local maintainer smoke check:
uv pip install -e ".[dev]"
python -m build
python -m venv /tmp/blop-dist-smoke
source /tmp/blop-dist-smoke/bin/activate
pip install dist/*.whl
blop --help
blop-mcp --helpThis should build both the sdist and wheel, install the wheel into a clean environment, and verify the console entrypoints start.
Release instructions:
python -m twine upload dist/*.docs/releasing.mdCopy the example config file and fill it in:
cp .env.example .envThen open .env in any text editor and fill in your values:
# Required — get this from aistudio.google.com/app/apikey
GOOGLE_API_KEY=your_key_here
# Your app's URL
APP_BASE_URL=https://your-app.com
# Login details (only needed for testing authenticated pages)
LOGIN_URL=https://your-app.com/login
[email protected]
TEST_PASSWORD=your_passwordEverything else can stay as-is.
Optional Blop Cloud sync:
# Leave these unset for local-only mode.
BLOP_HOSTED_URL=https://app.blop.dev
BLOP_API_TOKEN=blop_sk_...
BLOP_PROJECT_ID=00000000-0000-0000-0000-000000000000validate_release_setup treats Blop Cloud sync as non-blocking: it warns on partial config and probes /api/v1/sync/connection when all three values are present.
.cursor/mcp.json.example and copy it to .cursor/mcp.json locally if you prefer a file-based setup (the real mcp.json is gitignored).{
"mcpServers": {
"blop": {
"command": "uv",
"args": ["--directory", "/path/to/blop-mcp", "run", "python", "-m", "blop.server"],
"env": {
"GOOGLE_API_KEY": "your_key_here",
"APP_BASE_URL": "https://your-app.com",
"LOGIN_URL": "https://your-app.com/login",
"TEST_USERNAME": "[email protected]",
"TEST_PASSWORD": "your_password"
}
}
}
}Run this once in your terminal:
claude mcp add blop /path/to/blop-mcp/.venv/bin/blop-mcp \
-e GOOGLE_API_KEY="your_key_here" \
-e APP_BASE_URL="https://your-app.com" \
-e LOGIN_URL="https://your-app.com/login" \
-e TEST_USERNAME="[email protected]" \
-e TEST_PASSWORD="your_password"Type /mcp in Claude Code to verify — you should see blop: connected.
blop production is optimized for a client-managed `stdio` MCP process (Cursor/Claude launching blop-mcp), with strict runtime/path validation and least-privilege tool exposure.
docs/production_setup.mddeploy/prod.env.templatedeploy/systemd/blop-http.servicedeploy/docker/DockerfileRecommended production posture:
BLOP_ENV=productionBLOP_REQUIRE_ABSOLUTE_PATHS=trueBLOP_DB_PATH, BLOP_RUNS_DIR, and BLOP_DEBUG_LOGBLOP_ALLOW_INTERNAL_URLS=false (default-safe URL policy)BLOP_CAPABILITIES_PROFILE=production_minimalBLOP_ENABLE_COMPAT_TOOLS=false unless explicitly requiredOpen a chat window in Cursor or Claude Code and paste this (swap in your app URL):
Use blop to test https://your-app.com
1. Call validate_release_setup(app_url="https://your-app.com") and stop if status is "blocked"
2. Call discover_critical_journeys(app_url="https://your-app.com") to find the release-gating journeys
3. Read blop://journeys and pick the gated journeys that matter for this release
4. Record or refresh those journeys with record_test_flow(...) so release checks run against real saved flows
5. Call run_release_check(app_url="https://your-app.com", journey_ids=[...], mode="replay")
6. Poll get_test_results(run_id="...") until status is terminal
7. Read blop://release/{release_id}/brief and blop://release/{release_id}/artifacts
8. If the decision is not SHIP, call triage_release_blocker(run_id="...") and summarize blockers, evidence, and next actionsThat is the canonical MVP loop: validate, discover, record, replay, and triage.
validate_release_setup.discover_critical_journeys.record_test_flow.run_release_check in replay mode against recorded flows.triage_release_blocker plus blop://release/* resources to turn failures into decisions.targeted mode is still available for one-off exploratory checks, but it is a shortcut, not the golden path for release gating. For larger public sites, you can raise its one-shot budget with BLOP_TARGETED_MAX_STEPS (default 40).
For protected apps, the most reliable path is:
capture_auth_session(...)validate_release_setup(app_url="https://your-app.com", profile_name="your_profile")run_release_check(..., mode="replay")If a run returns waiting_auth or validation says the session is expired:
capture_auth_session(...) to refresh the saved session.validate_release_setup(...) to confirm the session lands inside the app.If failure output points to stale recordings, refresh the affected journey with record_test_flow(...) before trusting replay failures as real regressions.
Canonical MCP-client setup guides:
docs/quickstart_cursor.mddocs/quickstart_claude_code.mddocs/quickstart_codex.mdOperational references:
docs/production_setup.mddocs/operator_failures.mdget_test_results(...) includes per-run bucket summaries and get_risk_analytics(...) aggregates top buckets, blocker buckets, and highest-pain instability classes.docs/compatibility_policy.mddocs/release_notes_template.mdFor each candidate release, summarize:
blop now includes an additive compatibility layer for prompt portability across MCP clients that expect Playwright-style browser_* tools (Cursor, Claude, Codex, Copilot, Windsurf, etc.).
Enable it by adding compat_browser to capabilities:
export BLOP_CAPABILITIES=core,auth,debug,compat_browserOptional compatibility env vars:
| Variable | Default | Purpose |
|---|---|---|
BLOP_COMPAT_OUTPUT_DIR | .playwright-mcp | Where compatibility artifacts (snapshots/screenshots/storage-state files) are written |
BLOP_COMPAT_HEADLESS | true | Run compatibility browser session headless or headed |
BLOP_COMPAT_TEST_ID_ATTRIBUTE | data-testid | Preferred test id attribute used when building element selectors |
BLOP_COMPAT_SNAPSHOT_MODE | incremental | Snapshot mode hint for compatibility workflows |
Typical interop flow:
browser_navigate(url=...)browser_snapshot() to obtain ref handlesbrowser_click(ref=...) / browser_type(ref=..., text=...)browser_tabs(action="list"|"new"|"select")browser_console_messages(...), browser_network_requests(...)browser_close()Auth bridge behavior:
profile_name is passed to browser_navigate, blop resolves that saved auth profile first.save_auth_profile, capture_auth_session).browser_* cookie/state/route tools act on the shared compat session only; use get_browser_cookies, set_browser_cookie, save_browser_state, and mock_network_route when you want URL-scoped storage operations or regression-run mocks.Tool confusion matrix (use this / not that):
| If you want to... | Use this | Not that | Why |
|---|---|---|---|
| Inspect cookies for a specific URL/profile | get_browser_cookies(app_url, profile_name?) | browser_cookie_list() | get_browser_cookies is URL-scoped and runs in an ephemeral context; browser_cookie_list reads the shared compat session. |
| Set a cookie for URL-scoped auth state | set_browser_cookie(app_url, ...) | browser_cookie_set(...) | set_browser_cookie persists URL/profile state for blop auth flows; browser_cookie_set mutates only the shared compat session. |
| Save URL/profile storage state to disk | save_browser_state(app_url, ...) | browser_storage_state(...) | save_browser_state captures URL-scoped state; browser_storage_state exports the current shared compat session. |
| Mock APIs during regression replay runs | mock_network_route(...) | browser_route(...) | mock_network_route applies during regression execution; browser_route only affects the shared compat browser session. |
| Capture one-off exploratory QA output | evaluate_web_task(...) | record_test_flow(...) | evaluate_web_task returns immediate report output for one-off checks (see full reference); record_test_flow creates reusable flow artifacts for regression. |
| Create reusable regression flow IDs | record_test_flow(...) | evaluate_web_task(...) | record_test_flow is the source of reusable flow_id values consumed by run_release_check(..., mode="replay"). |
| Inspect page interaction structure from crawling context | get_page_structure(app_url, url?) | browser_snapshot(...) | get_page_structure is crawl/discovery-oriented; browser_snapshot is for current shared compat session state. |
| Start/stop the long-lived compat browser interaction loop | browser_navigate(...), browser_snapshot(...), browser_click(...) | discover_critical_journeys(...) | browser_* tools are imperative session controls; journey discovery is planning/crawl output, not interactive control. |
Use blop to discover and test https://new-saas-app.com from scratch.
1. Call validate_release_setup(app_url="https://new-saas-app.com")
2. Call discover_critical_journeys with business_goal="Find all revenue-critical journeys including signup, checkout, and onboarding"
3. Record the top suggested gated journeys with `record_test_flow`
4. Call run_release_check in replay mode and summarize anything that blocks shippingWe're about to ship a new version. Use blop to run a pre-release check on https://staging.myapp.com:
1. list_recorded_tests — show what flows we have
2. run_release_check on all release-gating flows against staging
3. get_test_results — compare pass/fail to last run
4. triage_release_blocker or debug_test_case on anything that changed from pass to failTest the authenticated product experience on https://app.myapp.com:
1. save_auth_profile("prod-user", "env_login", login_url="https://app.myapp.com/login")
2. record_test_flow for: dashboard load, core feature (e.g. "create new project"), settings page, and billing/upgrade journey
3. run_release_check with profile_name="prod-user"
4. get_test_results — show me the full breakdownA user reported the checkout button isn't working. Use blop to investigate:
1. record_test_flow("https://myapp.com", "checkout_bug", "Navigate to pricing, click the Pro plan CTA, and verify checkout loads")
2. run_release_check on that flow
3. get_test_results — check step_failure_index and assertion_failures
4. debug_test_case on the failure to get screenshots and a plain-English explanationOption A — Interactive capture (recommended): Use capture_auth_session so blop opens a browser and you log in once; it saves the session and creates the profile automatically.
capture_auth_session(
profile_name="sso-session",
login_url="https://your-app.com/login",
success_url_pattern="/dashboard",
timeout_secs=120
)For providers (e.g. Google, LinkedIn) that block "headless" or fresh contexts, use a persistent profile:
capture_auth_session(
profile_name="sso-session",
login_url="https://your-app.com/login",
success_url_pattern="/dashboard",
user_data_dir=".blop/chrome_profile_myapp"
)Option B — Manual export: Log in manually, export the session (e.g. Playwright or Chrome DevTools -> Application -> Storage), then:
save_auth_profile(
profile_name="sso-session",
auth_type="storage_state",
storage_state_path="/path/to/my-session.json"
)Canonical release-confidence resources:
blop://healthblop://journeysblop://release/{release_id}/briefblop://release/{release_id}/artifactsUse resources for cheap context retrieval before action:
blop://inventory/{app}blop://context-graph/{app}blop://run/{run_id}/artifact-indexblop://flow/{flow_id}/stability-profileUse v2 for release-level governance:
blop_v2_get_surface_contractblop_v2_assess_release_riskblop_v2_get_journey_healthblop_v2_cluster_incidents, blop_v2_generate_remediationblop_v2_get_correlation_reportDetailed resources and v2 references are provided below in the full reference sections.
The canonical release-confidence workflow uses:
validate_release_setupdiscover_critical_journeysrecord_test_flowrun_release_checktriage_release_blockerLegacy names such as validate_setup, discover_test_flows, and run_regression_test still appear below for compatibility context, but they should not be treated as the default path in new docs or prompts.
Recommended order for reliable MCP workflows:
validate_release_setupblop_v2_get_surface_contractexplore_site_inventory, get_page_structureblop://inventory/..., blop://context-graph/...discover_critical_journeys, record_test_flow, run_release_checktriage_release_blocker, get_run_health_stream, get_test_results, get_risk_analyticsDetailed tool behavior is below.
discover_critical_journeys — "What should gate this release?"Crawls your app and asks AI to figure out what the important user journeys are. Returns a list of suggested flows with descriptions of what to verify.
Basic usage:
discover_critical_journeys("https://your-app.com")With more context (gets better results):
discover_critical_journeys(
app_url="https://your-app.com",
business_goal="Find all revenue-critical flows like checkout and upgrade",
max_depth=2
)Parameters:
| Parameter | What it does | Example | |
|---|---|---|---|
app_url | The website to scan | "https://app.example.com" | |
business_goal | Tell it what matters most to your business or release scope | "Focus on checkout and onboarding" | |
profile_name | Use a logged-in account to scan private pages | "my-auth-profile" | |
max_depth | How deep to crawl (1 = homepage only, 2 = homepage + linked pages) | 2 | |
max_pages | Max pages to crawl before planning flows | 20 | |
seed_urls | Start crawl from specific same-origin URLs | ["https://app.example.com/pricing"] | |
include_url_pattern | Regex: only crawl URLs that match | `"/(pricing | signup)"` |
exclude_url_pattern | Regex: skip noisy URLs | `"/(blog | legal)"` |
What you get back: Journeys include business context and release-gating hints so you can decide what must be recorded and replayed before ship/no-ship decisions.
{
"flows": [
{
"flow_name": "user_login",
"goal": "User logs in with email and password and reaches the dashboard",
"severity_if_broken": "blocker",
"confidence": 0.92,
"business_criticality": "activation"
},
{
"flow_name": "pricing_page_upgrade",
"goal": "Visitor views pricing, clicks Pro plan CTA, reaches checkout",
"severity_if_broken": "high",
"confidence": 0.85,
"business_criticality": "revenue"
}
],
"inventory_summary": {
"auth_signals": ["sign in", "/login"],
"business_signals": ["pricing", "checkout"]
},
"quality": {
"passed": true,
"warnings": []
}
}explore_site_inventory — "Map the interface before planning tests"Runs inventory-only discovery (no Gemini flow planning) so you can inspect routes, forms, headings, auth signals, and business signals first. It now also includes page_structures, a compact per-page list of interactive ARIA nodes (role + name) to give agents layout context.
explore_site_inventory(
app_url="https://your-app.com",
max_depth=2,
max_pages=20,
include_url_pattern="/(pricing|signup|dashboard)"
)Use this when you want deterministic topology mapping before discover_critical_journeys.
get_page_structure — "Give me structure for one route right now"Captures a single-page interactive structure snapshot using Playwright's accessibility tree. Useful before recording or debugging when you want context for one URL without running a full crawl.
get_page_structure(
app_url="https://your-app.com",
url="https://your-app.com/pricing", # optional; defaults to app_url
profile_name="my-auth-profile" # optional
)Returns a flattened interactive_nodes list so MCP agents can reason about what controls are available before choosing actions.
save_auth_profile — "Here are my login credentials"Saves your login details so blop can test pages that require being signed in. Your password is only stored locally on your machine.
Basic usage (username + password from your .env file):
save_auth_profile(
profile_name="my-app-login",
auth_type="env_login",
login_url="https://your-app.com/login"
)Auth types explained:
| Type | When to use | Example |
|---|---|---|
env_login | You have a username + password | Standard email/password login |
storage_state | You have a browser session file from Playwright | SSO, OAuth, MFA flows |
cookie_json | You have exported browser cookies | When you can't automate login |
Tips:
storage_state or the interactive `capture_auth_session` tool (see below)user_data_dir when the login provider (e.g. Google, LinkedIn) blocks fresh browser contexts — blop will use a persistent Chromium profilecapture_auth_session — "Log in once in a browser, I'll save the session"Opens a visible browser at your login URL. You complete Google/GitHub OAuth, MFA, or any flow by hand. The tool polls the page URL every 500ms and, when it detects success, saves the Playwright storage state and creates an auth profile automatically. No manual session export needed.
Basic usage:
capture_auth_session(
profile_name="my-app-sso",
login_url="https://your-app.com/login",
success_url_pattern="/dashboard"
)Parameters:
| Parameter | What it does | Example |
|---|---|---|
profile_name | Name for the saved auth profile | "my-app-sso" |
login_url | URL to open (your app's login or OAuth start) | "https://app.example.com/login" |
success_url_pattern | URL substring that means "logged in" (optional) | "/dashboard" — if omitted, any URL change away from the login page counts as success |
timeout_secs | Max seconds to wait for you to complete login (default 120) | 180 |
user_data_dir | Path to a persistent Chromium profile dir (optional) | .blop/chrome_profile_myapp — use when OAuth providers treat a fresh browser as a bot |
Returns: status is "captured" (session saved, profile ready for record_test_flow and run_release_check) or "timeout" (no success detected in time). On success you get storage_state_path; the profile is already stored — just pass profile_name to other tools.
<a id="evaluate-web-task"></a>
evaluate_web_task — "Run one exploratory task and get a full report now"Runs a one-shot browser agent evaluation and returns results immediately in the same call. Use this for exploratory QA checks, quick validation, and ad-hoc investigation. If you want a reusable regression artifact (flow_id) for later replay, use record_test_flow instead.
Parameters:
| Parameter | Type | Default | Description | |
|---|---|---|---|---|
app_url | str | required | Base URL to test. | |
task | str | required | Natural-language objective for the agent. | |
profile_name | `str \ | null` | null | Optional saved auth profile to run as a logged-in user. |
headless | bool | false | Run browser headless or visible. | |
max_steps | int | 25 | Agent action budget before termination. | |
capture | `list[str] \ | null` | ["screenshots","console","network","trace"] | Evidence channels to persist (screenshots, console, network, trace). Invalid values are ignored. |
format | str | "markdown" | Output format: markdown, text, or json. | |
save_as_recorded_flow | bool | false | Whether to promote successful agent actions into a saved RecordedFlow. | |
flow_name | `str \ | null` | null | Optional flow name when save_as_recorded_flow=true. |
Return schema (high level):
status: "completed" on normal completion, otherwise error status.success: boolean pass/fail signal from evaluation outcome.pass_fail: normalized result (pass, fail, or error).metrics: execution stats such as elapsed time and step counts.agent_steps: normalized step summaries (step, action, description).evidence: logs/artifacts (console_errors, network_failures, screenshots, trace paths when captured).error: populated when input validation/auth/bootstrap/agent execution fails.report: formatted text/markdown block when format requests human-readable output.Side effects:
runs/...) when evidence capture is enabled.save_as_recorded_flow=true.Example call:
evaluate_web_task(
app_url="https://your-app.com",
task="Open pricing, click Pro plan CTA, and verify checkout loads",
profile_name="my-app-login",
max_steps=30,
capture=["screenshots", "console", "network"],
format="json"
)Example output (abridged):
{
"status": "completed",
"success": true,
"pass_fail": "pass",
"metrics": {"elapsed_secs": 18.4, "steps_taken": 9},
"agent_steps": [
{"step": 1, "action": "navigate", "description": "Navigate -> https://your-app.com/pricing"},
{"step": 2, "action": "click_element", "description": "Click element (index 4)"}
],
"evidence": {"console_errors": [], "network_failures": [], "screenshots": ["..."]},
"error": null
}record_test_flow — "Watch and learn this flow"Runs an AI agent in a real browser to accomplish a goal, and saves every step it takes. You can then replay this recording as many times as you want.
Use record_test_flow when you want a reusable regression artifact (flow_id). For one-off exploratory checks, use evaluate_web_task.
Basic usage:
record_test_flow(
app_url="https://your-app.com",
flow_name="user_signup",
goal="Sign up for a new account with email and verify the welcome screen appears"
)With authentication and business criticality (for flows behind login):
record_test_flow(
app_url="https://your-app.com",
flow_name="create_new_project",
goal="Log in, create a new project called 'Test Project', and verify it appears in the project list",
profile_name="my-app-login",
business_criticality="revenue"
)`business_criticality` (optional) is one of revenue, activation, retention, support, other. It is used in results and severity labels (e.g. "BLOCKER in revenue flow: checkout") so you can triage by business impact.
Writing good goals — what makes the difference:
| ❌ Vague (gets generic results) | ✅ Specific (gets reliable tests) |
|---|---|
"Test the login" | "Log in with email and password, verify the dashboard shows the user's name in the top right corner" |
"Check pricing" | "Navigate to pricing, verify Free, Pro ($35/mo), and Enterprise tiers are visible, click the Pro CTA and confirm it leads to checkout" |
"Test the form" | "Fill in the contact form with name, company email, and message, submit it, and verify a confirmation message appears" |
What gets captured per step:
run_release_check — "Can we ship this safely?"Replays recorded flows against your app and returns a release-confidence decision path. In replay mode it returns immediately with a run_id — poll for results with get_test_results. Run status moves: queued → running → (completed | failed | cancelled). If the auth profile cannot be resolved, status is waiting_auth and no flows run until you fix the profile and retry.
flow_ids must come from record_test_flow (or list_recorded_tests) and all IDs must be valid for the run to start.
Basic usage:
run_release_check(
app_url="https://your-app.com",
flow_ids=["abc123", "def456"]
)With auth and hybrid mode:
run_release_check(
app_url="https://your-app.com",
flow_ids=["abc123", "def456"],
profile_name="my-app-login",
mode="replay",
run_mode="hybrid"
)Run modes explained:
| Mode | What it does | When to use |
|---|---|---|
hybrid (default) | Tries saved steps first; if a selector breaks, AI repairs that single step | Best for most replay runs |
strict_steps | Follows saved steps exactly — fails immediately if anything doesn't match | CI/CD where you want strict enforcement |
goal_fallback | Ignores saved steps, replays using only the original goal description | Drift recovery only, not the normal release gate |
For release gating, prefer run_release_check(..., mode="replay") with recorded flow_ids. goal_fallback is useful for recovery and diagnosis when a recorded flow has drifted too far, but it should not be the default ship/no-ship path.
get_test_results — "What broke?"Polls a running test and returns structured results. Call it repeatedly every 2-5 seconds until status is "completed", "failed", "cancelled", or "waiting_auth". When status is waiting_auth, the response includes waiting_auth_message explaining that the auth profile could not be resolved (check credentials or re-run capture_auth_session if the session expired).
get_test_results("your-run-id-here")Understanding the results:
{
"status": "completed",
"severity_counts": {
"blocker": 1,
"high": 0,
"medium": 2,
"pass": 4
},
"failed_cases": [
{
"flow_name": "checkout_flow",
"severity": "blocker",
"replay_mode": "hybrid_repair",
"step_failure_index": 3,
"assertion_failures": ["Payment page should load after clicking Subscribe"],
"repro_steps": ["Go to /pricing", "Click 'Get Pro Plan'", "Observe: redirected to homepage instead of checkout"]
}
]
}Severity levels — what they mean for your business:
| Level | Meaning | Action |
|---|---|---|
| 🔴 blocker | Core workflow is completely broken. Users can't complete a key task. | Fix before shipping anything |
| 🟠 high | Major feature broken, significant user impact | Fix in current sprint |
| 🟡 medium | Partial issue, workaround possible | Fix in next sprint |
| 🟢 low | Cosmetic or edge case | Backlog |
| ✅ pass | Everything worked | No action needed |
`replay_mode` tells you how the test ran:
strict_steps — selector matched, step ran exactly as recordedhybrid_repair — original selector broke, AI found the element another waygoal_fallback — step-by-step replay failed entirely, fell back to full agent replayLook for replay trust cues in the response:
replay_trust_summary tells you whether replay stayed on the golden path or needs manual review.failure_classification explains whether the failure looks like auth, drift, infra, or product.stale_flow_guidance appears when an old recording should be refreshed before trusting the failure.list_runs — "What runs are active or recent?"Lists recent regression runs, optionally filtered by status.
list_runs(limit=20, status="running")Useful when you lost a run_id or need to inspect background runs.
get_run_health_stream — "What happened during this run, step by step?"Returns control-plane run events (queued, started, per-case completion, completed/failed) so you can inspect lifecycle and timing without opening artifacts first.
get_run_health_stream(
run_id="your-run-id",
limit=500 # optional
)Useful for quick triage when a run exits unexpectedly or when you want to inspect replay/healing metadata at event granularity.
get_risk_analytics — "Where are our biggest regression risks?"Aggregates recent runs into high-signal diagnostics:
business_criticality (revenue/activation/retention/support/other)get_risk_analytics(limit_runs=30)Use this to prioritize stabilization work across many runs instead of triaging one run at a time.
list_recorded_tests — "What tests do I have?"Compatibility-oriented listing of every recorded flow. For canonical planning context in the release workflow, prefer blop://journeys.
Lists every flow you've ever recorded.
list_recorded_tests()Returns a list with flow_id, flow_name, app_url, goal, and created_at. Use the flow_id values in run_release_check.
debug_test_case — "Why exactly did this fail?"Re-runs a specific failed case in a visible browser window (not headless), captures every screenshot, and generates a plain-English explanation of what went wrong.
debug_test_case(
run_id="your-run-id",
case_id="the-failed-case-id"
)What you get back:
{
"status": "fail",
"step_failure_index": 3,
"replay_mode": "hybrid_repair",
"assertion_failures": ["Dashboard should show user inbox after login"],
"why_failed": "The login succeeded but the session cookie was not persisted between the auth step and the dashboard navigation. The app redirected to /login again instead of /dashboard.",
"repro_steps": ["Navigate to /auth", "Fill email and password", "Click Sign In", "Session lost — redirect back to /auth"],
"screenshots": ["runs/screenshots/run123/case456/step_003.png"]
}validate_release_setup — "Is everything ready to gate a release?"Checks preconditions before you run flows: GOOGLE_API_KEY, Chromium installed, SQLite DB, optional app_url reachability, and optional auth profile (including whether a storage_state session is still valid). Use it after changing env vars or before a big run.
validate_release_setup(app_url="https://your-app.com", profile_name="my-app-login")Returns: status is "ready" (all checks passed), "warnings" (e.g. app URL unreachable but you can still run), or "blocked" (e.g. missing API key or Chromium). The checks array lists each condition and whether it passed; blockers and warnings give short messages. If an auth profile's session has expired, the message will suggest re-running capture_auth_session.
blop now exposes read-only MCP resources so agents can pull structured context without triggering heavy tool workflows.
blop://inventory/{app}Latest saved inventory for an app URL.
{app}.blop://inventory/https%3A%2F%2Fapp.example.comblop://context-graph/{app}Latest persisted SiteContextGraph snapshot (nodes, edges, archetype, freshness/confidence metadata).
blop://context-graph/https%3A%2F%2Fapp.example.comblop://run/{run_id}/artifact-indexArtifact index for a run (artifact metadata + case ids), useful before drilling into screenshots/traces.
blop://run/abc123/artifact-indexblop://flow/{flow_id}/stability-profileFlow-level stability profile derived from historical cases (pass/failure rates, replay-mode distribution, stability score).
blop://flow/def456/stability-profileinventory + context-graph resources.discover_critical_journeys/record_test_flow using that context.run_release_check.artifact-index + stability-profile.get_risk_analytics for cross-run prioritization.blop v2 expands beyond regression execution into change intelligence, journey health, incident clustering, and remediation orchestration.
blop_v2_get_surface_contract — returns machine-readable request/response schemas + examples for all v2 tools.blop_v2_capture_context — captures a context graph snapshot and structural diff summary.blop_v2_compare_context — compares two graph versions and returns structural/business impact.blop_v2_assess_release_risk — release-level risk score and top risks from context/run evidence.blop_v2_get_journey_health — SLO-like health view for business journeys over time.blop_v2_cluster_incidents — deduplicates failures into incident clusters with blast radius.blop_v2_generate_remediation — emits issue-ready remediation drafts (repro + evidence).blop_v2_ingest_telemetry_signals — ingests external signals (error rate/latency/conversion).blop_v2_get_correlation_report — correlates failures with telemetry changes for prioritization.blop://v2/contracts/toolsblop://v2/context/{urlencoded_app_url}/latestblop://v2/context/{urlencoded_app_url}/history/{limit}blop://v2/context/{urlencoded_app_url}/diff/{baseline_graph_id}/{candidate_graph_id}blop://v2/release/{release_id}/risk-summaryblop://v2/journey/{urlencoded_app_url}/health/{window} (window: 24h, 7d, 30d)blop://v2/incidents/{urlencoded_app_url}/openblop://v2/incident/{cluster_id}blop://v2/incident/{cluster_id}/remediation-draftblop://v2/correlation/{urlencoded_app_url}/{window}discover_test_flows, run_regression_test, validate_setup), but new workflows should prefer the canonical release-confidence surface.related_v2_resources links so agents can progressively adopt v2 context.{
"resource_version": "v2",
"generated_at": "2026-03-18T12:00:00Z",
"app_url": "https://app.example.com",
"data": {}
}Your .env file blop
─────────────────────────────────────────────────────────────
[email protected] → Reads at runtime
TEST_PASSWORD=secret → Never stored in DB
↓
Opens login page
Fills credentials
Saves session cookie
↓
.blop/auth_state_profile.json
(valid for 1 hour, then re-logs in)blop tries these login field selectors automatically, in order:
input[name="username"]input[name="email"]input[type="email"]#emailYou can override with env vars TEST_USERNAME_SELECTOR and TEST_PASSWORD_SELECTOR if your login form is unusual.
your-project/
├── .env ← Your credentials (never commit this)
├── .blop/
│ ├── runs.db ← All test history (SQLite)
│ └── auth_state_*.json ← Cached login sessions
└── runs/
├── screenshots/
│ └── <run_id>/<case_id>/
│ ├── step_000.png ← Screenshot at each step
│ └── step_001.png
├── traces/
│ └── <run_id>/<case_id>.zip ← Playwright trace (open with trace viewer)
└── console/
└── <run_id>/<case_id>.log ← Browser console errors"blop not found" or "command not found" Make sure you've activated the virtual environment: source .venv/bin/activate
"GOOGLE_API_KEY not set" Check your .env file exists in the blop-mcp folder and has your key on the GOOGLE_API_KEY= line. Alternatively, set it directly in the MCP config JSON.
Login keeps failing
TEST_USERNAME and TEST_PASSWORD in .envLOGIN_URL manually to confirm the credentials workTEST_USERNAME_SELECTOR=input[name="your-field"] to .envcapture_auth_session (opens a browser so you log in once; session is saved automatically) or auth_type="storage_state" with an exported session filevalidate_release_setup(profile_name="your-profile") to verify the profile; if the session expired, re-run capture_auth_session or refresh your storage state fileTests are all passing but you know something is broken The regression engine uses AI vision to evaluate assertions — it shouldn't produce false positives. If something is marked pass that looks wrong, use debug_test_case to re-run it with full screenshot capture and see what the browser actually showed.
"MCP server not connected" in Cursor
mcp.json points to where you actually cloned blop-mcpuv is installed (which uv in Terminal)The browser opens but does nothing / hangs Your BLOP_MAX_STEPS limit (default 50) may be too low for complex flows. Add BLOP_MAX_STEPS=100 to .env.
blop uses a deterministic-first architecture with adaptive repair fallback. For easier tuning across different interfaces, you can choose a profile:
BLOP_EXPLORATION_PROFILE=default — balanced defaults for most apps.BLOP_EXPLORATION_PROFILE=saas_marketing — tuned for async SPAs, heavy client-side editors, and cross-origin handoffs like rendley.com → app.rendley.com.You can still override individual knobs with env vars (BLOP_NETWORK_IDLE_WAIT, BLOP_SPA_SETTLE_MS, BLOP_AGENT_MAX_FAILURES, BLOP_AGENT_MAX_ACTIONS_PER_STEP, BLOP_DISCOVERY_MAX_PAGES).
Design baseline references:
| Variable | Required | Default | What it does |
|---|---|---|---|
GOOGLE_API_KEY | Yes | — | Gemini API key. Get one free at aistudio.google.com |
APP_BASE_URL | No | — | Default app URL (used as fallback if no URL passed to tools) |
LOGIN_URL | No | — | Where blop navigates to log in |
TEST_USERNAME | No | — | Login email/username |
TEST_PASSWORD | No | — | Login password |
TEST_USERNAME_SELECTOR | No | auto-detected | CSS selector for the username input field |
TEST_PASSWORD_SELECTOR | No | auto-detected | CSS selector for the password input field |
STORAGE_STATE_PATH | No | — | Path to a saved Playwright session (for SSO/OAuth) |
COOKIE_JSON_PATH | No | — | Path to exported browser cookies (JSON array) |
BLOP_DB_PATH | No | .blop/runs.db | Where blop stores its database |
BLOP_HEADLESS | No | true | false = show browser window during tests (useful for debugging) |
BLOP_MAX_STEPS | No | 50 | Max steps the AI agent takes per flow |
BLOP_ALLOW_SCREENSHOT_LLM | No | false | Privacy guard for visual-regression triage. When false, baseline/current screenshots are never base64-encoded or sent to external LLMs. |
BLOP_ENV | No | development | Environment mode (production enables stricter validation expectations) |
BLOP_REQUIRE_ABSOLUTE_PATHS | No | false (true in production recommended) | Require absolute paths for DB/runs/log values |
BLOP_ALLOW_INTERNAL_URLS | No | false | Block private/internal app URLs unless explicitly enabled |
BLOP_ALLOWED_HOSTS | No | — | Optional host allowlist for app_url validation |
BLOP_RUN_TIMEOUT_SECS | No | 0 | Total run timeout in seconds (0 disables timeout) |
BLOP_STEP_TIMEOUT_SECS | No | 45 | Per-step replay timeout in seconds |
BLOP_DEBUG_LOG | No | .blop/blop.log | JSON log destination path |
BLOP_CAPABILITIES_PROFILE | No | env-dependent | Predefined capability profile (production_minimal, production_debug, full) |
BLOP_ENABLE_COMPAT_TOOLS | No | false | Registers legacy/compat MCP tool surface when true |
BLOP_EXPLORATION_PROFILE | No | default | Tuning preset (default or saas_marketing) for discovery and replay behavior |
BLOP_DISCOVERY_MAX_PAGES | No | profile-driven | Default crawl page cap for discovery tools |
BLOP_AGENT_MAX_FAILURES | No | profile-driven | Max recoverable action failures before agent aborts recording |
BLOP_AGENT_MAX_ACTIONS_PER_STEP | No | profile-driven | Max agent actions per reasoning step during recording |
BLOP_NETWORK_IDLE_WAIT | No | 2.0 | Seconds to wait for network idle after page load (increase for WebGL/WASM or slow dashboards) |
BLOP_SPA_SETTLE_MS | No | 1500 | Extra settle time in ms after SPA navigation (for pushState / client-side routing) |
Powered by Browser Use and Google Gemini
blop was initially developed as a fork of browser-use/vibetest-use. The codebase has since been entirely rewritten with a new architecture, engine, tool surface, and storage layer. This repository (blop-mcp) is the canonical home for blop going forward.
If the upstream vibetest-use project's license requires attribution, see the upstream repository for license details.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.