Add "lessons/patterns/mcp-venv-symlinks-lost-on-marketplace-update---5-hour-debug-loop"

lessons%2Fpatterns%2Fmcp-venv-symlinks-lost-on-marketplace-update---5-hour-debug-loop.-.md

@@ -0,0 +1,67 @@
+# MCP Venv Symlinks Lost on Marketplace Update
+
+**Date:** 2026-02-02
+**Severity:** Critical (5+ hours wasted)
+**Affected:** All MCP-dependent plugins (projman, contract-validator, data-platform, viz-platform, cmdb-assistant, pr-review)
+
+## Context
+
+User was working on branch `fix/startup-hook-venv-cache-path` to fix venv path issues in startup hooks. After marketplace reinstalls, plugins repeatedly failed to load with "1 error" message.
+
+## Problem
+
+1. **MCP server venvs are stored in cache:** `~/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv`
+2. **Source has symlinks:** `~/claude-plugins-work/mcp-servers/{server}/.venv` → cache
+3. **Installed marketplace loses symlinks:** When Claude Code reinstalls/updates the marketplace, the `.venv` symlinks are NOT copied to `~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/{server}/`
+4. **No postInstall hooks:** Claude Code marketplaces do NOT support postInstall hooks (feature requested in GitHub issue #11240)
+5. **SessionStart hooks can't fix it:** MCP servers fail BEFORE hooks run, so startup-check.sh can't auto-create symlinks in time
+
+## What Was Tried (All Failed to Identify Root Cause)
+
+- ✅ Verified plugin.json files are valid JSON
+- ✅ Verified hooks.json format is correct
+- ✅ Verified hook scripts are executable
+- ✅ Verified MCP server references match .mcp.json
+- ✅ Verified commands directories exist
+- ✅ Ran validate-marketplace.sh - all passed
+- ✅ Verified cache venvs exist and work
+- ✅ MCP servers start successfully when invoked manually
+
+**Critical Gap:** Claude Code does NOT expose the actual plugin load error message. User sees "failed to load - 1 error" with no way to see WHAT the error is.
+
+## Actual Fix (Temporary)
+
+Run `setup-venvs.sh` in the installed marketplace path:
+```bash
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace
+./scripts/setup-venvs.sh
+```
+
+This creates symlinks in the installed path. But they get wiped on next update.
+
+## Proper Fix Needed
+
+1. **Option A:** Make `run.sh` auto-create symlinks before starting MCP server
+2. **Option B:** Have Claude Code preserve symlinks during marketplace updates
+3. **Option C:** Wait for postInstall hooks feature (GitHub issue #11240)
+
+## Prevention
+
+1. **After ANY marketplace reinstall/update:** Run `setup-venvs.sh` in installed path
+2. **Document this prominently:** Add to README and CLAUDE.md
+3. **Consider:** Making all MCP paths absolute to cache instead of relative with symlinks
+
+## Claude AI Failures in This Session
+
+1. Said "Found it!" multiple times without actually finding the root cause
+2. Kept checking things that turned out to be fine
+3. Did not identify that the actual error message is hidden from users
+4. Took 5+ hours of user time without resolving the underlying issue
+5. The SessionStart hook fix added won't help because MCP servers fail before hooks run
+
+## Tags
+plugins, mcp, venv, symlinks, marketplace, installation, critical-bug
+
+
+---
+**Tags:** plugins, mcp, venv, symlinks, marketplace, critical-bug, time-waste, claude-failure