Pingo Network

An MCP server exposing a full toolkit for debugging your local network, wired through a clean service-per-concern architecture so it's easy to extend.

Tools exposed

Tool	What it does
get_network_interfaces	Lists local IPv4 interfaces (name, IP, netmask, MAC)
ping_device	Pings a single IPv4 address, reports alive/latency
ping_sweep	Sweeps a /24-/32 CIDR to discover live hosts (concurrency-limited)
traceroute	OS-native traceroute/tracert to a host or IP
dns_lookup	Resolves a hostname to its IPv4/IPv6 addresses
reverse_dns_lookup	Resolves an IP back to hostname(s)
check_port	Checks if a single TCP port is open
scan_port_range	Scans a range of TCP ports (max 1024 span) via raw sockets
get_arp_table	Reads the OS ARP cache -> IP-to-MAC mappings on the LAN
get_active_connections	Lists active connections via netstat, optional port filter
check_http_reachability	Checks if an HTTP(S) endpoint responds, with status + latency

Design notes

• One service per concern (src/services/*) - each does exactly one job and is injected into the controller, so adding a new diagnostic (e.g. MTU discovery, bandwidth test) means adding one new service + one registerTool call, nothing else changes.
• No shell injection surface. Every OS command runs through execFile (argv array, never a shell string), and every input is validated against a strict allow-list (src/utils/validators.ts) before it ever reaches a command or socket.
• Bounded by default. Port scans cap at a 1024-port span, sweeps cap at /24, everything has a timeout - so a bad input can't hang the process or turn into an unbounded network scan.
• DNS uses Node's native dns/promises, not a shell command at all - one less exec surface for the riskiest-sounding tool.

Run it

pnpm install
pnpm dev        # tsx src/index.ts, hot-reload dev mode
pnpm build && pnpm start   # compiled prod run

Server listens on http://localhost:3000/mcp.

Extending it

1. Add src/services/YourService.ts implementing an IYourService interface (mirror the existing services - constructor-free, one focused method or two).
2. Add it to PingoServices in PingoMcpController.ts and instantiate it in src/index.ts.
3. Add one server.registerTool(...) block in registerTools().

That's the whole extension surface - no other files need to change.