Cómo añadir una herramienta de resolución de CAPTCHA a Ruflo

Una herramienta complementaria MCP stdio ejecutable que prioriza los fixtures, con un intento de recuperación, sondeo acotado, validación estructurada y traspaso a un humano.

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

Introducción

Cuando un flujo de trabajo autorizado de Ruflo encuentra una interrupción por CAPTCHA, necesita una herramienta de recuperación acotada que devuelva un resultado validado o se detenga para revisión humana. Este servidor MCP complementario muestra cómo una tarea de Ruflo puede llamar a CapSolver solo después de una autorización explícita y de una señal de desafío admitida. No modifica Ruflo ni afirma ninguna asociación oficial. El objeto de tarea de la API sigue siendo revisado por quien llama, de modo que el ejemplo no inventa campos del producto.

Características

• Una herramienta MCP: captcha_solver_recover_once

• Controles explícitos de autorización y de desafío

• ID de recuperación estable para idempotencia

• Una llamada de creación y un máximo de cinco sondeos de resultado

• Tiempos de espera, errores estructurados y traspaso a un humano

• Fixtures sin conexión; no se requiere ninguna clave ni objetivo reales

Cómo funciona

Ruflo enruta una tarea aprobada al servidor stdio local. La herramienta valida la autorización, el estado del desafío, el contexto y el presupuesto antes de usar el contrato oficial de creación de tareas. Solo acepta una solución lista; de lo contrario, sondea dentro del presupuesto configurado y se detiene de forma segura.

Arquitectura

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

Inicio rápido

npm test
npm run smoke
CAPSOLVER_API_KEY=replace_me npm start

En la interfaz web de Ruflo, abre MCP (n) → Añadir servidor, selecciona un servidor stdio y usa node src/server.js como comando local. Ruflo también documenta endpoints HTTP y SSE; este repositorio implementa deliberadamente solo stdio.

Uso

Usa examples/tool-call.json como plantilla de fixture. Reemplaza task únicamente con un objeto de tarea revisado según el contrato oficial de la solicitud createTask. El sondeo de resultados sigue el ciclo de vida oficial de getTaskResult.

Ejemplo de salida

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

Escenarios admitidos

Fixtures de prueba propios, QA explícitamente autorizado y automatización proporcionada contra objetivos aprobados. Los estados no admitidos se detienen para revisión humana.

Estructura del proyecto

• src/server.js — enrutador stdio JSON-RPC

• src/tool.js — definición de la herramienta MCP y mapeo seguro de errores

• src/recovery.js — contrato de recuperación acotado

• tests/ — pruebas unitarias sin conexión

• examples/ — llamada a la herramienta con solo fixtures

Pruebas

npm test
npm run smoke

Las pruebas utilizan clientes inyectados y nunca llaman a una API real.

Solución de problemas

AUTHORIZATION_REQUIRED, NO_SUPPORTED_CHALLENGE, DUPLICATE_RECOVERY, TIMEOUT y BUDGET_EXHAUSTED son señales de detención. Revisa la tarea y traspásala a un humano en lugar de reintentar indefinidamente.

Uso responsable

Usa únicamente datos públicos, sistemas propios u objetivos cubiertos por una autorización escrita explícita. Respeta las políticas de acceso, los términos, los límites de frecuencia, los límites de retención y las decisiones humanas de detención. No uses este ejemplo para datos privados, credenciales, información personal sensible, recopilación sin restricciones ni acceso no autorizado.

Contribuciones

Mantén los cambios que prioricen los fixtures, sean acotados y cierren ante fallos. Ejecuta ambas comprobaciones antes de enviar un pull request.

Seguridad

Nunca confirmes claves, cookies, perfiles de navegador, URLs de objetivos privados ni respuestas de producción. Consulta SECURITY.md.

Conclusión

Esta herramienta complementaria proporciona a Ruflo un pequeño límite de recuperación auditable, al tiempo que mantiene explícitos el enrutamiento, los presupuestos, la validación y el control humano. Para un adaptador de producción autorizado, confirma cada campo de la tarea contra la documentación de CapSolver antes de usarlo.

Nota del mantenedor

Desarrollador que comparte ejemplos de integración con CapSolver.

Licencia

MIT