From 13def03fd0cfa0008303565e34dfcd5606a33275 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Tue, 3 Feb 2026 04:06:02 +0000 Subject: [PATCH] Add "lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures" --- ...er-venv-package-installation-failures.-.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 lessons%2Fpatterns%2Fsession-2026-02-02---mcp-server-venv-package-installation-failures.-.md diff --git a/lessons%2Fpatterns%2Fsession-2026-02-02---mcp-server-venv-package-installation-failures.-.md b/lessons%2Fpatterns%2Fsession-2026-02-02---mcp-server-venv-package-installation-failures.-.md new file mode 100644 index 0000000..8d66a1a --- /dev/null +++ b/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 \ No newline at end of file