diagnose-network-printing

Diagnose Network Printing

Run a comprehensive diagnostic sequence to isolate printing issues. Stop at the first hard failure and surface the remediation hint.

When to use

• "The printer doesn't work" and user needs quick triage
• After configuration or network changes
• Before escalating to more detailed debugging
• Pre-flight after onboard setup

Inputs to gather

• None (uses env vars and config from onboard)

Procedure

Execute the following checks in sequence. Stop immediately on failure and show the remediation.

1. Check MCP_CUPS_SERVER env var.

Read MCP_CUPS_SERVER from environment.
If unset, read from ${CLAUDE_USER_DATA}/network-cups/config.json -> cups_server.
If still unset, emit: "CUPS server not configured. Run onboard skill."
Stop.

2. Test TCP reachability to CUPS port 631.

nc -zv -w 2 $MCP_CUPS_SERVER 631

If timeout/refused:

FAIL: Cannot reach CUPS server at $MCP_CUPS_SERVER:631.
Remediation:
  - Verify CUPS is running on the server: ssh <user>@$MCP_CUPS_SERVER systemctl status cups
  - Check firewall on the server: sudo ufw allow 631/tcp 631/udp
  - Verify hostname/IP is correct.
  - Run check-cups-firewall for local firewall audit.
Stop.

3. Check avahi-daemon is active (for Bonjour printer discovery).

systemctl is-active avahi-daemon

If inactive (but not a hard stop; just WARN):

WARN: avahi-daemon not running. Bonjour discovery will fail.
  To start: sudo systemctl start avahi-daemon
  To enable: sudo systemctl enable avahi-daemon
Continue to next check.

4. Attempt brief Bonjour browse.

timeout 3 avahi-browse -rt _ipp._tcp 2>/dev/null | head -5

If returns rows, output:

INFO: Found printers via Bonjour (sample output shown above).

If no rows:

WARN: No printers found via Bonjour. Printer may not support mDNS.
Continue to next check.

5. Audit firewall (summary of check-cups-firewall).

Run check-cups-firewall skill internally.
Emit one-line summary: "Firewall: PASS (631/tcp, 631/udp allowed)" or "Firewall: FAIL (see details below)".
If FAIL, show remediation commands inline.

6. Query MCP list_printers.

Call MCP tool list_printers via network-cups server.
If ≥1 printer returned, report: "PASS: <N> printer(s) registered on CUPS server."
If 0 printers, report: "WARN: No printers registered on CUPS server yet. Use add-printer or discover-printers-* to register one."
If MCP error (auth, connection), report: "FAIL: MCP connection failed: <error>. Check MCP_CUPS_SERVER and env vars."

Output / side effects

Emit a checklist like:

Network Printing Diagnostic (2026-04-30)

[PASS] MCP_CUPS_SERVER set to: cups.lan
[PASS] TCP 631 reachable (CUPS running)
[WARN] avahi-daemon inactive (Bonjour unavailable) — run: sudo systemctl start avahi-daemon
[PASS] Firewall: 631/tcp, 631/udp allowed
[PASS] 2 printers registered on CUPS

Result: Network printing healthy.

Or (on first failure):

Network Printing Diagnostic (2026-04-30)

[PASS] MCP_CUPS_SERVER set to: cups.lan
[FAIL] TCP 631 unreachable
       Remediation:
       - Verify CUPS running on cups.lan: ssh [email protected] systemctl status cups
       - Check server firewall: sudo ufw allow 631/tcp 631/udp on the CUPS host
       - Confirm DNS resolution: nslookup cups.lan

Stopped at step 2. Fix above and re-run.

No local files modified.

Safety / constraints

• Read-only diagnostic (except for check-cups-firewall which is also read-only).
• Safe to run repeatedly without side effects.
• Does not attempt to auto-fix; remediation hints are guidance only.