personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures
Pages
Change V5.4.0: Multi-Model Agent Support Proposal Change V5.4.0: Multi-Model Support (Sprint 7 Implementation) Change V04.1.0: Proposal (Implementation 1) Change V04.1.0: Proposal Change-V5.2.0:-Plugin-Enhancements-(Sprint-4-Commands) Change-V5.2.0:-Plugin-Enhancements-(Sprint-5-Documentation) Change-V5.2.0:-Plugin-Enhancements-Proposal.- Change-V5.5.0:-Hook-Efficiency-Quick-Wins-(Sprint-8-Implementation) Change-V5.6.0:-Domain-Advisory-Pattern-(Sprint-9-Implementation).- Change V5.6.0: Domain Advisory Pattern Proposal Change-V5.7.0:-Data-Platform-Domain-Advisory-(Sprint-10-Implementation) RFC-Hook-Efficiency-Improvements RFC-Perf-Sentinel-Plugin Sprint-1-viz-platform-Implementation-Plan branding/header-templates branding/plugin-registry branding/progress-templates branding/visual-spec lessons/patterns/agent-model-field-not-supported-by-claude-code lessons/patterns/command-frontmatter-missing-name-field-causes-silent-load-failure lessons/patterns/hook-message-wording-affects-claude-continuation-behavior lessons/patterns/mcp-venv-symlinks-lost-on-marketplace-update---5-hour-debug-loop lessons/patterns/mcp_servers-field-in-pluginjson---another-failed-debug-theory lessons/patterns/plugin-hooks-must-be-in-separate-file-not-inline lessons/patterns/plugin-load-errors---missing-name-field-in-command-frontmatter lessons/patterns/plugin-load-failure---check-command-frontmatter-first lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements lessons/patterns/plugin-version-mismatch-causes-silent-load-failure lessons/patterns/reset-pandas-index-after-filtering-to-prevent-column-pollution lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures lessons/patterns/setup-wizard-url-format-mismatch lessons/patterns/sprint-4---new-commands-not-discoverable-until-session-restart lessons/patterns/startup-hooks-must-check-venv-cache-path-first lessons/patterns/sync-entire-plugin-directory-not-individual-files lessons/patterns/use-fixes-n-keyword-for-automatic-issue-closing-in-prs lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session lessons/sprints/sprint-1---viz-platform-plugin-implementation lessons/sprints/sprint-10---domain-advisory-pattern-replication-success lessons/sprints/sprint-2---contract-validator-plugin-implementation lessons/sprints/sprint-3---agent-runaway-detection-and-timeout-handling lessons/sprints/sprint-3---background-agent-permissions-must-be-pre-granted lessons/sprints/sprint-3---mcp-server-branch-detection-bug-runs-from-installed-dir lessons/sprints/sprint-4---plugin-commands-implementation lessons/sprints/sprint-6---visual-branding-and-documentation-maintenance lessons/sprints/sprint-8---parallel-hook-optimization-success lessons/sprints/v400-release---wiki-workflow-and-versioning-patterns lessons/sprints/versioning-workflow---use-unreleased-and-release-script lessons-learned/sprints/hook-efficiency-rfc unnamed
Clone
1
lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures
Leo Miranda edited this page 2026-02-03 04:06:02 +00:00
Table of Contents

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