rea-captcha

MCP stdio local para evidência de verificação de navegador e retomada na mesma sessão. Análise sem configuração; ações de navegador configuradas são limitadas a chaves de teste oficiais do provedor e fluxos próprios.

GitHub
1

Documentação

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

rea-captcha

Inteligência de desafios de verificação local-first para agentes de navegador.

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

Instalar · Demonstração ao vivo · Matriz agêntica · Como funciona · Catálogo MCP · Casos · Arquitetura

Quando uma tarefa de Browser Use encontra um CAPTCHA no meio do caminho, o rea-captcha mantém o bloqueio e a recuperação dentro da sessão de navegador que o agente já possui. Ele detecta desafios de verificação suportados, coordena uma ação autorizada ou transferência humana, exige evidências novas validadas pelo servidor e, em seguida, devolve o controle à mesma tarefa. Ele inclui um SDK TypeScript, servidor MCP stdio local, plugin browser-use, Agent Skill compatível com Vercel e OCR local opcional de origem autorizada.

Fonte oficial: instale a partir de masakaai/rea-captcha e do pacote npm rea-captcha. O projeto não possui solucionador hospedado, telemetria, alegação de stealth ou dependência do Jet Browser. Ele reutiliza o navegador existente do agente; os exemplos de provedores usam apenas credenciais documentadas de não produção.

Execute os quatro casos de verificação ao vivo

Matriz de verificação 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 		Imagem/texto próprio
Agent completes owned image text verification, validates, and resumes

Estes são fluxos completos de ações protegidas conduzidos por agente, não apenas fixtures de DOM. Cada execução detecta um desafio, realiza a interação autorizada no navegador na mesma página, envia para o limite de validação real, observa novas evidências aprovadas, verifica o cookie de sessão e retoma o mesmo controlador. Google reCAPTCHA v2, Cloudflare Turnstile e hCaptcha usam seus modos de teste documentados mais endpoints Siteverify do fornecedor; o caso de imagem/texto próprio usa um caminho local explicitamente autorizado e validação local do servidor.

Os três primeiros casos carregam JavaScript hospedado pelo fornecedor e aceitam a ação protegida somente após o servidor receber success: true do endpoint de verificação do fornecedor. Eles usam as credenciais documentadas de não produção dos fornecedores: chaves de teste do Google, chaves fictícias do Cloudflare e chaves de teste do hCaptcha.

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

Instalar

Cole uma frase no Codex, Claude Code, Cursor ou outro agente de codificação:

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

Como 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 e agentes de codificação

A entrada oficial do Registry é io.github.masakaai/rea-captcha e inicia o servidor stdio de configuração zero via npm:

npx rea-captcha@0.2.4 mcp --stateless

Revise a versão fixada do pacote e aprove o prompt de instalação do npm somente quando ela corresponder à versão que você pretende executar. O comando não suprime esse prompt.

Ele expõe seis ferramentas: captcha_analyze, captcha_inspect, captcha_complete, captcha_handoff, captcha_wait e captcha_resume. captcha_complete executa apenas uma ação autorizada por política no navegador existente configurado e aguarda novas evidências de validação. Consulte o catálogo de ferramentas para entradas e semântica do ciclo de vida.

Para uma sessão local com estado, execute a configuração e imprima uma configuração de host:

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

rea-captcha adiciona inteligência de verificação e ações de conclusão limitadas; ele não substitui as ferramentas de navegação de um agente. Ambas as integrações devem referir-se à mesma sessão de navegador.

Usuários do Hermes Agent podem inspecionar o pacote Portable Agent Plugins v1. Seu padrão seguro para catálogo é análise de evidências sem estado; ações de navegador na mesma sessão ainda exigem uma configuração explícita de rea-captcha com estado.

SDK 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();
}

O controlador toma emprestado page; ele não cria nem fecha o navegador.

Provedores de navegador

O provedor recomendado entre agentes é um navegador que já expõe 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"]
    }
  }
}

Playwright genérico Page, Playwright sobre CDP, browser-use e adaptadores opcionais gerenciados/standalone do Jet Browser são implementados. O Jet Browser deve ser selecionado explicitamente e não é instalado nem iniciado pelo caminho padrão. Exemplos de configuração e limites de provedores estão documentados em arquitetura e casos.

browser-use e OCR local

Instale o adaptador Python alinhado à versão a partir da fonte do repositório marcado:

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

O adaptador Python ainda não está publicado no PyPI, portanto um pip install rea-captcha sem qualificação não funcionará. A instalação da fonte fixada mantém o adaptador e a versão do repositório alinhados sem depender de uma distribuição não publicada.

Para conclusão conduzida por agente, aponte a sessão Playwright/CDP do rea-captcha para o mesmo navegador existente usado pelo browser-use. O ciclo de vida do MCP detecta o bloqueio, executa uma ação autorizada, verifica o resultado e devolve o controle sem substituir o navegador ou o contexto da tarefa.

O plugin Python permanece um fallback leve de detecção e recuperação manual para integrações browser-use que não expõem uma superfície de ação CDP compatível:

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)

ddddocr local é um primitivo opcional apenas para desafios simples de imagem/texto em uma origem autorizada exata. Ele é desabilitado a menos que tanto allowLocalImageText quanto authorizedOrigins estejam configurados. Nenhum peso de modelo é redistribuído, e uma previsão de OCR permanece evidência não confiável.

O que está implementado

  • Detecção de evidências para reCAPTCHA, hCaptcha, Turnstile, GeeTest, DataDome, PerimeterX, AWS WAF, entradas de imagem/texto e páginas genéricas de verificação.
  • Estados determinísticos com timeout limitado, cancelamento e verificações de retomada de novas evidências.
  • Seis ferramentas MCP stdio, paridade CLI/MCP, SDK TypeScript, hooks browser-use e um Agent Skill compatível com Vercel.
  • Sessões Playwright/CDP emprestadas mais adaptadores opcionais do Jet Browser.
  • Eventos JSONL locais com propriedade explícita e sem telemetria.
  • Fluxo de trabalho npm Trusted Publishing/provenance e publicação GitHub OIDC para o Registry MCP oficial.

Documentação

Comunidade

Entre no Discord MASAKA e use o canal dedicado #rea-captcha para discussões de integração e exemplos de agentes na mesma sessão. Use GitHub Issues para bugs reproduzíveis e siga a política de segurança privada para vulnerabilidades. Nunca publique perfis de navegador, cookies, tokens de desafio, chaves de API ou evidências privadas de página.

Escopo e aviso legal

rea-captcha é para fluxos de trabalho próprios ou explicitamente autorizados. A automação de provedores é aceita somente quando o adaptador confirma a chave de teste documentada de não produção do fornecedor. Ele não contorna a proteção interativa de produção. APIs de solucionadores comerciais, transferência de credenciais, alegações de stealth e conclusão automática de desafios de produção de terceiros estão fora do escopo.

Inspirado por morluto/rea.

Licença

O código principal e as integrações são licenciados sob MIT. Dependências opcionais e artefatos de modelo mantêm seus próprios termos; consulte Avisos de terceiros e licenças de modelo.