Lab Guide

Lesson 03 · MCP Servers · Scaffold the PKB project and verify it loads

This lab is intentionally short. The goal is to leave with one thing working: mcp dev pkb/server.py opens Inspector pointed at an empty PKB server. We are not adding any tools yet — that's the very first task of Plan B Lesson 04. Today is purely about getting the skeleton installed, the entry point wired, and the Inspector handshake confirmed so you have a known-good starting point for every subsequent lesson.

What you need

• The Python virtual environment from Lesson 01 (or recreate it: python -m venv .venv && source .venv/bin/activate).
• mcp[cli]>=1.0.0 installed in that venv. The [cli] extra is what gives you the mcp command, including mcp dev.
• npx on your PATH — mcp dev shells out to it to launch the MCP Inspector. Any recent Node.js install includes it.

Step 1 — cd into the sample-server skeleton

The PKB skeleton already exists in the repository (created by Plan A Task 4). Start from there rather than scaffolding a new project from scratch — that way every lesson works against the same layout.

cd mcp-servers/sample-server/python
ls

You should see at minimum pyproject.toml, pkb/__init__.py, and pkb/server.py. If any of these are missing, stop and check that you cloned the repo cleanly — the rest of the lab assumes they are present.

Step 2 — Install the project in editable mode

Editable mode (-e) means changes to pkb/ are picked up immediately without a reinstall. This is the only sane way to develop a Python package you are actively editing.

pip install -e .

The install reads pyproject.toml, registers the pkb console-script entry point, and pulls in mcp[cli] as a dependency if it isn't already present. A successful run ends with Successfully installed pkb-0.1.0 (version may differ).

Step 3 — Run the entry point (should fail loudly)

The skeleton's pkb command is intentionally wired to refuse to start until Lesson 04 adds the first tool. This is a sanity check that the install worked — the failure is the success signal.

pkb

Expected output:

SystemExit: pkb server has no tools yet — start at lesson 04…

If you see this exact message, the package is installed, the console script is on your PATH, and you are ready to talk to it via mcp dev. If you get pkb: command not found instead, see Troubleshooting below.

Step 4 — Launch with mcp dev

mcp dev imports your server module, spins up an stdio transport, and launches the MCP Inspector (via npx) wired to it. It's the canonical "is my server alive?" check.

mcp dev pkb/server.py

Expected output: a couple of log lines from the SDK, then an Inspector URL like http://localhost:6274. Open it in a browser — you should see the PKB server connected, with an empty tools list. That is the correct state for Lesson 03. The whole point of this lesson is to feel what an empty server looks like before Lesson 04 starts filling it in.

Leave Inspector running while you do Step 5; we want it active so the next lesson opens with the shortest possible path back to a working setup.

Step 5 — Inspect the Server object from Python

One more sanity check, this time from a Python REPL — just to confirm the module imports cleanly and the server object is exactly what you expect. Open a fresh terminal in the same venv:

python -c "import pkb.server; print(pkb.server.server)"

Expected output (repr may vary slightly between SDK versions):

<Server name='pkb' version='0.1.0'>

If the import fails with ModuleNotFoundError: No module named 'pkb', your pip install -e . silently didn't take — re-run Step 2 with the venv definitely activated.

What you should leave with

• The PKB project is installed in editable mode in your venv.
• mcp dev pkb/server.py launches Inspector against the empty PKB server.
• You have a clear mental picture: the server is wired, the transport works, but there are no tools yet — and that's exactly what Plan B Lesson 04 is going to fix by adding the first tool inside pkb/server.py.

Troubleshooting