如何为 Ruflo 添加 CAPTCHA 求解器工具

一个可运行的、夹具优先的 stdio MCP 配套工具，具有一次恢复尝试、有界轮询、结构化验证和人工交接功能。

English · 简体中文 · 日本語 · Español · Português · 한국어

简介

当经过授权的 Ruflo 工作流遇到 CAPTCHA 中断时，它需要一个有界的恢复工具，要么返回验证结果，要么停止等待人工审查。这个配套 MCP 服务器展示了 Ruflo 任务如何在获得明确授权和支持的挑战信号之后才调用 CapSolver。它不会修改 Ruflo，也不声称是官方合作伙伴。API 任务对象仍由调用方审查，因此该示例不会虚构产品字段。

功能特性

• 一个 MCP 工具：captcha_solver_recover_once

• 明确的授权和挑战门控

• 稳定的恢复 ID 以实现幂等性

• 一次创建调用和最多五次结果轮询

• 超时、结构化错误和人工交接

• 离线夹具；无需真实密钥或目标

工作原理

Ruflo 将已批准的任务路由到本地 stdio 服务器。该工具在使用官方任务创建契约之前，会验证授权、挑战状态、上下文和预算。它只接受已就绪的解决方案，否则会在配置的预算内轮询并安全停止。

架构

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 start

在 Ruflo 的 Web UI 中，打开 MCP (n) → Add Server，选择 stdio 服务器，并使用 node src/server.js 作为本地命令。Ruflo 还记录了 HTTP 和 SSE 端点；本仓库有意只实现 stdio。

使用方法

使用 examples/tool-call.json 作为夹具形状。仅将 task 替换为根据官方 createTask 请求契约审查过的任务对象。结果轮询遵循官方 getTaskResult 生命周期。

示例输出

{"ok":true,"status":"ready","recoveryId":"qa-run-0001","polls":1,"solution":{"fixtureResult":"ok"}}

支持的场景

自有测试夹具、明确授权的 QA，以及针对已批准目标的适度自动化。不支持的状态会停止等待人工审查。

项目结构

• src/server.js — stdio JSON-RPC 路由器

• src/tool.js — MCP 工具定义和安全错误映射

• src/recovery.js — 有界恢复契约

• tests/ — 离线单元测试

• examples/ — 仅夹具工具调用

测试

npm test
npm run smoke

测试使用注入的客户端，从不调用真实 API。

故障排除

AUTHORIZATION_REQUIRED、NO_SUPPORTED_CHALLENGE、DUPLICATE_RECOVERY、TIMEOUT 和 BUDGET_EXHAUSTED 是停止信号。请审查任务并交给人工处理，而不是无限重试。

负责任的使用

仅使用公共数据、自有系统或明确书面授权涵盖的目标。尊重访问策略、条款、速率限制、保留限制和人工停止决定。请勿将此示例用于私人数据、凭据、敏感个人信息、无限制收集或未经授权的访问。

贡献

保持更改以夹具为先、有界且故障关闭。在提交拉取请求之前运行两项检查。

安全

切勿提交密钥、Cookie、浏览器配置文件、私有目标 URL 或生产响应。请参阅 SECURITY.md。

结论

这个配套工具为 Ruflo 提供了一个小而可审计的恢复边界，同时保持路由、预算、验证和人工控制的明确性。对于授权的生产适配器，请在使用前根据 CapSolver 文档确认每个任务字段。

维护者说明

分享 CapSolver 集成示例的开发者。

许可证

MIT