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

# How to Add a CAPTCHA Solver Tool to Ruflo

A runnable, fixture-first stdio MCP companion tool with one recovery attempt, bounded polling, structured 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 Ruflo workflow encounters a CAPTCHA interruption, it needs a bounded recovery tool that either returns a validated result or stops for human review. This companion MCP server shows how a Ruflo task can call [CapSolver](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=ruflo-captcha-solver-mcp-tool&utm_content=repository-readme) only after explicit authorization and a supported challenge signal. It does not modify Ruflo or claim an official partnership. The API task object remains caller-reviewed so the example does not invent product fields.

## Features

- One MCP tool: `captcha_solver_recover_once`
- Explicit authorization and challenge gates
- Stable recovery ID for idempotency
- One create call and at most five result polls
- Timeouts, structured errors, and human handoff
- Offline fixtures; no real key or target required

## How It Works

Ruflo routes an approved task to the local stdio server. The tool validates authorization, challenge state, context, and budget before using the official task creation contract. It accepts only a ready solution, otherwise it polls within the configured budget and stops safely.

## Architecture

`Ruflo → MCP tools/call → policy gates → CapSolver client → result validator → resume or human handoff`

## Quick Start

```bash
npm test
npm run smoke
CAPSOLVER_API_KEY=replace_me npm start
```

In Ruflo's Web UI, open **MCP (n) → Add Server**, select a stdio server, and use `node src/server.js` as the local command. Ruflo also documents HTTP and SSE endpoints; this repository intentionally implements only stdio.

## Usage

Use `examples/tool-call.json` as the fixture shape. Replace `task` only with a task object reviewed against 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","recoveryId":"qa-run-0001","polls":1,"solution":{"fixtureResult":"ok"}}
```

## Supported Scenarios

Owned test fixtures, explicitly authorized QA, and proportionate automation against approved targets. Unsupported states stop for human review.

## Project Structure

- `src/server.js` — stdio JSON-RPC router
- `src/tool.js` — MCP tool definition and safe error mapping
- `src/recovery.js` — bounded recovery contract
- `tests/` — offline unit tests
- `examples/` — fixture-only tool call

## Testing

```bash
npm test
npm run smoke
```

The tests use injected clients and never call a live API.

## Troubleshooting

`AUTHORIZATION_REQUIRED`, `NO_SUPPORTED_CHALLENGE`, `DUPLICATE_RECOVERY`, `TIMEOUT`, and `BUDGET_EXHAUSTED` are stop signals. Review the task and hand it to a human instead of retrying indefinitely.

## Responsible Use

Use only public data, owned systems, or targets covered by explicit written authorization. Respect access policies, terms, rate limits, retention limits, and human stop decisions. Do not use this example for private data, credentials, sensitive personal information, unrestricted collection, or unauthorized access.

## Contributing

Keep changes fixture-first, bounded, and fail-closed. Run both checks before a pull request.

## Security

Never commit keys, cookies, browser profiles, private target URLs, or production responses. See `SECURITY.md`.

## Conclusion

This companion tool gives Ruflo a small, auditable recovery boundary while keeping routing, budgets, validation, and human control explicit. For an authorized production adapter, confirm every task field against [CapSolver](https://www.capsolver.com/?utm_source=github&utm_medium=referral&utm_campaign=ruflo-captcha-solver-mcp-tool&utm_content=repository-readme) documentation before use.

## Maintainer Note

Developer sharing CapSolver integration examples.

## License

MIT