lmiranda
2d51df7a42
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
Virtual Environment Diagnostics Skill
Patterns for checking virtual environment health in MCP server directories.
Check 1: Venv Exists
test -d <server_cwd>/.venv && echo "EXISTS" || echo "MISSING"
If missing, the server will fail to start. Fix:
cd <server_cwd> && python3 -m venv .venv
Check 2: Python Binary Intact
Venvs can break when the system Python is upgraded (symlink becomes dangling).
<server_cwd>/.venv/bin/python --version 2>&1
If error contains "No such file or directory" despite .venv existing, the symlink is broken.
Fix:
cd <server_cwd> && rm -rf .venv && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
IMPORTANT: Never delete .venv without explicit user approval. Show the diagnosis and ask user to confirm the fix.
Check 3: Requirements Satisfied
Compare requirements.txt with installed packages:
cd <server_cwd> && .venv/bin/pip freeze > /tmp/installed.txt
Then diff against requirements.txt:
- Missing packages: In requirements but not installed
- Version mismatch: Installed version does not satisfy requirement specifier
- Extra packages: Installed but not in requirements (usually OK, may indicate stale venv)
Quick check:
cd <server_cwd> && .venv/bin/pip check 2>&1
This reports broken dependencies (missing or incompatible versions).
Check 4: Module Import Test
Verify the server's main module can be imported:
cd <server_cwd> && .venv/bin/python -c "import mcp_server.server" 2>&1
Common failures:
| Error | Cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'mcp' |
MCP SDK not installed | pip install mcp |
ModuleNotFoundError: No module named '<pkg>' |
Missing dependency | pip install -r requirements.txt |
ImportError: cannot import name 'X' |
Version mismatch | pip install --upgrade <pkg> |
SyntaxError |
Python version too old | Check python3 --version >= 3.10 |
Check 5: Broken Symlinks
Find broken symlinks in the venv:
find <server_cwd>/.venv -type l ! -exec test -e {} \; -print 2>/dev/null
Any output indicates broken symlinks that may cause import failures.
Health Summary Format
### Venv: <server_name>
- Directory: EXISTS
- Python: 3.11.2 (OK)
- Packages: 12 installed, 10 required, 0 missing
- Import: OK
- Broken symlinks: 0
- Status: HEALTHY