vision-upgrade — VisionSqueezer Upgrade Skill

Detects install method, flushes npx cache, re-registers MCP with a pinned version, and verifies the MCP can spawn after upgrade. Single self-healing pass.

Why this skill is non-trivial

npx -y vision-squeezer caches the resolved tarball in ~/.npm/_npx. After a release bump, the cache does not refresh; users keep running the old version even though npm view shows the new one. This was the root cause behind multiple "MCP failed to connect" reports.

The fix is two-layered:

1. The installer now registers the MCP with an explicit version: npx -y [email protected].

Cache busts automatically on every upgrade.

1. This skill nukes ~/.npm/_npx and re-registers MCP with the new pinned version, so users on

old (unpinned) registrations get migrated to the pinned scheme.

Trigger

/vision-upgrade or any of: "vision upgrade", "upgrade vision-squeezer", "update vision-squeezer", "install latest vision-squeezer", "fix vision-squeezer", "vision-squeezer broken — fix it".

Pass --force (or user says "force"/"reset"/"clean") to:

• Wipe the npx cache directory entirely.
• Force-remove and re-add the MCP registration in every Claude scope.
• Run the binary install command with --force.

Action

Step 1 — Detect state

LATEST=$(npm view vision-squeezer version 2>/dev/null)
NPM_GLOBAL=$(npm list -g vision-squeezer --depth=0 2>/dev/null | grep vision-squeezer | head -1)
CARGO_BIN=""
[ -x "$HOME/.cargo/bin/vision-squeezer" ] && CARGO_BIN="$HOME/.cargo/bin/vision-squeezer"
MCP_LINE=$(claude mcp list 2>/dev/null | grep -i vision-squeezer | head -1)
# Parse the pinned version out of `[email protected]` if present:
MCP_PINNED=$(echo "$MCP_LINE" | grep -oE 'vision-squeezer@[0-9]+\.[0-9]+\.[0-9]+' | sed 's/vision-squeezer@//')
echo "LATEST=$LATEST"
echo "NPM_GLOBAL=$NPM_GLOBAL"
echo "CARGO_BIN=$CARGO_BIN"
echo "MCP_LINE=$MCP_LINE"
echo "MCP_PINNED=$MCP_PINNED"

Pick install method by priority (first that matches wins):

• CARGO_BIN non-empty → cargo
• NPM_GLOBAL non-empty → npm-global
• MCP_LINE non-empty → npx (pinned if MCP_PINNED non-empty, else unpinned)
• otherwise → not-installed — tell user to run npx vision-squeezer install

Step 2 — Run the matching upgrade command

cargo:

cargo install vision-squeezer --force

npm-global:

npm install -g vision-squeezer@latest

npx (pinned or unpinned): No binary install needed — npx -y vision-squeezer@$LATEST will fetch it. Skip to Step 3.

Step 3 — Flush npx cache

Always, regardless of install method (npx cache may have a stale build that another tool spawns):

rm -rf "$HOME/.npm/_npx"

Step 4 — Re-register MCP with pinned latest version

If MCP_LINE was found in Step 1, re-register so the registered command points at the new version:

# Capture existing scope before remove. `claude mcp list -s user|local|project` outputs
# the registration only if scope matches; the first non-empty scope wins.
SCOPE=""
for s in user local project; do
  if claude mcp list -s "$s" 2>/dev/null | grep -q vision-squeezer; then SCOPE="$s"; break; fi
done
[ -z "$SCOPE" ] && SCOPE="user"  # safest default

claude mcp remove vision-squeezer -s "$SCOPE" 2>/dev/null
claude mcp add -s "$SCOPE" vision-squeezer -- npx -y "vision-squeezer@${LATEST}"

For --force mode, also remove from the other two scopes (in case the user had duplicates):

for s in user local project; do
  [ "$s" = "$SCOPE" ] && continue
  claude mcp remove vision-squeezer -s "$s" 2>/dev/null || true
done

Step 5 — Verify MCP can spawn

Probe the registered command — give it 5s to print a JSON-RPC ready signal on stdin/stdout.

# Portable 8s probe — macOS lacks GNU `timeout`, so use python3.
# 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".
PROBE=$(python3 - "$LATEST" "$HOME" <<'PY' 2>&1
import subprocess, sys
ver = sys.argv[1]
home = sys.argv[2]
req = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"vision-upgrade","version":"1"}}}\n'
try:
    r = subprocess.run(['npx', '-y', f'vision-squeezer@{ver}'], input=req, capture_output=True, text=True, timeout=8, cwd=home)
    if r.stdout:
        print(r.stdout.splitlines()[0])
    if r.stderr:
        print(r.stderr[:2000], file=sys.stderr)
except subprocess.TimeoutExpired as e:
    print("PROBE_TIMEOUT after 8s", file=sys.stderr)
PY
)
echo "$PROBE" | head -1 | grep -q '"jsonrpc"' && echo "PROBE=ok" || echo "PROBE=fail: $PROBE"

If PROBE=fail, surface the captured output to the user and suggest:

• vision-upgrade --force (clear cache, re-register from scratch).
• Report the captured stderr verbatim — most failures are postinstall download errors

(HTTP 403 / 404 / network), and the message tells the user what to do.

Output format

## VisionSqueezer Upgrade

- [x] Latest (npm): <LATEST>
- [x] Detected install: <cargo / npm-global / npx-pinned / npx-unpinned>
- [x] Previous version: <MCP_PINNED or "unknown (unpinned npx)">
- [x] Ran upgrade: <cargo install / npm install -g / skipped (npx)>
- [x] Flushed npx cache: ~/.npm/_npx
- [x] Re-registered MCP: vision-squeezer@<LATEST> (scope: <SCOPE>)
- [x] MCP probe: ✅ connected / ❌ <reason>
- [x] Status: ✅ Upgraded <OLD> → <LATEST>

If the probe failed:

- [ ] MCP probe: ❌ <captured-error>

Fix: vision-upgrade --force

Notes

• Do not tell users "npx always pulls latest" — that statement is wrong now that the

installer pins versions in the MCP registration. The pinned version freezes them until this skill re-registers.

• If claude CLI is missing, run only Steps 1–3 and tell the user to re-register manually

with npx vision-squeezer install.

• For Codex/Qwen users, replace claude mcp with codex mcp / qwen mcp — same command shape.