Skip to main content
Glama
ruflo-captcha-solver-mcp-tool

ruflo-captcha-solver-mcp-tool

by normal-sugar

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.

Related MCP server: M365 Copilot Web Bridge

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

Available Tools

1 tool
captcha_solver_recover_onceC

Perform one bounded CAPTCHA recovery for an explicitly authorized Ruflo task.

Inputs: task (required), context (required), authorization (required), challengeDetected (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusion between tools. The tool's purpose is specific (recover once) even if the underlying 'Ruflo task' is opaque.

    Naming Consistency5/5

    With a single tool, naming consistency is trivially maintained. The name 'captcha_solver_recover_once' follows a clear verb_noun_adverb pattern without conflicting conventions.

    Tool Count2/5

    A single tool is far too few for a CAPTCHA solver domain. Typical workflows require multiple operations (solve, verify, status), so this feels like a deliberately minimal or unfinished server.

    Completeness1/5

    The sole tool covers a narrow 'recover once' action, but lacks standard CAPTCHA operations like solving, verification, or result retrieval. The surface is severely incomplete for the stated purpose.

    Related MCP Connectors

    Related MCP Servers