How to Add a CAPTCHA Solver Tool Alongside Obscura MCP

English · 简体中文 · 日本語 · Español · Português · 한국어

Introduction

When an authorized AI-agent browser task reaches a CAPTCHA checkpoint, an operator needs a controlled decision instead of an open-ended retry loop. This repository shows how an MCP client can run Obscura for the stateful browser session and use CapSolver through a separate, bounded checkpoint tool.

Obscura exposes browser tools through MCP, but it does not advertise a third-party tool plugin interface. This example therefore runs as an independent companion MCP server configured alongside Obscura. It does not modify the browser engine or claim a native integration.

Features

• accepts structured state from the current Obscura browser_snapshot result;

• requires explicit authorization and a matching snapshot origin;

• supports one attempt with a configurable timeout capped at 120 seconds;

• validates a ready solver result before returning a token;

• returns a structured manual_review state for every unsafe or ambiguous branch;

• uses fixtures only in tests and makes no real browser or solver request.

How It Works

1. The agent uses Obscura MCP tools to navigate and inspect an authorized target.

2. A supported verification checkpoint is detected.

3. The agent passes the browser session ID, snapshot URL, origin, purpose authorization, and challenge type to this companion tool.

4. Policy checks run before any solver transport is allowed.

5. One bounded attempt may run; malformed, denied, exhausted, or timed-out work stops for a person.

Architecture

MCP-capable agent
 ├─ Obscura MCP → stateful browser_* tools
 └─ this MCP server → authorization → bounded solver transport → validated status

The two servers share only structured task context supplied by the agent. This repository does not read browser cookies, profiles, or saved credentials.

Quick Start

python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -v
python scripts/smoke.py

Add both servers to an MCP-capable client using examples/mcp-client-config.json. Start the companion directly with:

python -m obscura_capsolver_tool.mcp_server

Usage

Call browser_snapshot first, then send one authorized checkpoint:

{
  "task_id": "authorized-qa-42",
  "origin": "https://example.test",
  "snapshot_url": "https://example.test",
  "browser_session_id": "obscura-local-1",
  "challenge_type": "recaptcha_v2",
  "authorized": true,
  "attempt": 0,
  "timeout_seconds": 45
}

The offline fixture returns either solved or manual_review. Production transport code should follow the official CapSolver API overview, task creation contract, and task result contract.

Example Output

{
  "status": "solved",
  "task_id": "authorized-qa-42",
  "browser_session_id": "obscura-local-1",
  "attempts_used": 1,
  "token": "fixture-token"
}

Project Structure

src/obscura_capsolver_tool/  policy, handler, and stdio MCP server
examples/                    dual-server MCP client configuration
tests/                       offline policy and protocol tests
scripts/                     smoke test
docs/                        five translated guides

Testing

The suite covers authorization denial, attempt exhaustion, invalid results, session/origin binding, MCP tool discovery, and the successful fixture path. It does not run Obscura or make a real CapSolver API request.

Responsible Use

Use this example only with public data, systems you own, or targets where you have explicit permission. Respect site terms, rate limits, privacy requirements, and retention policies. Do not use it for bulk account creation, access controls, private data, credential collection, or avoiding platform safeguards. Stop for human review whenever authorization, target ownership, challenge state, or result validity is unclear.

Security

Never commit API keys, session state, cookies, tokens, or captured private content. See SECURITY.md for reporting guidance.

Conclusion

This companion pattern keeps Obscura browser control separate from solver policy while preserving authorization, session binding, attempt budgets, validation, and human stopping. Replace the fixture transport only after reviewing the current official CapSolver integration guidance.

Maintainer Note

Developer sharing CapSolver integration examples.

License

MIT. See LICENSE.