Testing/CI/tooling consistency (#9,#20,#21,#22,#23,#28) (#59)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>

modules/20-mcp-servers-giving-the-ai-hands/README.md

@@ -239,10 +239,40 @@ is the one that lands the concept.
 - Your agentic coding tool from Module 4, which is the **MCP client**. Find, in its docs, *where it
   reads MCP server configuration* and *how it shows that a server is connected* (often a list of
   connected servers or available tools).
-- Python 3.10+ and the official MCP Python SDK: `pip install "mcp[cli]"`.
+- Python 3.10+ and the official MCP Python SDK, installed into a virtual environment — read the
+  **Python packages and which `python`** note just below *before* you run `pip`.
 - The starter files in this module's `lab/` folder: `tasks_mcp_server.py` and
   `mcp-config-example.json`.
 
+> **Python packages and which `python`.** This lab's one dependency is the MCP SDK, and *how* you
+> install it decides whether the server ever connects. Two things bite people:
+>
+> - **PEP 668 ("externally-managed-environment").** On modern Debian/Ubuntu and Homebrew Python, a
+>   global `pip install` is refused on purpose. The clean fix is a virtual environment per project:
+>
+>   ```bash
+>   cd ~/workflow-course/tasks-app
+>   python3 -m venv .venv                       # one-time
+>   source .venv/bin/activate                   # Windows: .venv\Scripts\activate
+>   python3 -m pip install "mcp[cli]"
+>   ```
+>
+>   (If you'd rather not manage a venv: `pipx`, or `pip install --break-system-packages` — but a venv
+>   is the clean default and keeps this lab's dependency out of your system Python.)
+> - **The install interpreter must match the config's launch command.** Your MCP client starts the
+>   server by running the `"command"` in its config — *not* your activated shell — so activating a
+>   venv does nothing to help the client find the SDK. You must point `"command"` at the venv's
+>   **absolute** python path (e.g. `~/workflow-course/tasks-app/.venv/bin/python`, or
+>   `...\.venv\Scripts\python.exe` on Windows). If they don't match, the server dies on `import mcp`
+>   and your tool just says "not connected" with no obvious reason — the exact failure this lab is
+>   about avoiding.
+>
+> Before wiring anything, verify with the *same* interpreter the config will launch:
+>
+> ```bash
+> ~/workflow-course/tasks-app/.venv/bin/python -c "import mcp; print('mcp ok')"
+> ```
+
 ### Part A — Connect an existing server (warm-up, ~10 min)
 
 Before building anything, prove the plumbing works by connecting a server someone else already
@@ -291,8 +321,8 @@ That's the entire client/server loop, end to end, with zero code you wrote. Now
 2. Sanity-check it starts. From inside `tasks-app`:
 
    ```bash
-   pip install "mcp[cli]"      # once
-   python tasks_mcp_server.py  # it will sit there waiting for a client — that's correct
+   python3 -m pip install "mcp[cli]"   # into the venv from the note above, once
+   python tasks_mcp_server.py          # it will sit there waiting for a client — that's correct
    ```
 
    It looks like it's hanging. It isn't — a stdio server waits for a client on its stdin/stdout.
@@ -301,20 +331,26 @@ That's the entire client/server loop, end to end, with zero code you wrote. Now
 ### Part C — Wire it into your agentic tool
 
 3. Open `lab/mcp-config-example.json`. Copy the `tasks` entry into wherever your tool reads MCP
-   config, and replace the path with the **absolute** path to your `tasks_mcp_server.py`. (Use
-   `python3` or a venv's python if that's what runs the SDK on your system.)
+   config. Set `"command"` to the **absolute path of the python that has `mcp` installed** — the venv
+   python from the note above, *not* a bare `python` — and set `args` to the **absolute** path to
+   your `tasks_mcp_server.py`:
 
    ```json
    "tasks": {
-     "command": "python",
+     "command": "/ABSOLUTE/PATH/TO/workflow-course/tasks-app/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/workflow-course/tasks-app/tasks_mcp_server.py"]
    }
    ```
 
+   (On Windows the venv python is `...\.venv\Scripts\python.exe`.) A bare `"command": "python"` is the
+   single most common reason the server "won't connect": the client launches whatever `python` is on
+   *its* PATH, which is usually not the interpreter that has the SDK.
+
 4. Reload your agentic tool and confirm it shows the `tasks` server **connected**, with `list_tasks`
    and `add_task` among its available tools. If it doesn't connect, the usual culprits are a wrong
-   path, the wrong `python`, or the SDK not installed for that interpreter — check the tool's MCP
-   logs.
+   path, the wrong `python`, or the SDK not installed for that interpreter — re-run the
+   `... .venv/bin/python -c "import mcp"` check from the note above against the *exact* path you put
+   in `"command"`, then check the tool's MCP logs.
 
 ### Part D — Watch the AI use its new hands
 

modules/20-mcp-servers-giving-the-ai-hands/lab/mcp-config-example.json

@@ -1,8 +1,8 @@
 {
-  "_comment": "Common shape of an MCP server entry for a local (stdio) server. Many agentic tools accept this 'mcpServers' map; yours may use a different key or location (check its docs). Replace the path with the ABSOLUTE path to tasks_mcp_server.py in your tasks-app. Use 'python3' instead of 'python' if that's what your system calls it, or the full path to a virtualenv's python.",
+  "_comment": "Common shape of an MCP server entry for a local (stdio) server. Many agentic tools accept this 'mcpServers' map; yours may use a different key or location (check its docs). IMPORTANT: 'command' must be the ABSOLUTE path to the python interpreter that has the MCP SDK installed (e.g. your venv's python) -- a bare 'python' makes the client launch whatever is on its PATH, which usually does NOT have the SDK, and the server then reports 'not connected'. On Windows the venv python is ...\\.venv\\Scripts\\python.exe. Set 'args' to the ABSOLUTE path to tasks_mcp_server.py in your tasks-app.",
   "mcpServers": {
     "tasks": {
-      "command": "python",
+      "command": "/ABSOLUTE/PATH/TO/workflow-course/tasks-app/.venv/bin/python",
       "args": ["/ABSOLUTE/PATH/TO/workflow-course/tasks-app/tasks_mcp_server.py"]
     }
   }