rea-captcha

MCP local stdio para evidencia de verificación de navegador y reanudación en la misma sesión. Análisis sin configuración; las acciones de navegador configuradas se limitan a claves de prueba oficiales del proveedor y flujos propios.

GitHub
1

Documentación

English · العربية · Deutsch · Ελληνικά · Español · فارسی · Français · Bahasa Indonesia · Italiano · 日本語 · 한국어 · Polski · Português (Brasil) · Русский · ไทย · Türkçe · Українська · Tiếng Việt · 简体中文 · 繁體中文

rea-captcha

Inteligencia de verificación de desafíos local-primero para agentes de navegador.

npm CI Provider web demos Live demo MCP Registry MCP tools skills.sh Discord license

Instalación · Demo en vivo · Matriz agéntica · Cómo funciona · Catálogo MCP · Casos · Arquitectura

Cuando una tarea de Browser Use encuentra un CAPTCHA a mitad de camino, rea-captcha mantiene el bloqueo y la recuperación dentro de la sesión del navegador que el agente ya posee. Detecta desafíos de verificación compatibles, coordina una acción autorizada o una transferencia humana, requiere evidencia fresca validada por el servidor y luego devuelve el control a la misma tarea. Incluye un SDK de TypeScript, un servidor MCP stdio local, un plugin de browser-use, una Agent Skill compatible con Vercel y un OCR local opcional de origen autorizado.

Fuente oficial: instala desde masakaai/rea-captcha y el paquete npm rea-captcha. El proyecto no tiene solucionador alojado, telemetría, afirmación de sigilo ni dependencia de Jet Browser. Reutiliza el navegador existente del agente; los ejemplos de proveedores usan solo credenciales documentadas de no producción.

Ejecuta los cuatro casos de verificación en vivo

Matriz de verificación agéntica

Google reCAPTCHA v2
Agent completes Google reCAPTCHA test mode, validates, and resumes 		Cloudflare Turnstile
Agent completes Cloudflare Turnstile test mode, validates, and resumes
hCaptcha
Agent completes hCaptcha test mode, validates, and resumes 		Imagen/texto propio
Agent completes owned image text verification, validates, and resumes

Estos son flujos completos de acciones protegidas impulsadas por agentes, no solo accesorios de DOM. Cada ejecución detecta un desafío, realiza la interacción autorizada del navegador en la misma página, envía al límite de validación real, observa evidencia fresca de aprobación, verifica la cookie de sesión y reanuda el mismo controlador. Google reCAPTCHA v2, Cloudflare Turnstile y hCaptcha usan sus modos de prueba documentados más los endpoints de Siteverify del proveedor; el caso de imagen/texto propio usa una ruta local explícitamente autorizada y validación del servidor local.

Los primeros tres casos cargan JavaScript alojado por el proveedor y aceptan la acción protegida solo después de que el servidor recibe success: true del endpoint de verificación del proveedor. Usan las credenciales documentadas de no producción de los proveedores: claves de prueba de Google, claves ficticias de Cloudflare y claves de prueba de hCaptcha.

npm run demo:web       # interactive local demo
npm run test:web-demo  # all four live validation paths

Instalación

Pega una oración en Codex, Claude Code, Cursor u otro agente de codificación:

Install rea-captcha in this project and connect it to the browser session this agent already uses.

Cómo funciona

rea-captcha lifecycle: inspect evidence, apply policy, perform an authorized agent action in the same browser session, verify fresh clearance, and resume the same task

MCP y agentes de codificación

La entrada oficial del Registro es io.github.masakaai/rea-captcha y lanza el servidor stdio de configuración cero a través de npm:

npx rea-captcha@0.2.4 mcp --stateless

Revisa la versión fijada del paquete y aprueba el aviso de instalación de npm solo cuando coincida con la versión que pretendes ejecutar. El comando no suprime ese aviso.

Expone seis herramientas: captcha_analyze, captcha_inspect, captcha_complete, captcha_handoff, captcha_wait y captcha_resume. captcha_complete realiza solo una acción autorizada por política en el navegador existente configurado y espera evidencia fresca de validación. Consulta el catálogo de herramientas para entradas y semántica del ciclo de vida.

Para una sesión local con estado, ejecuta la configuración e imprime una configuración de host:

npx rea-captcha agent-config --agent codex
npx rea-captcha agent-config --agent mcp-json

rea-captcha agrega inteligencia de verificación y acciones de finalización acotadas; no reemplaza las herramientas de navegación de un agente. Ambas integraciones deben referirse a la misma sesión del navegador.

Los usuarios de Hermes Agent pueden inspeccionar el paquete Portable Agent Plugins v1. Su valor predeterminado seguro para catálogo es análisis de evidencia sin estado; las acciones del navegador en la misma sesión aún requieren una configuración explícita de rea-captcha con estado.

SDK de TypeScript

import { ChallengeController, ChallengePolicy } from 'rea-captcha';
import { PlaywrightChallengeAdapter } from 'rea-captcha/playwright';

const authorizedOrigin = 'https://fixture.example';
const controller = new ChallengeController({
  browser: new PlaywrightChallengeAdapter({
    id: 'checkout',
    page,
    agentActions: {
      authorizedOrigins: [authorizedOrigin],
      allowProviderTestAutomation: true,
      submitSelector: 'button[type="submit"]'
    }
  }),
  policy: new ChallengePolicy({
    authorizedOrigins: [authorizedOrigin],
    allowProviderTestAutomation: true
  })
});

const inspection = await controller.inspect();
if (inspection.policy.decision === 'agent-action' || inspection.policy.decision === 'local-processing') {
  await controller.complete({ timeoutMs: 30_000 });
  await controller.resume();
}

El controlador toma prestado page; no crea ni cierra el navegador.

Proveedores de navegador

El proveedor recomendado entre agentes es un navegador que ya expone CDP:

{
  "version": 1,
  "sessions": {
    "local-chrome": {
      "adapter": "playwright-cdp",
      "endpoint": "http://127.0.0.1:9222",
      "allowProviderTestAutomation": true,
      "submitSelector": "button[type=submit]",
      "authorizedOrigins": ["https://fixture.example"]
    }
  }
}

Se implementan adaptadores genéricos de Playwright Page, Playwright sobre CDP, browser-use y adaptadores opcionales de Jet Browser administrado/independiente. Jet Browser debe seleccionarse explícitamente y no se instala ni se inicia por la ruta predeterminada. Los ejemplos de configuración y los límites de proveedores están documentados en arquitectura y casos.

browser-use y OCR local

Instala el adaptador de Python alineado con la versión desde la fuente etiquetada del repositorio:

python -m pip install 'rea-captcha[browser-use] @ git+https://github.com/masakaai/rea-captcha.git@v0.2.4#subdirectory=python'

El adaptador de Python aún no está publicado en PyPI, por lo que un pip install rea-captcha sin calificar no funcionará. La instalación de fuente fijada mantiene el adaptador y la versión del repositorio alineados sin depender de una distribución no publicada.

Para la finalización impulsada por el agente, apunta la sesión de Playwright/CDP de rea-captcha al mismo navegador existente que usa browser-use. El ciclo de vida de MCP detecta el bloqueo, realiza una acción autorizada, verifica el resultado y devuelve el control sin reemplazar el navegador ni el contexto de la tarea.

El plugin de Python sigue siendo un respaldo ligero de detección y recuperación manual para integraciones de browser-use que no exponen una superficie de acción CDP compatible:

from browser_use import Agent
from rea_captcha import ChallengePlugin

agent = Agent(task="Complete the authorized workflow", llm=llm)
challenge = ChallengePlugin(mode="local", human_handoff=True)
await challenge.attach(agent)

El ddddocr local es un primitivo opcional solo para desafíos simples de imagen/texto en un origen autorizado exacto. Está deshabilitado a menos que se configuren tanto allowLocalImageText como authorizedOrigins. No se redistribuyen pesos de modelos, y una predicción de OCR sigue siendo evidencia no confiable.

Qué está implementado

  • Detección de evidencia para reCAPTCHA, hCaptcha, Turnstile, GeeTest, DataDome, PerimeterX, AWS WAF, entradas de imagen/texto y páginas de verificación genéricas.
  • Estados deterministas con tiempo de espera acotado, cancelación y verificaciones de reanudación de evidencia fresca.
  • Seis herramientas MCP stdio, paridad CLI/MCP, SDK de TypeScript, enlaces de browser-use y una Agent Skill compatible con Vercel.
  • Sesiones prestadas de Playwright/CDP más adaptadores opcionales de Jet Browser.
  • Eventos JSONL locales con propiedad explícita y sin telemetría.
  • Flujo de trabajo de publicación de confianza/procedencia de npm y publicación OIDC de GitHub al Registro MCP oficial.

Documentación

Comunidad

Únete al Discord de MASAKA y luego usa el canal dedicado #rea-captcha para discusión de integración y ejemplos de agentes en la misma sesión. Usa GitHub Issues para errores reproducibles y sigue la política de seguridad privada para vulnerabilidades. Nunca publiques perfiles de navegador, cookies, tokens de desafío, claves de API ni evidencia de páginas privadas.

Alcance y descargo de responsabilidad

rea-captcha es para flujos de trabajo propios o explícitamente autorizados. La automatización de proveedores se acepta solo cuando el adaptador confirma la clave de prueba de no producción documentada del proveedor. No elude la protección interactiva de producción. Las API de solucionadores comerciales, la transferencia de credenciales, las afirmaciones de sigilo y la finalización automática de desafíos de producción de terceros están fuera del alcance.

Inspirado en morluto/rea.

Licencia

El código central y las integraciones tienen licencia MIT. Las dependencias opcionales y los artefactos de modelos mantienen sus propios términos; consulta Avisos de terceros y licencias de modelos.