ShristiLabs/madhyamas

Proxy Madhyamas — Guide pour agents IA

Madhyamas est un proxy de débogage HTTP/HTTPS open source développé en Rust. Il capture, inspecte et manipule le trafic entre les clients et les serveurs. Le binaire unifié madhyamas fournit un serveur proxy, une interface web, un serveur MCP et une CLI.

Démarrage rapide

# 1. Installation (choisir une méthode)
cargo install madhyamas                          # depuis crates.io
cargo build --release -p madhyamas               # depuis les sources
# Ou télécharger un binaire pré-construit depuis GitHub Releases

# 2. Démarrer le serveur proxy
madhyamas serve
# Le proxy écoute sur :8888, l'API/interface web sur :3001

# 3. Vérification
curl http://localhost:3001/api/health
# Retourne : OK

Configurez les clients pour utiliser le proxy localhost:8888. Pour l'interception HTTPS, installez le certificat CA depuis ~/.madhyamas/certs/madhyamas-ca.pem (ou téléchargez-le via GET /api/cert/ca).

Consultez references/setup.md pour une installation, configuration et configuration du certificat CA détaillées.

Choisir une interface

Madhyamas expose trois interfaces. Utilisez celle qui est disponible dans votre contexte :

Interface	Quand l'utiliser	Configuration	Référence
Outils MCP	Dans des agents compatibles MCP (Claude Desktop, Windsurf, etc.)	madhyamas mcp (transport stdio)	references/mcp-tools.md
Commandes CLI	Accès shell, scripts, agents en terminal	madhyamas <commande> <sous-commande>	references/cli-commands.md
API REST	Contrôle fin, scripts personnalisés, HTTP direct	curl http://localhost:3001/api/...	references/rest-api.md

Les trois interfaces exposent les mêmes fonctionnalités sous-jacentes. Les outils MCP et les commandes CLI sont des wrappers autour de l'API REST.

Concepts clés

• Ports du proxy : Proxy sur :8888 (trafic HTTP/HTTPS), API/interface sur :3001
• Certificat CA : Généré automatiquement dans ~/.madhyamas/certs/. Installez-le dans le magasin de confiance du système pour l'interception HTTPS
• Sessions : Organisez le trafic en sessions nommées. Une session par défaut est créée automatiquement
• Mode de capture : Enregistrement (par défaut) capture le trafic ; Passage en transit transfère sans enregistrer
• Ordre du pipeline d'interception : Réécritures (priorité 10) → Simulations (20) → Points d'arrêt (30) → Limitation (40)
• Répertoire de données : ~/.madhyamas/ contient certs/, logs/, traffic.db (SQLite)
• Serveur MCP : Exécutez madhyamas mcp pour un transport MCP basé sur stdio. Définissez MADHYAMAS_API_URL pour vous connecter à une instance proxy en cours d'exécution

Flux de travail principaux

Flux de travail	Description	Référence
Configuration	Installer, configurer, connecter des clients, installer le certificat CA	setup.md
Inspecter le trafic	Lister, filtrer, rechercher, analyser le trafic HTTP/HTTPS capturé	traffic-inspection.md
Simuler des réponses	Créer des règles de simulation pour intercepter et renvoyer des réponses factices	mocking.md
Points d'arrêt	Mettre en pause les requêtes/réponses pour inspection et modification	breakpoints.md
Réécritures	Modifier les URL, en-têtes, corps du trafic correspondant	rewrites.md
Limitation	Simuler des conditions réseau lentes/instables	throttling.md
Rejeu	Ré-exécuter des requêtes capturées avec des modifications	replay.md
Sessions	Créer, changer, exporter, importer des sessions de débogage	sessions.md
Inspection gRPC	Inspecter les connexions, flux, trames gRPC (expérimental)	grpc.md
Scripting	Automatiser la manipulation du trafic avec des scripts JS/TS (expérimental)	scripting.md
Plugins	Gérer les plugins Rust pour des fonctionnalités étendues (expérimental)	plugins.md
WebSockets	Inspecter le trafic et les messages des connexions WebSocket	websockets.md
Export/Import	Export HAR, export cURL, persistance des règles	export-import.md
Dépannage	Erreurs de certificat, conflits de ports, verrous de base de données, échecs TLS	troubleshooting.md
Configuration de l'environnement	Configurer MCP pour Claude, Windsurf, Cursor, etc.	harness-setup.md

Index des références

Fichier	Quand le lire
references/setup.md	Configuration initiale, installation, certificat CA, configuration client
references/mcp-tools.md	Référence complète des 67 outils MCP avec paramètres
references/cli-commands.md	Référence complète des 58 sous-commandes CLI avec drapeaux
references/rest-api.md	Référence complète des 130+ endpoints de l'API REST
references/traffic-inspection.md	Filtrage, recherche, analyse du trafic capturé
references/mocking.md	Création et gestion de réponses simulées
references/breakpoints.md	Mise en pause et modification du trafic
references/rewrites.md	Règles de réécriture d'URL/en-têtes/corps
references/throttling.md	Simulation de conditions réseau
references/replay.md	Rejeu et enregistrement de requêtes
references/sessions.md	Gestion des sessions
references/grpc.md	Inspection du trafic gRPC
references/scripting.md	Scripting JavaScript/TypeScript
references/plugins.md	Gestion des plugins
references/websockets.md	Inspection du trafic WebSocket
references/export-import.md	Export HAR/cURL, persistance
references/troubleshooting.md	Problèmes courants et solutions
references/harness-setup.md	Configuration MCP par environnement

Configuration du serveur MCP

Exécutez le serveur MCP pour l'intégration avec les agents IA :

madhyamas mcp                    # transport stdio, se connecte à localhost:3001
MADHYAMAS_API_URL=http://hôte:3001 madhyamas mcp  # URL API personnalisée

Ajoutez à la configuration MCP de votre agent :

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

Consultez references/harness-setup.md pour une configuration spécifique à chaque environnement (Claude Desktop, Windsurf, Cursor, OpenCode, CommandCode, Devin).

Schémas courants

Déboguer des appels API échoués :

1. Démarrer le proxy : madhyamas serve
2. Configurer le client pour utiliser le proxy
3. Reproduire le problème
4. Inspecter le trafic : madhyamas traffic list --status 500 ou MCP madhyamas_get_traffic avec status=500
5. Obtenir les détails : madhyamas traffic get <id> ou MCP madhyamas_get_traffic_entry

Simuler un point de terminaison API :

1. Créer une simulation : madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}'
2. Ou MCP : madhyamas_create_mock avec url_pattern="*/api/auth*", status_code=200, body='{"token":"fake"}'
3. Tester le point de terminaison simulé depuis votre client

Tester sous réseau lent :

1. Activer la limitation : madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable
2. Ou MCP : madhyamas_set_throttle avec download_bps=50000, delay_ms=200, enabled=true
3. Reproduire votre flux de travail pour observer le comportement en conditions lentes