ShristiLabs/madhyamas

Madhyamas Proxy — Guía para Agentes IA

Madhyamas es un proxy de depuración HTTP/HTTPS de código abierto construido en Rust. Captura, inspecciona y manipula el tráfico entre clientes y servidores. El binario unificado madhyamas proporciona un servidor proxy, interfaz web, servidor MCP y CLI.

Inicio Rápido

# 1. Instalar (elige una opción)
cargo install madhyamas                          # desde crates.io
cargo build --release -p madhyamas               # desde el código fuente
# O descarga el binario precompilado desde GitHub Releases

# 2. Iniciar el servidor proxy
madhyamas serve
# Proxy escucha en :8888, API/Interfaz Web en :3001

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

Configura los clientes para que usen el proxy localhost:8888. Para la interceptación HTTPS, instala el certificado CA desde ~/.madhyamas/certs/madhyamas-ca.pem (o descárgalo mediante GET /api/cert/ca).

Consulta references/setup.md para obtener instrucciones detalladas de instalación, configuración y certificado CA.

Elegir una Interfaz

Madhyamas expone tres interfaces. Usa la que esté disponible en tu contexto:

Interfaz	Cuándo Usarla	Configuración	Referencia
Herramientas MCP	Dentro de agentes compatibles con MCP (Claude Desktop, Windsurf, etc.)	madhyamas mcp (transporte stdio)	references/mcp-tools.md
Comandos CLI	Acceso a shell, scripts, agentes basados en terminal	madhyamas <comando> <subcomando>	references/cli-commands.md
API REST	Control detallado, scripts personalizados, HTTP directo	curl http://localhost:3001/api/...	references/rest-api.md

Las tres interfaces exponen la misma funcionalidad subyacente. Las herramientas MCP y los comandos CLI son envoltorios de la API REST.

Conceptos Clave

• Puertos del proxy: Proxy en :8888 (tráfico HTTP/HTTPS), API/UI en :3001
• Certificado CA: Generado automáticamente en ~/.madhyamas/certs/. Instálalo en el almacén de confianza del sistema para la interceptación HTTPS
• Sesiones: Organiza el tráfico en sesiones con nombre. Se crea una sesión por defecto automáticamente
• Modo de captura: Grabación (por defecto) captura el tráfico; Paso directo reenvía sin grabar
• Orden del pipeline de interceptación: Reescrituras (prioridad 10) → Simulaciones (20) → Puntos de interrupción (30) → Limitación (40)
• Directorio de datos: ~/.madhyamas/ contiene certs/, logs/, traffic.db (SQLite)
• Servidor MCP: Ejecuta madhyamas mcp para transporte MCP basado en stdio. Establece MADHYAMAS_API_URL para conectar a una instancia de proxy en ejecución

Flujos de Trabajo Principales

Flujo de Trabajo	Descripción	Referencia
Configuración	Instalación, configuración, conexión de clientes, instalación del certificado CA	setup.md
Inspeccionar tráfico	Listar, filtrar, buscar, analizar el tráfico HTTP/HTTPS capturado	traffic-inspection.md
Simular respuestas	Crear reglas de simulación para interceptar y devolver respuestas falsas	mocking.md
Puntos de interrupción	Pausar solicitudes/respuestas para inspección y modificación	breakpoints.md
Reescrituras	Modificar URLs, cabeceras, cuerpos del tráfico coincidente	rewrites.md
Limitación	Simular condiciones de red lentas o inestables	throttling.md
Reproducción	Re-ejecutar solicitudes capturadas con modificaciones	replay.md
Sesiones	Crear, cambiar, exportar, importar sesiones de depuración	sessions.md
Inspección gRPC	Inspeccionar conexiones, streams y tramas gRPC (experimental)	grpc.md
Scripting	Automatizar la manipulación del tráfico con scripts JS/TS (experimental)	scripting.md
Plugins	Gestionar plugins de Rust para funcionalidad extendida (experimental)	plugins.md
WebSockets	Inspeccionar el tráfico y mensajes de conexiones WebSocket	websockets.md
Exportar/Importar	Exportación HAR, exportación cURL, persistencia de reglas	export-import.md
Solución de problemas	Errores de certificado, conflictos de puerto, bloqueos de base de datos, fallos TLS	troubleshooting.md
Configuración del harness	Configurar MCP para Claude, Windsurf, Cursor, etc.	harness-setup.md

Índice de Referencias

Archivo	Cuándo Leerlo
references/setup.md	Configuración inicial, instalación, certificado CA, configuración del cliente
references/mcp-tools.md	Referencia completa de las 67 herramientas MCP con parámetros
references/cli-commands.md	Referencia completa de los 58 subcomandos CLI con indicadores
references/rest-api.md	Referencia completa de los más de 130 endpoints de la API REST
references/traffic-inspection.md	Filtrado, búsqueda y análisis del tráfico capturado
references/mocking.md	Creación y gestión de respuestas simuladas
references/breakpoints.md	Pausa y modificación del tráfico
references/rewrites.md	Reglas de reescritura de URL/cabecera/cuerpo
references/throttling.md	Simulación de condiciones de red
references/replay.md	Reproducción y guardado de solicitudes
references/sessions.md	Gestión de sesiones
references/grpc.md	Inspección de tráfico gRPC
references/scripting.md	Scripting en JavaScript/TypeScript
references/plugins.md	Gestión de plugins
references/websockets.md	Inspección de tráfico WebSocket
references/export-import.md	Exportación HAR/cURL, persistencia
references/troubleshooting.md	Problemas comunes y soluciones
references/harness-setup.md	Configuración MCP por harness

Configuración del Servidor MCP

Ejecuta el servidor MCP para la integración con agentes IA:

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

Añádelo a la configuración MCP de tu agente:

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

Consulta references/harness-setup.md para la configuración específica de cada harness (Claude Desktop, Windsurf, Cursor, OpenCode, CommandCode, Devin).

Patrones Comunes

Depurar llamadas API fallidas:

1. Iniciar el proxy: madhyamas serve
2. Configurar el cliente para que use el proxy
3. Reproducir el problema
4. Inspeccionar el tráfico: madhyamas traffic list --status 500 o MCP madhyamas_get_traffic con status=500
5. Obtener detalles: madhyamas traffic get <id> o MCP madhyamas_get_traffic_entry

Simular un endpoint API:

1. Crear la simulación: madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}'
2. O MCP: madhyamas_create_mock con url_pattern="*/api/auth*", status_code=200, body='{"token":"fake"}'
3. Probar el endpoint simulado desde tu cliente

Probar con red lenta:

1. Habilitar la limitación: madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable
2. O MCP: madhyamas_set_throttle con download_bps=50000, delay_ms=200, enabled=true
3. Reproducir tu flujo de trabajo para ver el comportamiento bajo condiciones lentas