<p align="center"><img src="assets/cover.png" alt="How to Add a CAPTCHA Solver Extension to goose" width="100%"></p>

# How to Add a CAPTCHA Solver Extension to goose

A runnable, fixture-first goose MCP extension with one controlled recovery, bounded polling, result validation, and human handoff.

English · [简体中文](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 goose agent reaches a CAPTCHA interruption, it needs a small recovery component with clear limits and a human fallback. This example introduces [CapSolver](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=goose-capsolver-mcp-extension&utm_content=repository-readme) only after explicit authorization and a supported challenge signal. It does not modify goose or claim an official partnership.

## Features

- Framework-native goose MCP extension surface
- Authorization and challenge gates
- Stable recovery ID and duplicate protection
- One create call and at most five polls
- Structured stop codes and human handoff
- Offline fixtures with no real key or target

## How It Works

The adapter receives approved task context, validates policy gates and the retry budget, calls a transport matching the official task lifecycle, validates the structured result, and either resumes once or stops for human review.

## Architecture

`goose → adapter → policy gates → recovery client → validated result or human handoff`

## Quick Start

```bash
python -m unittest discover -s tests -q\npython scripts/smoke_test.py
```

## Usage

Use the fixture in `examples/` and replace its `task` only after checking the [official createTask request contract](https://docs.capsolver.com/en/guide/api-createtask/). Result polling follows the [official getTaskResult lifecycle](https://docs.capsolver.com/en/guide/api-gettaskresult/).

## Example Output

```json
{"ok":true,"status":"ready","polls":1,"solution":{"fixtureResult":"ok"}}
```

## Supported Scenarios

Owned test fixtures, explicitly authorized QA, and proportionate automation against approved targets.

## Project Structure

- `src/` — recovery core and framework adapter
- `tests/` — offline unit tests
- `examples/` — safe fixture
- `scripts/` — smoke test

## Testing

All tests inject a fixture client and make no live API call.

## Troubleshooting

Authorization, unsupported challenge, duplicate context, malformed response, timeout, and exhausted budget are stop conditions—not reasons for unlimited retries.

## Responsible Use

Use only public data, owned systems, or targets covered by explicit written authorization. Respect terms, access policies, rate limits, minimization, and retention rules. Never use this example for private data, credentials, sensitive personal data, unlimited collection, or unauthorized access.

## Contributing

Keep changes bounded, fixture-first, and fail-closed.

## Security

Never commit keys, sessions, browser profiles, private targets, or production responses. See `SECURITY.md`.

## Conclusion

This goose MCP extension keeps recovery narrow, testable, and controlled by the caller. Verify every production task field against [CapSolver](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=goose-capsolver-mcp-extension&utm_content=repository-readme) documentation before authorized use.

## Maintainer Note

Developer sharing CapSolver integration examples.

## License

MIT