ShristiLabs/madhyamas

Madhyamas Proxy – KI-Agenten-Anleitung

Madhyamas ist ein quelloffener HTTP/HTTPS-Debugging-Proxy, der in Rust geschrieben ist. Er erfasst, inspiziert und manipuliert den Datenverkehr zwischen Clients und Servern. Die einheitliche madhyamas-Binärdatei bietet einen Proxy-Server, eine Weboberfläche, einen MCP-Server und eine CLI.

Schnellstart

# 1. Installieren (eine Option wählen)
cargo install madhyamas                          # von crates.io
cargo build --release -p madhyamas               # aus dem Quellcode
# Oder vorgefertigtes Binary von GitHub Releases herunterladen

# 2. Proxy-Server starten
madhyamas serve
# Proxy lauscht auf :8888, API/Web UI auf :3001

# 3. Überprüfen
curl http://localhost:3001/api/health
# Antwort: OK

Konfigurieren Sie Clients, den Proxy localhost:8888 zu verwenden. Für die HTTPS-Abfangen installieren Sie das CA-Zertifikat aus ~/.madhyamas/certs/madhyamas-ca.pem (oder laden Sie es via GET /api/cert/ca herunter).

Weitere Informationen zur detaillierten Installation, Konfiguration und CA-Zertifikat-Einrichtung finden Sie in references/setup.md.

Wahl der Schnittstelle

Madhyamas bietet drei Schnittstellen an. Verwenden Sie diejenige, die in Ihrem Kontext verfügbar ist:

Schnittstelle	Wann verwenden	Einrichtung	Referenz
MCP-Tools	In MCP-kompatiblen Agenten (Claude Desktop, Windsurf, etc.)	madhyamas mcp (stdio-Transport)	references/mcp-tools.md
CLI-Befehle	Shell-Zugriff, Skripterstellung, terminalbasierte Agenten	madhyamas <Befehl> <Unterbefehl>	references/cli-commands.md
REST-API	Feingranulare Steuerung, benutzerdefinierte Skripte, direktes HTTP	curl http://localhost:3001/api/...	references/rest-api.md

Alle drei Schnittstellen bieten die gleiche zugrunde liegende Funktionalität. MCP-Tools und CLI-Befehle sind Wrapper um die REST-API.

Schlüsselkonzepte

• Proxy-Ports: Proxy auf :8888 (HTTP/HTTPS-Traffic), API/UI auf :3001
• CA-Zertifikat: Wird automatisch unter ~/.madhyamas/certs/ generiert. Für HTTPS-Abfangen im Systemvertrauensspeicher installieren
• Sitzungen: Organisieren Sie den Datenverkehr in benannten Sitzungen. Standardsitzung wird automatisch erstellt
• Aufzeichnungsmodus: Aufzeichnung (Standard) erfasst Datenverkehr; Durchleitung leitet ohne Aufzeichnung weiter
• Abfang-Pipeline-Reihenfolge: Umschreibungen (Priorität 10) → Mocks (20) → Haltepunkte (30) → Drosselung (40)
• Datenverzeichnis: ~/.madhyamas/ enthält certs/, logs/, traffic.db (SQLite)
• MCP-Server: Führen Sie madhyamas mcp für den stdio-basierten MCP-Transport aus. Setzen Sie MADHYAMAS_API_URL, um eine Verbindung zu einer laufenden Proxy-Instanz herzustellen

Kern-Workflows

Workflow	Beschreibung	Referenz
Einrichtung	Installieren, konfigurieren, Clients verbinden, CA-Zertifikat installieren	setup.md
Datenverkehr inspizieren	Erfassten HTTP/HTTPS-Traffic auflisten, filtern, durchsuchen, analysieren	traffic-inspection.md
Mock-Antworten	Mock-Regeln erstellen, um Anfragen abzufangen und simulierte Antworten zurückzugeben	mocking.md
Haltepunkte	Anfragen/Antworten anhalten, um sie zu inspizieren und zu modifizieren	breakpoints.md
Umschreibungen	URLs, Header, Bodies von passendem Datenverkehr modifizieren	rewrites.md
Drosselung	Langsame/unzuverlässige Netzwerkbedingungen simulieren	throttling.md
Wiedergabe	Erfasste Anfragen mit Änderungen erneut ausführen	replay.md
Sitzungen	Debugging-Sitzungen erstellen, wechseln, exportieren, importieren	sessions.md
gRPC-Inspektion	gRPC-Verbindungen, Streams, Frames inspizieren (experimentell)	grpc.md
Skripterstellung	Datenverkehrsmanipulation mit JS/TS-Skripten automatisieren (experimentell)	scripting.md
Plugins	Rust-Plugins für erweiterte Funktionalität verwalten (experimentell)	plugins.md
WebSockets	WebSocket-Verbindungsdatenverkehr und -Nachrichten inspizieren	websockets.md
Export/Import	HAR-Export, cURL-Export, Regel-Persistenz	export-import.md
Fehlerbehebung	Zertifikatsfehler, Portkonflikte, DB-Sperren, TLS-Fehler	troubleshooting.md
Harness-Einrichtung	MCP für Claude, Windsurf, Cursor, etc. konfigurieren	harness-setup.md

Referenzindex

Datei	Wann lesen
references/setup.md	Ersteinrichtung, Installation, CA-Zertifikat, Client-Konfiguration
references/mcp-tools.md	Vollständige Referenz aller 67 MCP-Tools mit Parametern
references/cli-commands.md	Vollständige Referenz aller 58 CLI-Unterbefehle mit Flags
references/rest-api.md	Vollständige Referenz aller 130+ REST-API-Endpunkte
references/traffic-inspection.md	Filtern, Durchsuchen, Analysieren von erfasstem Datenverkehr
references/mocking.md	Erstellen und Verwalten von Mock-Antworten
references/breakpoints.md	Anhalten und Modifizieren von Datenverkehr
references/rewrites.md	URL/Header/Body-Umschreibungsregeln
references/throttling.md	Netzwerkbedingungen simulieren
references/replay.md	Anfragen wiedergeben und speichern
references/sessions.md	Sitzungsverwaltung
references/grpc.md	gRPC-Datenverkehrsinspektion
references/scripting.md	JavaScript/TypeScript-Skripterstellung
references/plugins.md	Plugin-Verwaltung
references/websockets.md	WebSocket-Datenverkehrsinspektion
references/export-import.md	HAR/cURL-Export, Persistenz
references/troubleshooting.md	Häufige Probleme und Lösungen
references/harness-setup.md	MCP-Konfiguration pro Umgebung

MCP-Server Einrichtung

Führen Sie den MCP-Server für die KI-Agenten-Integration aus:

madhyamas mcp                    # stdio-Transport, verbindet sich mit localhost:3001
MADHYAMAS_API_URL=http://host:3001 madhyamas mcp  # benutzerdefinierte API-URL

Fügen Sie Folgendes zur MCP-Konfiguration Ihres Agenten hinzu:

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

Siehe references/harness-setup.md für umgebungsspezifische Konfigurationen (Claude Desktop, Windsurf, Cursor, OpenCode, CommandCode, Devin).

Häufige Muster

Fehlgeschlagene API-Aufrufe debuggen:

1. Proxy starten: madhyamas serve
2. Client für die Verwendung des Proxys konfigurieren
3. Problem reproduzieren
4. Datenverkehr inspizieren: madhyamas traffic list --status 500 oder MCP madhyamas_get_traffic mit status=500
5. Details abrufen: madhyamas traffic get <id> oder MCP madhyamas_get_traffic_entry

Einen API-Endpunkt mocken:

1. Mock erstellen: madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}'
2. Oder MCP: madhyamas_create_mock mit url_pattern="*/api/auth*", status_code=200, body='{"token":"fake"}'
3. Den gemockten Endpunkt von Ihrem Client aus testen

Unter langsamen Netzwerkbedingungen testen:

1. Drosselung aktivieren: madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable
2. Oder MCP: madhyamas_set_throttle mit download_bps=50000, delay_ms=200, enabled=true
3. Reproduzieren Sie Ihren Workflow, um das Verhalten unter langsamen Bedingungen zu sehen