![How to Add a CAPTCHA Solver Tool Alongside Obscura MCP](assets/cover.png)

# How to Add a CAPTCHA Solver Tool Alongside Obscura MCP

[English](README.md) · [简体中文](docs/zh-CN/README.md) · [日本語](docs/ja/README.md) · [Español](docs/es/README.md) · [Português](docs/pt-BR/README.md) · [한국어](docs/ko/README.md)

## 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](https://github.com/h4ckf0r0day/obscura) for the stateful browser session and use [CapSolver](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=obscura-capsolver-tool&utm_content=repository-readme) 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

```text
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

```bash
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`](examples/mcp-client-config.json). Start the companion directly with:

```bash
python -m obscura_capsolver_tool.mcp_server
```

## Usage

Call `browser_snapshot` first, then send one authorized checkpoint:

```json
{
  "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](https://docs.capsolver.com/en/guide/what-is-capsolver/), [task creation contract](https://docs.capsolver.com/en/guide/api-createtask/), and [task result contract](https://docs.capsolver.com/en/guide/api-gettaskresult/).

## Example Output

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

## Project Structure

```text
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`](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](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=obscura-capsolver-tool&utm_content=repository-readme) integration guidance.

## Maintainer Note

Developer sharing CapSolver integration examples.

## License

MIT. See [`LICENSE`](LICENSE).