ReqTree

ReqTree

ReqTree é um proxy de captura HTTP/HTTPS sem GUI. Ele captura o tráfego em memória e o expõe a um LLM por meio do MCP; o LLM é a interface para inspecionar, salvar e alterar o 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 por meio do ReqTree

Capacidade	Ferramentas MCP	O que permite
Inspecionar tráfego capturado	get_stats, search_exchanges, get_exchange_detail	Mapear endpoints, métodos, cabeçalhos, corpos JSON, códigos de status e ordem das requisições.
Controlar a captura	start_capture, stop_capture, capture_window, clear_*	Manter apenas uma reprodução ou um 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 da captura.

As regras são executadas primeiro e são a opção simples e declarativa. Os scripts são a válvula de escape: 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, os cabeçalhos ou o corpo entregue 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, pois não há versão upstream.

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

Instale o .NET 10 SDK e, em seguida, 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 mais simples. O ReqTree confia em seu certificado raiz para o usuário atual, aponta as configurações de proxy da máquina para si mesmo e começa a gravar o tráfego de navegadores e aplicativos. Use Ctrl+C para interrompê-lo de forma limpa; isso restaura as configurações anteriores de proxy do sistema.

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 criar um cliente

Use isso apenas para um site, conta e tráfego que você está autorizado a inspecionar. As 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 o 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, em seguida, 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 espaços reservados para credenciais e segredos, não reutilize tokens capturados e não invente endpoints.”

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

Uma captura prova apenas o caminho que você executou. Capture fluxos extras deliberadamente para outras funções, 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, peça 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, posteriormente, desativá-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 calculadas, 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 somente quando uma URL de requisição contém /preview/; registre cada alteração e me mostre o script primeiro.”

Comandos

Comando	Finalidade
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 grava tráfego.
reqtree help	Imprime o manual integrado. Funciona sem um repositório ou um servidor em execução.

Opções de início

Os valores das opções sempre usam =, por exemplo, --mcp-port=9000.

Opção	Padrão	Finalidade
--port=<n>	8888	Porta TCP para o proxy de captura.
--mcp-port=<n>	9999	Porta TCP para o servidor MCP localhost.
--console-view	desativado	Imprime uma linha de resumo por troca concluída.
--paused	desativado	Inicia o proxy com a gravação desativada. 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>	ilimitado	Para de gravar após este número de trocas. O tráfego continua fluindo.
--no-proxy	desativado	Inicia apenas o MCP. Inicie a interceptação depois com a ferramenta MCP start_proxy.
--no-system-proxy	desativado	Escuta sem alterar as configurações de proxy da máquina; configure um cliente manualmente.
--no-cert-trust	desativado	Gera e exporta o certificado raiz sem adicioná-lo ao armazenamento de confiança do usuário atual.
-h ou --help	desativado	Mostra o manual integrado. reqtree help é a forma mais clara.

Modos de início comuns

Objetivo	Comando
Capturar tudo nesta máquina	reqtree start
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 a gravação somente 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 no tráfego HTTPS.

Conectando um cliente MCP

O ReqTree fala Streamable HTTP diretamente, portanto, 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 isso simplesmente como HTTP)
   URL	http://127.0.0.1:9999
   Autenticação / cabeçalhos	Nenhum

4. Salve ou reconecte o cliente MCP e, em seguida, 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, portanto, o cliente deve ser executado na mesma máquina que o ReqTree.

Várias sessões de 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 atividades lido por get_logs.
proxy-state.json	Presente somente enquanto o ReqTree possui as configurações de proxy do sistema.

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

Se a internet parecer parar após uma falha ou encerramento forçado, execute reqtree start novamente. O ReqTree vê o marcador de recuperação obsoleto e restaura as configurações anteriores de proxy do sistema 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 as principais compensações. PROGRESS.md registra o estado atual e bugs anteriores. Mantenha este README e reqtree help alinhados sempre que a CLI mudar.