netdiag-mcp

English | 日本語

MCP-Server für On-Demand-Netzwerkdiagnosen – DNS-Abfragen (mit DNSSEC-AD-Bit-Prüfung), Ping, ein mtr-basierter Pfadbericht, TCP-Portprüfungen, HTTP-Status-/Weiterleitungsprüfungen, TLS-Zertifikatsprüfung und WHOIS, alles von einem Server aus.

Entwickelt für die Bearbeitung von Meldungen wie „X nicht erreichbar“ / „Ist DNS bereits propagiert?“, ohne sich für jedes einzelne dig/ping/curl auf einen Sprungserver einloggen zu müssen.

Tools

Alle Tools sind schreibgeschützt und auf ein einzelnes Ziel ausgerichtet (kein Stapel-/Scanmodus) – dies ist ein Komfort-Wrapper um Prüfungen, die ein Operator von Hand ausführen würde, kein Scan-Tool. nmap-artiges Multi-Host-/Multi-Port-Scannen ist bewusst nicht Teil des Umfangs; das absichtliche Sondieren vieler Hosts oder Ports ist eine andere Aktion mit größerem Schadensradius, die eine eigene Tool-Unterstützung und einen eigenen Genehmigungsablauf verdient.

tcp_port_check, http_check und tls_cert_check verwenden Pythons eigenen Socket/ssl/httpx-Stack, anstatt nc/curl/openssl als externe Prozesse aufzurufen. Diese drei Tools funktionieren daher auch auf einem Host, auf dem nur die Binaries dig/ping/mtr/whois installiert sind (oder gar keine – health_check meldet, welche fehlen, ohne den gesamten Server zu stoppen).

dns_lookup/dnssec_check unterstützen DNS-over-TLS und DNS-over-HTTPS über transport="dot"/"doh" (die +tls-/+https-Optionen von dig). Dafür wird dig aus BIND 9.18+ benötigt – ein älteres dig lehnt das Flag komplett ab, anstatt still auf normales DNS zurückzufallen. Ein veraltetes Binary schlägt also deutlich fehl, statt ein falsches Gefühl zu vermitteln, über einen verschlüsselten Transport geprüft zu haben.

tls_cert_check/http_check können bei einer reinen IP-Adresse auf SNI-gehosteten bzw. hinter einem CDN liegenden Origins (z. B. bei Cloudflare) mit einem „handshake failure“ oder einem ähnlichen Fehler im TLS-Handshake fehlschlagen – die SNI-Erweiterung von TLS überträgt nur Hostnamen, daher kann ein IP-Literal an einem gemeinsam genutzten Edge nicht zum richtigen Zertifikat führen. Das ist normales TLS-Verhalten und kein Tool-Fehler; prüfen Sie über den Hostnamen, wenn das Ziel hinter einem CDN liegt.

Einrichtung

1. Systemabhängigkeiten

dns_lookup, dnssec_check, ping_host, traceroute_path und whois_lookup rufen dig, ping, mtr bzw. whois als externe Prozesse auf. Installieren Sie, welche davon Sie benötigen:

# Debian/Ubuntu
sudo apt install dnsutils iputils-ping mtr-tiny whois

mtr benötigt Zugriff auf Raw-Sockets. Das Debian/Ubuntu-Paket mtr-tiny gewährt dem Helfer mtr-packet bei der Installation cap_net_raw, sodass es normalerweise ohne weitere Einrichtung für einen unprivilegierten Dienstbenutzer funktioniert – überprüfen Sie es mit getcap "$(command -v mtr-packet)", wenn traceroute_path einen Socket-Berechtigungsfehler meldet. Ohne diese Fähigkeit schlägt traceroute_path sauber mit einem ToolError fehl, anstatt den Server zum Absturz zu bringen.

2. Installation

pip install netdiag-mcp
# or
uv tool install netdiag-mcp

3. Claude Code (manuell)

claude mcp add netdiag -- netdiag-mcp

Es sind keine Umgebungsvariablen erforderlich.

CLI

netdiag-mcp --version   # print version
netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)

Sicherheitshinweise

• Jeder Aufruf eines externen Binaries übergibt eine argv-Liste (niemals einen Shell-String), sodass kein Tool-Argument in die Shell-Syntax ausbrechen kann.

• Hostname/IP- und Port-Argumente werden vor der Verwendung validiert und in Größe/Bereich begrenzt – Tool-Eingaben sind modellgesteuert und werden als nicht vertrauenswürdig behandelt, genau wie bei jeder anderen Tool-Aufruffläche.

• tcp_port_check verbindet sich pro Aufruf mit genau einem Host:Port; es gibt bewusst kein Schleifen- oder Bereichsargument.

Entwicklung

Live-Smoke-Test

Unit-Tests prüfen die Logik anhand von Fixtures; sie können Ihnen nicht sagen, dass ein Tool aufgehört hat, echte Daten zurückzugeben (ein defektes dig/ping/mtr/whois-Binary, ein defekter TLS-Trust-Store, ein Netzwerk, das ausgehenden ICMP-Verkehr blockiert). scripts/ smoke_test.py führt jedes registrierte Tool gegen echte öffentliche Endpunkte aus und schlägt bei leeren, fehlerhaften oder Fehlerantworten fehl:

uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only ping --traceback

• Kein Inventar, daher ist jedes Ziel ein fester öffentlicher Endpunkt – Cloudflares 1.1.1.1 und IANAs example.com (für Dokumentations-/Testzwecke reserviert, RFC 2606). Dieser Server akzeptiert keine Konfiguration und hat nichts, woraus es ein Ziel ermitteln könnte, anders als ein MCP-Server für Geräteflotten in dieser Familie.

• tests/test_smoke_probes.py ist die Offline-Hälfte: Es prüft nur, dass jedes registrierte Tool eine Probe-Spezifikation hat (und umgekehrt), sodass die CI ein hinzugefügtes Tool erkennt, für das nicht entschieden wurde, wie man erkennen kann, dass es funktioniert – ganz ohne Netzwerkzugriff.

Lizenz

MIT