A runnable, fixture-first stdio MCP companion tool with one recovery attempt, bounded polling, structured validation, and human handoff.
English · 简体中文 · 日本語 · Español · Português · 한국어
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.
- 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
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.
Ruflo → MCP tools/call → policy gates → CapSolver client → result validator → resume or human handoff
npm test
npm run smoke
CAPSOLVER_API_KEY=replace_me npm startIn 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.
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.
{"ok":true,"status":"ready","recoveryId":"qa-run-0001","polls":1,"solution":{"fixtureResult":"ok"}}Owned test fixtures, explicitly authorized QA, and proportionate automation against approved targets. Unsupported states stop for human review.
src/server.js— stdio JSON-RPC routersrc/tool.js— MCP tool definition and safe error mappingsrc/recovery.js— bounded recovery contracttests/— offline unit testsexamples/— fixture-only tool call
npm test
npm run smokeThe tests use injected clients and never call a live API.
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.
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.
Keep changes fixture-first, bounded, and fail-closed. Run both checks before a pull request.
Never commit keys, cookies, browser profiles, private target URLs, or production responses. See SECURITY.md.
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.
Developer sharing CapSolver integration examples.
MIT