vision-doctor — VisionSqueezer Health Check Skill

Reports accurate state for all three install paths (cargo / npm-global / npx) and actively probes the MCP server. Every failure line ends with a single recovery command — typically vision-upgrade (or vision-upgrade --force).

Trigger

/vision-doctor or any of: "vision doctor", "check vision-squeezer", "is vision-squeezer up to date", "vision-squeezer broken", "MCP not connecting", "vision-squeezer not working", "vision-squeezer version".

Action — Step 1: Detect state

LATEST=$(npm view vision-squeezer version 2>/dev/null)

# Direct binary (cargo / npm global)
BIN=$(command -v vision-squeezer 2>/dev/null)
[ -z "$BIN" ] && [ -x "$HOME/.cargo/bin/vision-squeezer" ] && BIN="$HOME/.cargo/bin/vision-squeezer"
INSTALLED=""
[ -n "$BIN" ] && INSTALLED=$("$BIN" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)

# MCP registration — parse the actual command + pinned version
MCP_LINE=$(claude mcp list 2>/dev/null | grep -i vision-squeezer | head -1)
MCP_PINNED=$(echo "$MCP_LINE" | grep -oE 'vision-squeezer@[0-9]+\.[0-9]+\.[0-9]+' | sed 's/vision-squeezer@//')
MCP_MODE=""
if [ -n "$MCP_LINE" ]; then
  if [ -n "$MCP_PINNED" ]; then MCP_MODE="npx-pinned";
  elif echo "$MCP_LINE" | grep -q npx; then MCP_MODE="npx-unpinned";
  else MCP_MODE="binary"; fi
fi

# What version is the user effectively running?
EFFECTIVE=""
case "$MCP_MODE" in
  npx-pinned) EFFECTIVE="$MCP_PINNED" ;;
  binary)     EFFECTIVE="$INSTALLED" ;;
  npx-unpinned) EFFECTIVE="unknown (unpinned npx — cache decides)" ;;
esac
[ -z "$EFFECTIVE" ] && [ -n "$INSTALLED" ] && EFFECTIVE="$INSTALLED"

echo "LATEST=$LATEST"
echo "BIN=$BIN"
echo "INSTALLED=$INSTALLED"
echo "MCP_LINE=$MCP_LINE"
echo "MCP_MODE=$MCP_MODE"
echo "MCP_PINNED=$MCP_PINNED"
echo "EFFECTIVE=$EFFECTIVE"

Action — Step 2: Active MCP probe

If MCP_LINE non-empty, spawn the registered MCP command and send an initialize request. Capture stderr — most failures are postinstall download errors that the message reveals.

# Reconstruct the runnable command from the MCP_LINE. Fields after the colon are the command.
# Format examples:
#   vision-squeezer: npx -y [email protected] - ✓ Connected
#   vision-squeezer: /Users/x/.cargo/bin/vision-squeezer-mcp - ✗ Failed to connect
CMD=$(echo "$MCP_LINE" | sed -E 's/^[^:]+:[[:space:]]*//' | sed -E 's/[[:space:]]+- (✓|✗).*$//')
[ -z "$CMD" ] && CMD="npx -y vision-squeezer@${LATEST}"

# Use python3 for a portable 8s timeout (macOS lacks GNU `timeout`).
# cwd=$HOME because npx checks the cwd's package.json — if the user happens to
# be inside the vision-squeezer project dir (name collision), npx skips the
# install and the probe false-negatives with "command not found". Running from
# $HOME guarantees a neutral resolution context.
PROBE_OUT=$(python3 - "$CMD" "$HOME" <<'PY' 2>&1
import subprocess, sys, json
cmd = sys.argv[1]
home = sys.argv[2]
req = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"vision-doctor","version":"1"}}}\n'
try:
    r = subprocess.run(cmd, shell=True, input=req, capture_output=True, text=True, timeout=8, cwd=home)
    if r.stdout:
        print(r.stdout.splitlines()[0])
    if r.stderr:
        print("---STDERR---", file=sys.stderr)
        print(r.stderr[:2000], file=sys.stderr)
except subprocess.TimeoutExpired as e:
    print("PROBE_TIMEOUT after 8s", file=sys.stderr)
    if e.stderr:
        print(e.stderr[:2000].decode('utf-8', errors='replace'), file=sys.stderr)
PY
)
if echo "$PROBE_OUT" | head -1 | grep -q '"jsonrpc"'; then
  echo "PROBE=ok"
else
  echo "PROBE=fail"
  echo "PROBE_STDERR<<EOF"
  echo "$PROBE_OUT" | head -20
  echo "EOF"
fi

Output format

Display as a markdown checklist with accurate per-mode language. Never claim "npx always pulls latest" — that statement is wrong now that the installer pins versions.

## VisionSqueezer Doctor

- [x] Latest (npm):       <LATEST>
- [x] Install mode:       <cargo / npm-global / npx-pinned / npx-unpinned / not-installed>
- [x] Effective version:  <EFFECTIVE>
- [x] MCP registered:     <yes (scope: X, mode: Y) / no>
- [x] MCP probe:          <✅ connected / ❌ <one-line reason>>
- [x] Status:             <see status table below>

Status logic

When probe fails, include the captured stderr verbatim:

MCP probe failed. Captured output:

    <PROBE_STDERR first 20 lines>

Fix: vision-upgrade --force

When not installed:

## VisionSqueezer not found

Install:
  npx vision-squeezer install

Notes

• The MCP probe is the only authoritative health signal. Registration without successful

probe is a broken install — surface the stderr so the user (or [[vision-upgrade]]) can act.

• npx-pinned is the new default — registered as npx -y [email protected]. The pinned

version is the effective version; it does not auto-update to npm latest.

• npx-unpinned exists for users on old installs that pre-date the pin change. Recommend

vision-upgrade to migrate them to the pinned scheme.

• For Codex/Qwen users, replace claude mcp list with codex mcp list / qwen mcp list.