ShristiLabs/madhyamas

Madhyamas Proxy — Guia para Agentes de IA

Madhyamas é um proxy de depuração HTTP/HTTPS de código aberto construído em Rust. Ele captura, inspeciona e manipula o tráfego entre clientes e servidores. O binário unificado madhyamas fornece um servidor proxy, interface web, servidor MCP e CLI.

Início Rápido

# 1. Instalar (escolha uma opção)
cargo install madhyamas                          # do crates.io
cargo build --release -p madhyamas               # a partir do código-fonte
# Ou baixe o binário pré-compilado das GitHub Releases

# 2. Iniciar o servidor proxy
madhyamas serve
# Proxy escuta em :8888, API/Interface Web em :3001

# 3. Verificar
curl http://localhost:3001/api/health
# Retorna: OK

Configure os clientes para usar o proxy localhost:8888. Para interceptação HTTPS, instale o certificado CA de ~/.madhyamas/certs/madhyamas-ca.pem (ou baixe via GET /api/cert/ca).

Consulte references/setup.md para instalação detalhada, configuração e configuração do certificado CA.

Escolhendo uma Interface

Madhyamas expõe três interfaces. Use a que estiver disponível no seu contexto:

Interface	Quando usar	Configuração	Referência
Ferramentas MCP	Dentro de agentes compatíveis com MCP (Claude Desktop, Windsurf, etc.)	madhyamas mcp (transporte stdio)	references/mcp-tools.md
Comandos CLI	Acesso ao shell, scripts, agentes baseados em terminal	madhyamas <comando> <subcomando>	references/cli-commands.md
API REST	Controle refinado, scripts personalizados, HTTP direto	curl http://localhost:3001/api/...	references/rest-api.md

Todas as três interfaces expõem a mesma funcionalidade subjacente. As ferramentas MCP e comandos CLI são wrappers em torno da API REST.

Conceitos Principais

• Portas do proxy: Proxy em :8888 (tráfego HTTP/HTTPS), API/UI em :3001
• Certificado CA: Gerado automaticamente em ~/.madhyamas/certs/. Instale no repositório de confiança do sistema para interceptação HTTPS
• Sessões: Organize o tráfego em sessões nomeadas. Sessão padrão criada automaticamente
• Modo de captura: Gravação (padrão) captura o tráfego; Passagem encaminha sem gravar
• Ordem do pipeline de interceptação: Reescritas (prioridade 10) → Mocks (20) → Breakpoints (30) → Throttle (40)
• Diretório de dados: ~/.madhyamas/ contém certs/, logs/, traffic.db (SQLite)
• Servidor MCP: Execute madhyamas mcp para transporte MCP via stdio. Defina MADHYAMAS_API_URL para conectar a uma instância de proxy em execução

Fluxos de Trabalho Principais

Fluxo de Trabalho	Descrição	Referência
Configuração	Instalar, configurar, conectar clientes, instalar certificado CA	setup.md
Inspecionar tráfego	Listar, filtrar, pesquisar, analisar tráfego HTTP/HTTPS capturado	traffic-inspection.md
Mock de respostas	Criar regras de mock para interceptar e retornar respostas falsas	mocking.md
Breakpoints	Pausar requisições/respostas para inspeção e modificação	breakpoints.md
Reescritas	Modificar URLs, cabeçalhos, corpos do tráfego correspondente	rewrites.md
Throttling	Simular condições de rede lentas/não confiáveis	throttling.md
Replay	Reexecutar requisições capturadas com modificações	replay.md
Sessões	Criar, alternar, exportar, importar sessões de depuração	sessions.md
Inspeção gRPC	Inspecionar conexões, streams e frames gRPC (experimental)	grpc.md
Scripting	Automatizar manipulação de tráfego com scripts JS/TS (experimental)	scripting.md
Plugins	Gerenciar plugins Rust para funcionalidade estendida (experimental)	plugins.md
WebSockets	Inspecionar tráfego e mensagens de conexão WebSocket	websockets.md
Exportar/Importar	Exportação HAR, exportação cURL, persistência de regras	export-import.md
Solução de problemas	Erros de certificado, conflitos de porta, bloqueios de BD, falhas TLS	troubleshooting.md
Configuração de Harness	Configurar MCP para Claude, Windsurf, Cursor, etc.	harness-setup.md

Índice de Referências

Arquivo	Quando ler
references/setup.md	Configuração inicial, instalação, certificado CA, configuração do cliente
references/mcp-tools.md	Referência completa para todas as 67 ferramentas MCP com parâmetros
references/cli-commands.md	Referência completa para todos os 58 subcomandos CLI com flags
references/rest-api.md	Referência completa para mais de 130 endpoints da API REST
references/traffic-inspection.md	Filtragem, pesquisa, análise de tráfego capturado
references/mocking.md	Criar e gerenciar respostas mock
references/breakpoints.md	Pausar e modificar tráfego
references/rewrites.md	Regras de reescrita de URL/cabeçalho/corpo
references/throttling.md	Simulação de condições de rede
references/replay.md	Reexecutar e salvar requisições
references/sessions.md	Gerenciamento de sessões
references/grpc.md	Inspeção de tráfego gRPC
references/scripting.md	Scripting em JavaScript/TypeScript
references/plugins.md	Gerenciamento de plugins
references/websockets.md	Inspeção de tráfego WebSocket
references/export-import.md	Exportação HAR/cURL, persistência
references/troubleshooting.md	Problemas comuns e soluções
references/harness-setup.md	Configuração MCP por harness

Configuração do Servidor MCP

Execute o servidor MCP para integração com agentes de IA:

madhyamas mcp                    # transporte stdio, conecta a localhost:3001
MADHYAMAS_API_URL=http://host:3001 madhyamas mcp  # URL da API personalizada

Adicione à configuração MCP do seu agente:

{
  "mcpServers": {
    "madhyamas": {
      "command": "/caminho/para/madhyamas",
      "args": ["mcp"],
      "env": { "MADHYAMAS_API_URL": "http://127.0.0.1:3001" }
    }
  }
}

Consulte references/harness-setup.md para configuração específica de harness (Claude Desktop, Windsurf, Cursor, OpenCode, CommandCode, Devin).

Padrões Comuns

Depurar chamadas de API com falha:

1. Iniciar proxy: madhyamas serve
2. Configurar cliente para usar o proxy
3. Reproduzir o problema
4. Inspecionar tráfego: madhyamas traffic list --status 500 ou MCP madhyamas_get_traffic com status=500
5. Obter detalhes: madhyamas traffic get <id> ou MCP madhyamas_get_traffic_entry

Mock de um endpoint de API:

1. Criar mock: madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}'
2. Ou MCP: madhyamas_create_mock com url_pattern="*/api/auth*", status_code=200, body='{"token":"fake"}'
3. Testar o endpoint mockado a partir do seu cliente

Testar sob rede lenta:

1. Ativar throttle: madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable
2. Ou MCP: madhyamas_set_throttle com download_bps=50000, delay_ms=200, enabled=true
3. Reproduzir seu fluxo de trabalho para ver o comportamento sob condições lentas