Add "lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures"

lessons%2Fpatterns%2Fsession-2026-02-02---mcp-server-venv-package-installation-failures.-.md

@@ -0,0 +1,34 @@
+## Context
+
+User reported projman and contract-validator plugins not working with no error messages. Multiple debugging sessions required to identify root cause.
+
+## Problem
+
+1. **Venvs existed but packages weren't installed** - The `.venv` directories existed in `mcp-servers/*/` but the actual Python packages weren't installed in editable mode (`pip install -e .`)
+
+2. **setup.sh created venvs but didn't always install packages** - Race conditions or incomplete runs left venvs without the required packages
+
+3. **No clear error messages** - Plugins just showed "failed to load · 1 error" without details
+
+4. **Gitignored venvs disappear on updates** - `.venv` is in `.gitignore`, so marketplace updates wipe the venvs since they're never committed
+
+## Solution Applied
+
+1. Manually ran `pip install -e .` in each affected MCP server directory
+2. Removed `rm -rf .venv` from `setup-venvs.sh` - now skips existing venv directories instead of deleting them
+3. Added **SACRED RULE** to both CLAUDE.md files: NEVER DELETE .venv without explicit user approval
+
+## Prevention
+
+1. **NEVER delete .venv directories automatically** - This rule is now in CLAUDE.md
+2. **After marketplace updates**: Always run `./scripts/setup.sh` from installed marketplace
+3. **Verify packages installed**: Check with `python -c "from mcp_server import server"` in each MCP server dir
+4. **setup.sh must be idempotent**: Should safely re-run without destroying existing work
+
+## Times User Was Made to Debug This: Multiple times in one session
+
+## Tags
+venv, mcp-servers, setup, installation, gitignore, packages
+
+---
+**Tags:** venv, mcp-servers, setup, installation, debugging, painful-lesson