Português (Brasil) · English

rea-from-api

Transforme os dados de qualquer site num cliente de API testado para o seu app.

Viu num site um dado de que você precisa? Descubra exatamente como ele é servido, com provas, e receba código tipado e testado.

O que dá para fazer · Início rápido · Como funciona · O que ele descobre · Benchmark · Showcase · FAQ · Docs

npx rea-from-api setup

Precisa dos produtos, preços, pacotes, anúncios ou estatísticas que um site mostra? Peça ao seu agente para investigar com o rea-from-api. Ele descobre de onde os dados realmente vêm (uma API oficial, uma especificação OpenAPI publicada, as requisições que a página faz no navegador, uma rota de dados do framework ou JSON embutido no HTML), prova cada fonte com requisições somente leitura, registra a API como OpenAPI 3.1 e gera um cliente TypeScript ou Python testado para colocar no seu projeto.

Toda afirmação vem com evidência: qual estratégia encontrou, a requisição que confirmou e o hash dos bytes. Nada é inventado: uma rota vista só no JavaScript continua inferida até uma resposta real prová-la. A captura no navegador e a análise de bundles usam o motor REA.

O que dá para fazer

Related MCP server: Hydra ACI

Início rápido

Funciona em Windows, macOS e Linux com Node.js 22.18+.

Configure o seu agente

npx rea-from-api setup

O setup detecta os seus agentes, mostra exatamente o que vai mudar, pergunta antes de aplicar e faz backup de cada configuração. Reinicie os agentes depois.

--agent <id> (pode repetir) ou --all escolhem os agentes sem perguntar, --yes pula a confirmação, --dry-run só mostra o plano e --uninstall remove tudo o que o setup adicionou. Qualquer outro cliente MCP pode rodar npx -y rea-from-api mcp.

Peça ao agente

Investigue https://exemplo.com, descubra como ele disponibiliza os dados públicos de produtos,
me mostre as evidências e crie uma integração TypeScript para o meu projeto.

Ou use o terminal

npx rea-from-api run https://exemplo.com --goal "dados públicos de produtos" --target ../meu-app --live

run = investigate → plan → generate → validate. Cada etapa também roda sozinha; veja npx rea-from-api help. npx rea-from-api doctor mostra quais motores opcionais estão disponíveis.

APIs que exigem a sua chave

A maioria das APIs oficiais pede uma chave. Coloque a sua chave numa variável de ambiente e passe o nome dela. A chave vai só para a API do alvo e nunca aparece em relatórios, fixtures ou código gerado.

export MINHA_CHAVE=...           # PowerShell: $env:MINHA_CHAVE = "..."
npx rea-from-api run https://api.exemplo.com/docs --goal "dados de pedidos" \
  --auth-env MINHA_CHAVE --auth-header X-Api-Key        # ou: --auth-query api_key

Como funciona

O agente chama pelo MCP as mesmas operações que você roda no terminal. Os resultados são resumos curtos com os caminhos dos artefatos completos: findings.md, endpoints.json, evidence.json, openapi.json, plan.md e validation.md.

O que ele descobre

Motores opcionais são detectados, nunca instalados por conta própria: jsluice, schemathesis, oasdiff, mypy.

Benchmark

Testado em 22 sites reais, recebendo só a URL e um objetivo em texto: sem seeds, sem HAR e sem chave. Conta como usável o endpoint que o plan transformaria em código: confirmado por um GET real, em JSON e relevante para o objetivo.

Exemplos do que ele acha sozinho: api.github.com/repos/{owner}/{repo} já preenchido com nodejs/node a partir da URL da página; bcb.gov.br/api/servico/sitebcb/taxaselic/ultima para "taxa selic"; crates.io/api/v1/crates/{id} com paginação.

Rodar o benchmark mudou a ferramenta: a primeira rodada deu 3 de 22, e cada falha virou uma correção (documentação em subdomínios, raízes de API em hipermídia, palavras compostas na relevância, JSON de banner de consentimento entrando no código gerado). Tabela completa por site em benchmark/RESULTS.md; para reproduzir, rode node benchmark/run.mjs.

Showcase

PyPI: de uma página de projeto a um cliente devolvendo dados ao vivo

Um único run em https://pypi.org/project/requests/ (saída acima e em examples/pypi/). O navegador viu 7 requisições de dados, a Wayback Machine trouxe 1.000 URLs arquivadas para checar e os logs de certificados apontaram docs.pypi.org. Rotas de conta achadas no JavaScript foram recusadas pelo verificador. A JSON API do PyPI é bloqueada para robôs no robots.txt, então só foi verificada depois de um --robots-exempt explícito para a API documentada, e virou um cliente que passou em todas as checagens e devolveu dados ao vivo.

Uma loja SPA: todas as conexões de uma vez

O site de teste (tests/fixtures/site.ts) esconde os dados atrás de chamadas fetch. Uma investigação acha a API de produtos no tráfego do navegador, um catálogo RFC 9727 apontando para uma spec YAML, uma listagem no APIs.guru, uma URL morta da Wayback (verificada como inexistente), um endpoint de avaliações que existe só no TypeScript original recuperado do source map, um endpoint de parceiro que só funciona com a chave do próprio usuário, o schema GraphQL e uma rota de dados do Next.js, e então gera clientes TypeScript e Python que passam nos próprios testes. O npm test roda tudo isso em Windows, macOS e Linux.

Testes de conformidade acham o que as amostras escondiam

No mesmo site, o Schemathesis apontou que page, total_pages e next podem vir null, o que nunca aconteceu nas páginas gravadas. Exportar OpenAPI faz o contrato descoberto ser testado além dos exemplos que você por acaso observou.

Segurança

Só requisições somente leitura são enviadas automaticamente (mais uma query de introspecção GraphQL padrão). O robots.txt é respeitado; rotas de conta, admin, login, checkout e exclusão nunca são chamadas; 401/403 e redirecionamentos para login significam "use a sua credencial"; desafios anti-bot e CAPTCHAs param a execução, sem contorno. Requisições, tempo e retentativas têm limites rígidos. Cookies, tokens e chaves nunca chegam a relatórios, fixtures ou código gerado, e o conteúdo dos sites é tratado como dado, nunca como instrução. Detalhes em docs/safety.md.

Ferramentas MCP

investigate · list_endpoints · get_endpoint · read_findings · export_openapi · plan_integration · generate_integration · validate_integration · run_conformance · diff_specs · monitor · doctor

FAQ

Não. O navegador é uma de doze estratégias. Declarações do publicador, sondagem de OpenAPI, a documentação e os hosts de API do próprio site, convenções de frameworks, APIs.guru, Wayback Machine, Certificate Transparency, análise de JavaScript e source maps e introspecção GraphQL funcionam sem navegador (--browser off). O objetivo é a API por trás da página, verificada e tipada, não HTML raspado.

Acha os endpoints que o próprio site usa e verifica os somente leitura. Eles ficam marcados como não documentados: podem mudar sem aviso e o reuso pode ser restrito pelos termos do site. Confira os termos antes de depender dos dados; o monitor avisa quando algo muda.

Endpoints que respondem 401/403 ou redirecionam para login ficam marcados como auth: required. Use a sua chave com --auth-env (veja APIs que exigem a sua chave) ou grave um HAR da sua sessão e passe --har. Nada é extraído do site e nenhuma autenticação é contornada.

Muitos hosts de API (como api.open-meteo.com) usam Disallow: / para afastar robôs de busca, mesmo sendo APIs públicas feitas para programas. Por padrão ele respeita e avisa. Se os termos da API permitem o seu uso, rode de novo com --robots-exempt documented: libera só as rotas que a documentação do próprio site descreve, e isso fica registrado nas evidências.

Qualquer agente com suporte a MCP local. O setup configura Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Gemini CLI ou um .mcp.json de projeto; qualquer outro pode rodar npx -y rea-from-api mcp.

As fontes passivas enviam só o nome do domínio para APIs.guru, Wayback Machine e crt.sh; desative com --passive off. Todo o resto roda na sua máquina. O provedor do modelo do seu agente tem a própria política de dados.

Documentação

• Fluxo e estratégias: ordem, limites, códigos de saída

• Modelo de evidências: campos de endpoint e evidência, extensões OpenAPI

• Segurança e limites

• Pesquisa por trás do design

• Como estender: novas estratégias e geradores

• Integração com o motor

• SKILL.md: instruções para agentes

A documentação detalhada está em inglês.

Desenvolvimento

git clone https://github.com/vitorcgo/rea-from-api && cd rea-from-api
npm install
npm run typecheck
npm test        # testes unitários, de pipeline, MCP, setup e geradores contra um site local
npm run build   # compila o dist/ (o que o pacote npm executa)
node benchmark/run.mjs   # benchmark em sites reais (veja benchmark/)

Um checkout roda os fontes TypeScript direto; node bin/rea-from-api.mjs setup liga a skill a ele. O CI roda a suíte em Windows, macOS e Linux com Node 22 e 24 e instala o pacote empacotado num diretório limpo.

Créditos e licença

MIT, veja LICENSE. A captura no navegador, a análise de bundles e a leitura de HAR usam a REA (Reverse Engineer Anything), do morluto (MIT), como dependência sem modificações; o rea-from-api é um projeto independente. Avisos de terceiros: THIRD_PARTY_NOTICES.md.