Add venv / PEP 668 / which-python guidance for pip install "mcp[cli]" in Module 20 (and M14/M15 local installs) #20

New Issue

2026-06-22T14:23:47-04:00

claude commented

2026-06-22 14:23:47 -04:00

Problem

The MCP lab's only install is pip install "mcp[cli]" with no venv. On modern Debian/Ubuntu and Homebrew Python, a global pip install aborts with "externally-managed-environment" (PEP 668), and pip/venv/packaging are never taught. Worse, the MCP config launches "command": "python", but pip may have installed mcp under a different interpreter, so the server crashes on import and the tool just reports "not connected" — the exact knowledge the persona lacks. M14's and M15's first local pip install hit the same PEP 668 wall.

Evidence

modules/20-mcp-servers-giving-the-ai-hands/README.md: pip install "mcp[cli]" (~lines 242/294); "(Use python3 or a venv's python if that's what runs the SDK)" (~line 305); troubleshooting "the SDK not installed for that interpreter" (~line 316).
M14 (~line 223) and M15 (~line 220): same bare local installs.

Why it matters

The lab's first step fails on common modern setups; Python/pip is the course's own chosen stack (M13-16), so adding guidance is not vendor creep — it serves the labs-must-work and honesty promises.

Proposed change

Add a short "Python packages and which python" sidebar:

Create a venv (or note pipx / --break-system-packages for PEP 668), install with python3 -m pip install "mcp[cli]".
Stress the install interpreter must match the config's launch command. Because the MCP client launches the server via PATH's python (not an activated venv), point the config "command" at the venv's ABSOLUTE python path (e.g. ~/…/venv/bin/python) — activating a venv alone does not fix the "not connected" failure.
Give a check: python3 -c "import mcp" (using the same interpreter the config will launch).
Add the same venv/PEP 668 note to M14's and M15's first local pip install.

Acceptance criteria

M20 explains venv/PEP 668 and the install succeeds on default Debian/Ubuntu/Homebrew.
The config "command" is pointed at the exact interpreter that has mcp installed.
An import check is provided; M14/M15 carry the same note.

Affected files

modules/20-mcp-servers-giving-the-ai-hands/README.md, modules/14-continuous-integration/README.md, modules/15-security-scanning/README.md

References

Source finding F34 (realVotes 3/3).

Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.

## Problem The MCP lab's only install is `pip install "mcp[cli]"` with no venv. On modern Debian/Ubuntu and Homebrew Python, a global `pip install` aborts with "externally-managed-environment" (PEP 668), and pip/venv/packaging are never taught. Worse, the MCP config launches `"command": "python"`, but pip may have installed `mcp` under a different interpreter, so the server crashes on import and the tool just reports "not connected" — the exact knowledge the persona lacks. M14's and M15's first local `pip install` hit the same PEP 668 wall. ## Evidence `modules/20-mcp-servers-giving-the-ai-hands/README.md`: `pip install "mcp[cli]"` (~lines 242/294); "(Use `python3` or a venv's python if that's what runs the SDK)" (~line 305); troubleshooting "the SDK not installed for that interpreter" (~line 316). M14 (~line 223) and M15 (~line 220): same bare local installs. ## Why it matters The lab's first step fails on common modern setups; Python/pip is the course's own chosen stack (M13-16), so adding guidance is not vendor creep — it serves the labs-must-work and honesty promises. ## Proposed change Add a short "Python packages and which python" sidebar: 1. Create a venv (or note `pipx` / `--break-system-packages` for PEP 668), install with `python3 -m pip install "mcp[cli]"`. 2. Stress the install interpreter must match the config's launch command. Because the MCP client launches the server via PATH's `python` (not an activated venv), point the config `"command"` at the venv's ABSOLUTE python path (e.g. `~/…/venv/bin/python`) — activating a venv alone does not fix the "not connected" failure. 3. Give a check: `python3 -c "import mcp"` (using the same interpreter the config will launch). 4. Add the same venv/PEP 668 note to M14's and M15's first local `pip install`. ## Acceptance criteria - [ ] M20 explains venv/PEP 668 and the install succeeds on default Debian/Ubuntu/Homebrew. - [ ] The config `"command"` is pointed at the exact interpreter that has `mcp` installed. - [ ] An import check is provided; M14/M15 carry the same note. ## Affected files - `modules/20-mcp-servers-giving-the-ai-hands/README.md`, `modules/14-continuous-integration/README.md`, `modules/15-security-scanning/README.md` ## References Source finding F34 (realVotes 3/3). --- *Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.*