ReqTree

ReqTree

ReqTree é um proxy de captura HTTP/HTTPS e WebSocket sem GUI. Ele captura tráfego HTTP/1.x e HTTP/2 além de frames WebSocket decodificados em memória e os expõe a um LLM através de MCP; o LLM é a interface para inspecionar, salvar e alterar tráfego. É uma camada de dados para entender uma API, não uma GUI ou um gerador de clientes de API por si só.

O que um LLM pode fazer através do ReqTree

Capacidade	Ferramentas MCP	O que isso permite
Inspecionar tráfego capturado	get_stats, search_exchanges, get_exchange_detail	Mapear endpoints, métodos, protocolos, cabeçalhos, corpos JSON, frames WebSocket, códigos de status e ordem de requisições.
Controlar captura	start_capture, stop_capture, capture_window, clear_*	Manter apenas uma reprodução ou fluxo de login em vez de tráfego de fundo.
Salvar e comparar sessões	save_capture, open_capture, list_captures	Preservar uma captura útil ou compará-la com uma execução posterior.
Alterar requisições correspondentes	add_rule, list_rules, set_rule_enabled	Bloquear, simular, redirecionar, definir ou remover cabeçalhos de requisição e redigir corpos de requisição.
Executar lógica C# personalizada	add_script, list_scripts, describe_script_format	Inspecionar ou reescrever requisições antes de saírem e respostas antes de o cliente recebê-las.
Coordenar sessões	get_logs, log_note	Ver quem alterou regras compartilhadas, scripts ou estado de captura.

Regras são executadas primeiro e são a opção simples e declarativa. Scripts são a saída de emergência: um script before_request pode reescrever uma URL, cabeçalhos de requisição ou um corpo de requisição, ou responder a uma requisição localmente atribuindo exchange.StatusCode e exchange.ResponseBody. Um script before_response pode reescrever o status, cabeçalhos ou corpo entregues ao cliente.

Isso também torna o ReqTree útil para testes de API: um LLM pode capturar um fluxo real, identificar seu contrato, gerar um cliente ou casos de teste a partir das evidências e usar regras ou scripts para exercitar respostas de sucesso, falha e casos extremos.

Cabeçalhos e corpos devem ser atribuídos, não mutados no lugar. Por exemplo, atribua uma nova lista de cabeçalhos com exchange.RequestHeaders = [...]; não faça cast e edite a lista existente. Chame describe_script_format antes de pedir a um LLM para escrever seu primeiro script.

Quando um script de resposta altera o tráfego, o ReqTree mantém a resposta upstream original na captura e envia a versão modificada apenas ao cliente. Uma resposta simulada localmente é armazenada como a resposta, porque não há versão upstream.

Início rápido — a configuração normal

Instale o .NET 10 SDK e então compile uma vez a partir da raiz do repositório:

dotnet build ReqTree.sln

Inicie o ReqTree com sua configuração padrão de todo o sistema:

.\src\ReqTree\bin\Debug\net10.0\reqtree.exe start

Ou, após colocar reqtree.exe no seu PATH:

reqtree start

Este é o modo normal de todo o sistema. O ReqTree confia em seu certificado raiz para o usuário atual e Local Machine, então usa as configurações de conexão WinINet ativas do Windows para apontar aplicativos com suporte a proxy para si mesmo. O proxy não precisa ser executado como Administrador. Use Ctrl+C para pará-lo limpo e restaurar a configuração completa de proxy anterior.

Em seguida, adicione o ReqTree como um servidor MCP HTTP nas configurações de MCP do seu cliente LLM. Os detalhes de conexão portátil estão em Conectando um cliente MCP.

Exemplos

Capturar um fluxo de login e construir um cliente

Use isso apenas para um site, conta e tráfego que você está autorizado a inspecionar. Capturas podem conter senhas, cookies, tokens de portador e dados pessoais; não envie uma captura não redigida para um serviço não confiável nem a envie para controle de versão.

1. Diga ao LLM: “Inicie uma nova captura para example.com; limpe quaisquer trocas existentes primeiro.”
2. No seu navegador ou aplicativo, carregue o site, faça login com uma conta de teste, abra uma página autenticada, e então faça logout.
3. Diga ao LLM: “Concluí o fluxo de login. Pare de capturar e recrie o fluxo de autenticação do site observado como um cliente de API. Use placeholders para credenciais e segredos, não reutilize tokens capturados e não invente endpoints.”

O ReqTree dá ao LLM as trocas capturadas. Ele pode inspecionar sua ordem, URLs, métodos, requisição e resposta JSON, cabeçalhos, cookies, transições de token e respostas de erro, e então gerar um pequeno cliente, suíte de testes de API, serviço de teste, esquema, fixtures ou mock a partir dessas evidências. Salve a evidência quando terminar: “Salve esta captura como example-sign-in.”

Uma captura prova apenas o caminho que você executou. Capture fluxos extras deliberadamente para outros papéis, erros, verificações de dispositivo ou permissões antes de pedir ao LLM para ampliar a implementação.

Exemplos de modificações

Ao testar um site que você está autorizado a modificar, pergunte diretamente. Por exemplo:

“Para requisições a api.example.com, adicione o cabeçalho de requisição X-Test-Mode: true. Continue capturando para que eu possa ver o resultado e me diga como desfazer a alteração.”

O LLM pode criar uma regra correspondente e depois desabilitá-la ou removê-la. Outros prompts úteis incluem:

• Corpo da requisição: “Para requisições POST a api.example.com/orders, substitua o campo JSON testMode por true. Capture a requisição original e me diga quais trocas mudaram.”
• Redirecionamento de URL: “Redirecione requisições de https://api.example.com/v1/catalog para https://staging-api.example.com/v1/catalog até eu dizer para parar.”
• Corpo da resposta: “Para respostas de api.example.com/feature-flags, retorne uma versão com newCheckout definido como true, mas mantenha a resposta upstream original na captura.”
• Resposta simulada: “Simule GET https://api.example.com/account com uma resposta JSON 200 para um usuário de teste, sem enviar a requisição upstream.”
• Bloquear tráfego: “Bloqueie requisições a analytics.example.com e registre cada correspondência.”

Para alterações condicionais ou computadas, o LLM pode gerar um script C# personalizado e passá-lo ao ReqTree para você. O ReqTree executa esse script antes de uma requisição sair ou antes de uma resposta chegar ao cliente. Por exemplo: “Escreva e habilite um script que adiciona X-Preview: true apenas quando uma URL de requisição contém /preview/; registre cada alteração e me mostre o script primeiro.”

Comandos

Comando	Propósito
reqtree start [options]	Inicia o MCP e, por padrão, o proxy de captura de todo o sistema.
reqtree open <file.reqtree>	Abre uma captura salva para leitura; não intercepta nem registra tráfego.
reqtree help	Imprime o manual embutido. Funciona sem um repositório ou servidor em execução.

Opções de início

Valores de opções sempre usam =, por exemplo --mcp-port=9000.

Opção	Padrão	Propósito
--port=<n>	8888	Porta TCP para o proxy de captura.
--mcp-port=<n>	9999	Porta TCP para o servidor MCP localhost.
--console-view	off	Imprime uma linha de resumo por troca concluída.
--paused	off	Inicia o proxy com gravação desligada. Tráfego, regras e scripts ainda são executados.
--buffer=<n>	5000	Máximo de trocas mantidas em memória; descarta as mais antigas quando cheio. 0 é ilimitado.
--buffer-mb=<n>	512	Limite aproximado de memória de corpo em MB; descarta as mais antigas quando cheio. 0 é ilimitado.
--stop-after=<n>	unlimited	Para de gravar após este número de trocas. O tráfego continua fluindo.
--no-proxy	off	Inicia apenas o MCP. Inicie a interceptação depois com a ferramenta MCP start_proxy.
--no-system-proxy	off	Modo de cliente manual: deixa as configurações de proxy do Windows intactas e configura um cliente explicitamente.
--no-cert-trust	off	Gera e exporta o certificado raiz sem adicioná-lo a qualquer armazenamento de confiança do Windows.
--user-cert-trust	off	Confia na raiz apenas para a conta atual, evitando elevação para instalação de certificado.
--machine-cert-trust	on	Alias de compatibilidade; confiança de máquina inteira já é o padrão.
-h ou --help	off	Mostra o manual embutido. reqtree help é a forma mais clara.

Modos de início comuns

Objetivo	Comando
Capturar tráfego HTTP/HTTPS de todo o sistema	reqtree start
Limitar confiança de certificado a esta conta	reqtree start --user-cert-trust
Capturar um cliente configurado manualmente	reqtree start --no-system-proxy --no-cert-trust
Conectar um LLM antes de interceptar tráfego	reqtree start --no-proxy
Iniciar gravação apenas quando solicitado	reqtree start --paused
Ler uma captura anterior	reqtree open C:\path\to\capture.reqtree

Para o modo de cliente manual, aponte o cliente para http://localhost:8888. O certificado raiz ainda é exportado para %LOCALAPPDATA%\ReqTree\reqtree-root.cer para que esse cliente possa confiar em tráfego HTTPS.

A confiança de certificado de máquina inteira é o padrão e persiste após o ReqTree sair. O Windows pode pedir elevação uma vez quando esse certificado é instalado pela primeira vez; execuções normais de proxy permanecem sem elevação. A captura normal usa as configurações de proxy HTTP e HTTPS ativas por conexão do WinINet, o mesmo mecanismo de um proxy Windows comparável. Aplicativos que ignoram as configurações de proxy do Windows, UDP e QUIC não são capturados, e clientes TLS com fixação de certificado não podem ser descriptografados. --no-system-proxy deixa as configurações do Windows intactas para configuração explícita/manual de cliente.

Conectando um cliente MCP

O ReqTree fala Streamable HTTP diretamente, então qualquer cliente LLM que suporte servidores MCP HTTP pode usá-lo. Não há processo de ponte nem comando para executar a partir da configuração do cliente.

1. Inicie o ReqTree: reqtree start.

2. Abra as configurações de servidor MCP do seu cliente LLM e adicione um servidor HTTP remoto.

3. Insira estes valores:

   Configuração	Valor
   Nome	reqtree
   Transporte	Streamable HTTP (alguns clientes rotulam simplesmente como HTTP)
   URL	http://127.0.0.1:9999
   Autenticação / cabeçalhos	Nenhum

4. Salve ou reconecte o cliente MCP e então chame get_proxy_status para confirmar que está conectado.

Mantenha a porta da URL em sincronia com --mcp-port. Por exemplo, se o ReqTree iniciar com --mcp-port=9000, configure http://127.0.0.1:9000 em vez disso. O endpoint é somente loopback, então o cliente deve ser executado na mesma máquina que o ReqTree.

Várias sessões LLM podem se conectar ao mesmo tempo; elas compartilham uma captura, um conjunto de regras e scripts e um log de coordenação. get_logs mostra quem alterou o quê.

Dados e recuperação

O ReqTree armazena seu certificado, logs e marcador de recuperação de proxy em %LOCALAPPDATA%\ReqTree:

Caminho	Conteúdo
reqtree-root.pfx / reqtree-root.cer	O certificado raiz MITM gerado.
logs\reqtree-YYYYMMDD.log	O log de atividade lido por get_logs.
proxy-state.json	Presente apenas enquanto o ReqTree possui as configurações de proxy do sistema.

O tráfego capturado não é escrito lá automaticamente. Ele vive em memória até save_capture ser chamado e é perdido quando o ReqTree sai se não foi salvo.

Se a internet parecer parar após uma falha ou morte forçada, execute reqtree start novamente. O ReqTree vê o marcador de recuperação obsoleto e restaura as configurações de proxy do sistema anteriores antes de iniciar. A ferramenta clean_stale_proxy_state fornece o mesmo reparo sob demanda.

Para contribuidores e LLMs

AGENTS.md explica a arquitetura e as regras do repositório. DECISIONS.md explica tradeoffs-chave. PROGRESS.md registra o estado atual e bugs anteriores. Mantenha este README e reqtree help alinhados sempre que a CLI mudar.