netdiag-mcp

English | 日本語

Servidor MCP para diagnósticos de red bajo demanda: consultas DNS (con verificación del bit AD de DNSSEC), ping, informe de ruta basado en mtr, comprobaciones de puertos TCP, comprobaciones de estado/redirecciones HTTP, inspección de certificados TLS y WHOIS, todo desde un solo servidor.

Diseñado para diagnosticar informes de "no puedo llegar a X" / "¿ya se propagó el DNS?" sin tener que acceder mediante shell a un host de salto para cada dig/ping/curl puntual.

Herramientas

Todas las herramientas son de solo lectura y de un solo objetivo (sin modo de lote/barrido): son un envoltorio de conveniencia alrededor de comprobaciones que un operador haría a mano, no una herramienta de escaneo. El escaneo multi-host/multi-puerto estilo nmap está intencionalmente fuera del alcance; probar deliberadamente muchos hosts o puertos es una acción de mayor radio de impacto que merece su propio flujo de herramientas y aprobación.

tcp_port_check, http_check y tls_cert_check usan la pila propia de Python (socket/ssl/httpx) en lugar de invocar nc/curl/openssl mediante shell, de modo que estas tres herramientas funcionan incluso en un host donde solo estén instalados los binarios dig/ping/mtr/whois (o ninguno de ellos: health_check informa cuáles faltan sin que falle todo el servidor).

dns_lookup/dnssec_check admiten DNS sobre TLS y DNS sobre HTTPS mediante transport="dot"/"doh" (los +tls/+https de dig). Esto requiere dig de BIND 9.18+; un dig más antiguo rechaza la opción directamente en lugar de recurrir silenciosamente a DNS simple, de modo que un binario desactualizado falla de forma visible en lugar de dar una falsa sensación de haber comprobado un transporte cifrado.

tls_cert_check/http_check contra una dirección IP simple pueden fallar el handshake TLS con un error de "handshake failure" o similar en orígenes alojados con SNI / tras un CDN (p. ej., detrás de Cloudflare): la extensión SNI de TLS solo transporta nombres de host, por lo que un literal de IP no puede enrutar al certificado correcto en un borde compartido. Esto es un comportamiento normal de TLS, no un error de la herramienta; comprueba por nombre de host cuando el objetivo esté tras un CDN.

Configuración

1. Dependencias del sistema

dns_lookup, dnssec_check, ping_host, traceroute_path y whois_lookup invocan mediante shell a dig, ping, mtr y whois respectivamente. Instala los que quieras tener disponibles:

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

mtr necesita acceso a sockets sin procesar. El paquete mtr-tiny de Debian/Ubuntu otorga cap_net_raw al helper mtr-packet en el momento de la instalación, por lo que normalmente funciona para un usuario de servicio sin privilegios sin configuración adicional; verifica con getcap "$(command -v mtr-packet)" si traceroute_path informa un error de permisos de socket. Sin esa capacidad, traceroute_path falla limpiamente con un ToolError en lugar de provocar un fallo del servidor.

2. Instalación

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

3. Claude Code (manual)

claude mcp add netdiag -- netdiag-mcp

No se requieren variables de entorno.

CLI

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

Notas de seguridad

• Cada llamada a un binario externo pasa una lista argv (nunca una cadena de shell), de modo que ningún argumento de herramienta puede romper la sintaxis de shell.

• Los argumentos de nombre de host/IP y puerto se validan y se limitan en tamaño/rango antes de usarse: la entrada de las herramientas está impulsada por el modelo y se trata como no confiable, igual que cualquier otra superficie de llamada a herramientas.

• tcp_port_check se conecta exactamente a un host:puerto por llamada; no hay argumento de bucle ni de rango, por diseño.

Desarrollo

Prueba de humo en vivo

Las pruebas unitarias verifican la lógica contra datos de prueba; no pueden detectar que una herramienta haya dejado de devolver datos reales (un binario dig/ping/mtr/whois muerto, un almacén de confianza TLS roto, una red que bloquea ICMP saliente). scripts/smoke_test.py ejecuta cada herramienta registrada contra puntos finales públicos reales y falla si las respuestas están vacías, malformadas o son errores:

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

• Sin inventario, por lo que cada objetivo es un punto final público fijo: el 1.1.1.1 de Cloudflare y el example.com de IANA (reservados para uso en documentación/pruebas, RFC 2606). Este servidor no toma configuración y no tiene nada de qué descubrir un objetivo, a diferencia de un servidor MCP de flota de dispositivos de esta familia.

• tests/test_smoke_probes.py es la mitad sin conexión: solo verifica que cada herramienta registrada tenga una especificación de prueba (y viceversa), de modo que la CI detecte una herramienta añadida sin decidir cómo sabría alguien que funciona, sin necesidad de acceso a red.

Licencia

MIT