MCP relay framework for administering appliances (NAS, router) with token auth, forensic audit, and gated command execution
Strong foundation with clear naming, comprehensive descriptions, and proper schema definitions. Most tools follow verb_noun patterns (system_info, restart_service, firewall_show). Descriptions are detailed and contextual (avg ~180 chars), explaining WHAT, WHEN, and prerequisites. Input schemas are well-typed with enums for constrained inputs (e.g., restart_service.name has 17 allowed values). However, output schemas are not formally documented in the code, responses are described narratively rather than as structured JSON Schema. Error handling is present but inconsistent: some tools mention transport_error and recovery paths, others do not. Tool composition is excellent: read-only Tier A tools are separated from reversible Tier B and destructive Tier C operations, enabling proper agent gating. Duplicate tool names (system_info, disk_usage, performance, internet_exposure, pending_updates appear twice across router and synology variants) suggest code reuse but risk LLM confusion if both are registered in a single server.
Tier A — connected clients (DHCP + ARP + wireless). Merges three sources for completeness: dnsmasq DHCP leases (hostname + IP), ARP table (MAC + IP), and wireless clients (MAC + RSSI/rate). Returns {dhcp_leases, arp_table, wireless_clients}.
Tail logs for a container by name. Use list_containers first to find the exact name. Returns {rc, stdout, stderr} from `docker logs`.
Tier A — DHCP leases from dnsmasq.leases (hostname, IP, MAC, expiry). Parses the lease file directly; does NOT query dnsmasq (which would require a socket or ubus call).
Tier A — SSH transport self-test. Round-trips a cheap `nvram get model` and reports latency, rc, and the transport_error flag (set when ssh ITSELF fails, rc 255).
Tier A — filesystem usage (df -h). Returns {rc, stdout, stderr}.
Output schemas not formally documented. Tool descriptions state what is returned (e.g., '{dhcp_leases, arp_table, wireless_clients}') but no JSON Schema definitions are visible in the code. LLMs cannot reliably extract fields from narrative descriptions.
Duplicate tool names across router and synology variants (system_info, disk_usage, performance, internet_exposure, pending_updates). If both servers are registered in a single MCP instance, LLM will be confused about which variant to call.
Inferred effective spec: 2026-07-28+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 67 | 2026-07-28+ | v2 |
Filesystem usage (df -h).
Tier B — disable the DSM firewall (synosystemctl stop firewall). Briefly interrupts network filtering.
Tier B — enable the DSM firewall (synosystemctl start firewall). Briefly interrupts network filtering.
Tier A — DSM firewall rules (iptables -L -n -v). Returns {filter, nat, mangle} tables.
Tier A — firewall rules (iptables -L -n -v). Returns {filter, nat, mangle} tables.
Tier A — DSM firewall status (enabled/disabled) and rule count. Reads from synoinfo.conf and counts rules in /etc/iptables/rules.v4.
Tier A — all network interfaces (ip link show + ip addr show). Returns {interfaces: [{name, state, mtu, mac, addrs}]}.
Tier A — authoritative external-access posture: QuickConnect, DDNS, UPnP, port forwarding, reverse proxy. Each channel reports {enabled, ...detail, source, confidence} where confidence is 'authoritative' | 'heuristic' | 'unknown'. CRITICAL: 'unknown' (no evidence either way) is NEVER collapsed into 'disabled' — conflating those is exactly how the 2026-05 audit wrongly cleared QuickConnect (it read /etc/synoinfo.conf, which has no quickconnect key). Raw probe outputs are included under 'signals' so the authority mapping can be refined from observation. Secret-ish values (DDNS creds, registration tokens) are not returned.
Tier A — authoritative external-access posture: WAN admin, SSH, telnet, port forwards, UPnP, DMZ, DDNS, AiCloud, OpenVPN, WireGuard, IPv6 firewall, FTP, port triggering. Reads ONLY a frozen allowlist of nvram keys (never `nvram show`); no credentials are returned.
All Docker / Container Manager containers (docker ps -a).
Tier A — firmware update posture (current build, available build, update URL). Reads nvram only; does NOT phone home.
Tier A — update posture in DISTINCT buckets (don't flatten): DSM OS, Package Center packages, externally/vendor-managed (e.g. Tailscale, which Package Center lags), and a pointer to container-image drift. `synopkg checkupdateall` phones home, so it runs with an extended timeout.
Tier A — resource pressure snapshot with operator-grade summary fields (load relative to core count, swap pressure, instantaneous iowait, top processes). Missing metrics (e.g. CPU temp on boxes without hwmon) report 'unavailable' rather than failing the call.
Tier A — resource pressure snapshot with operator-grade summary fields (load relative to core count, swap pressure, instantaneous iowait, top processes).
Tier A — read a text file from the target host. Use for inspecting configs/logs instead of run(). Restricted to allowed roots (secret paths are denied; a policy error lists the allowed roots). Returns {path, content}; content is truncated at the read cap.
Tier B — reboot the router (approval- AND confirm-gated). Requires a confirmation token from a prior call. Returns {rc, stdout, stderr}; transport_error may be set if SSH drops during reboot.
Tier B — restart a single container by name (docker restart). Briefly interrupts the container's service. Returns {rc, stdout, stderr}; stdout echoes the name on success.
Tier B — restart a DSM service (synosystemctl reload-or-restart <name>). Briefly interrupts that service. DSM 7 replaced synoservicectl with synosystemctl; the old binary 404s on 7.x. Returns {rc, stdout, stderr}.
Tier B — restart a Merlin service (service restart_<name>). Briefly interrupts the service. Returns {rc, stdout, stderr}.
Tier C — execute an arbitrary shell command on the router (gated by dry-run + one-time exec_token). First call without exec_token returns a token; replay with the token to execute. Denylist blocks catastrophic patterns (rm -rf /, mkfs, firmware flashing, factory reset, indirect reboots). Returns {rc, stdout, stderr, transport_error}.
Active status of a DSM service (synosystemctl get-active-status <name>). DSM 7 replaced synoservicectl with synosystemctl; the old binary 404s on 7.x. Returns {rc, stdout, stderr}; stdout is the status token (e.g. 'active').
SMART health for every detected disk: scan, then `-H` per device.
Router identity: kernel (uname -a), Merlin firmware (build/version), uptime, load, memory.
Kernel/host identity (uname -a) and DSM version.
Tier A — WAN link status (IP, gateway, DNS, connection state, uptime). Reads nvram + /proc/net/route + resolv.conf.
Tool 'run' has generic name that does not clearly convey it executes arbitrary shell commands. Better names: 'execute_command', 'run_shell_command', or 'exec_shell'. Current name risks LLM confusion with other 'run' operations.
Error handling guidance is inconsistent. Some tools (diagnostics, reboot_router, run) document transport_error and recovery paths; others (clients, dhcp_leases, interfaces) do not mention error cases or recovery strategies. LLMs need explicit error classification (retryable, user-fixable, fatal).
Destructive tool 'run' accepts arbitrary commands with only a denylist guard (rm -rf /, mkfs, firmware flashing, factory reset). Denylist-based security is fragile; consider whitelist-based command approval or stronger sandboxing for production use.