# Pingo - Local LAN Debugging MCP Server

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

```bash
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.