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 · 简体中文 · 日本語 · Español · Português · 한국어

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 only after explicit authorization and a supported challenge signal. It does not modify goose or claim an official partnership.

Related MCP server: sessemi-mcp

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

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. Result polling follows the official getTaskResult lifecycle.

Example Output

{"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 documentation before authorized use.

Maintainer Note

Developer sharing CapSolver integration examples.

License

MIT