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

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

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

Example Output

{"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

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

Maintainer Note

Developer sharing CapSolver integration examples.

License

MIT