# Career Copilot MCP

An MCP server over 2,253 US Data Analyst job postings — plus a from-scratch MCP client, because the fastest way to stop treating a protocol as magic is to implement it.

![Python](https://img.shields.io/badge/python-3.11+-blue)
![MCP](https://img.shields.io/badge/MCP-2.0_SDK-000000)
![Tests](https://img.shields.io/badge/tests-27_passing-green)

Week 5 of my **Learning in Public** roadmap. [Week 2](../week2_salaray_predictor) trained a salary model in a notebook. [Week 3](../week3-fastpi) put a model behind an async FastAPI service so a *person* could call it. This week: what does it take for an **AI agent** to call it?

---

## What this is

A deliberately small server that exercises **all three MCP primitives**, because most examples only ship tools — which quietly reduces MCP to "function calling with extra steps".

| Primitive | Controlled by | In this server |
|---|---|---|
| **Tools** | the model | `search_jobs`, `salary_benchmark`, `skill_demand` |
| **Resources** | the client app | `market://snapshot`, `market://locations` |
| **Prompts** | the human | `career_gap_review` |

The distinction is the actual protocol. A tool is something the model *decides* to call, with arguments it chooses. A resource is addressable read-only data with no arguments — the client attaches it to context like a `GET`, so making the model "call" for it wastes a round trip. A prompt is a template the *user* picks from a menu; the model never invokes it.

## Quick start

```bash
uv sync && uv pip install -e .
```

Watch the entire protocol run, with no SDK and no LLM in the loop:

```bash
uv run python client/raw_client.py --verbose
```

Run the suite:

```bash
uv run python -m pytest tests/ -q
```

### Connect it to Claude Code

```bash
claude mcp add career-copilot -- uv --directory /absolute/path/to/mcp-week-5 run python -m career_copilot_mcp.server
```

<details>
<summary>Claude Desktop config</summary>

```json
{
  "mcpServers": {
    "career-copilot": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-week-5", "run", "python", "-m", "career_copilot_mcp.server"]
    }
  }
}
```
</details>

---

## MCP is not magic

It is JSON-RPC 2.0 as newline-delimited JSON over a subprocess's stdin/stdout, with an agreed method vocabulary. Here is a real session, captured from `client/raw_client.py --verbose` (truncated for width):

```jsonc
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"raw-client","version":"0.1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{…},"resources":{…},"tools":{…}},"protocolVersion":"2025-11-25","serverInfo":{"name":"career-copilot"}}}

→ {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}          // a notification: no id, no reply

→ {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search_jobs","description":"Find Data Analyst job postings…","inputSchema":{…},"outputSchema":{…},"annotations":{"readOnlyHint":true}}, …]}}

→ {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"salary_benchmark","arguments":{"location":"San Francisco, CA","skill":"python"}}}
← {"jsonrpc":"2.0","id":6,"result":{"content":[…],"isError":false,"structuredContent":{"median":92500,"p25":80500,"p75":126000,…}}}
```

Eight calls is the entire surface this server uses: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`.

### The handshake does the compatibility work

The client asks for `2026-07-28`. The server answers `2025-11-25` — the newest version *it* speaks. Nobody errors and nobody upgrades:

| client asks | server answers |
|---|---|
| `2026-07-28` (newer than the server) | `2025-11-25` |
| `2025-11-25` | `2025-11-25` |
| `2025-06-18` | `2025-06-18` |
| `2024-11-05` | `2024-11-05` |
| `1999-01-01` (nonsense) | `2025-11-25` |

That is why an MCP client written months ago still works against a server shipped today. The compatibility lives in the handshake, not in your code.

---

## Four things that cost me time

### 1. The tool description *is* the prompt

It's the only thing the model reads when deciding whether to call a tool and what to pass. `location: str` tells it nothing. This does:

```python
location: US metro in "City, ST" form, e.g. "New York, NY" or "Austin, TX".
    A partial name like "Austin" is accepted when it is unambiguous. Read
    market://snapshot for the most common values before guessing.
```

A test enforces it, because descriptions rot silently:

```python
assert len(tool["description"]) > 80, f"{tool['name']} description is too thin"
```

### 2. `-> dict` gives you no output schema

My tools returned a JSON *string* inside a text block. The client had to `json.loads` it and guess at the shape. The SDK won't let you paper over this:

```
InvalidSignature: Function search_jobs: return type <class 'dict'> is not
serializable for structured output
```

Typed returns (`TypedDict`) generate an `outputSchema` that ships with the tool in `tools/list`, and results come back in `structuredContent` — machine-readable, not text to re-parse.

### 3. An error is a result, not a crash

An agent can retry against a suggestion. It cannot retry against silence. So an unknown location returns a message naming valid ones:

```
No postings found for location 'Bangalore'. This dataset covers US metros only.
Try one of: New York, NY, Chicago, IL, San Francisco, CA, Austin, TX, …
```

The connection stays up, `isError: true` comes back as a normal result, and a test asserts the server is still answering afterwards.

### 4. The model cannot sanity-check your data

This one is the real lesson, and it wasn't an MCP bug at all — it was a data bug that MCP made dangerous.

Week 2 detected skills with a naive substring match. `"excel" in description` also matches **"excellent"**. `"aws"` matches **"laws"**, **"draws"**, **"flaws"**.

| skill | substring match | word-boundary match | inflation |
|---|---|---|---|
| excel | 1,354 (60.1%) | 903 (40.1%) | **+50%** |
| aws | 275 (12.2%) | 132 (5.9%) | **+108%** |
| spark | 89 | 71 | +25% |
| sql | 1,389 | 1,387 | — |

In a notebook, a wrong number is a chart I squint at. Behind an MCP tool, it is a number the model repeats to a user in a confident sentence, with my name on the server. There is no error, no exception, no signal — just a wrong answer delivered well.

`SQL` keeps its substring exception on purpose: `mysql` and `postgresql` really do mean SQL.

---

## Every test earns its place

Week 3's rule, carried forward: a test that still passes after you delete the code it covers was never testing anything. `scripts/verify_tests.py` removes each fix and checks the suite notices.

```bash
uv run python scripts/verify_tests.py
```

| fix removed | suite notices |
|---|---|
| word-boundary skill matching | yes |
| limit clamp (`1 ≤ limit ≤ 25`) | yes |
| actionable unknown-location error | yes |
| truncation reporting | yes |
| `readOnlyHint` annotations | yes |
| **stray `print()` in a tool body** | **no — and that's the finding** |

Running it caught **two tests that tested nothing**:

- The skill-matching tests asserted against the `SKILL_PATTERNS` constant, not against loaded data. They proved the regex was well-formed, not that the pipeline used it. Mutating the call site didn't break them. They now assert on real postings.
- The stdout test only called `tools/list` — so a `print()` inside a *tool body* never ran. It now exercises every handler.

### The footgun that isn't

Every MCP guide says the same thing: over stdio your stdout **is** the wire, so one stray `print()` corrupts the stream and kills the client. I wrote a test for it. With `print("stray print", flush=True)` added to a tool body, **the test passed** — and the client kept working.

`mcp/server/stdio.py` explains why. While serving, the transport claims fd 1: it duplicates the real wire to a private descriptor, then points fd 1 at a duplicate of **stderr**.

```python
def _open_stdout_diversion() -> int:
    try:
        return os.dup(2)          # fd 1 now goes wherever stderr goes
    except OSError:
        return os.open(os.devnull, os.O_WRONLY)
```

Verified end to end: the stray print never reaches the wire, and lands on stderr instead. (`stdin` gets the same treatment against `/dev/null`, so handlers and child processes read EOF rather than eating protocol bytes.)

So logging to stderr is still correct — the spec asks for it, and it's what a client surfaces to you as server logs. But the reason usually given for it is, for this SDK at this version, folklore. I'd have shipped that folklore in a comment if I hadn't tried to break my own test.

---

## Layout

```
src/career_copilot_mcp/
  market.py     data layer — no MCP imports, so the logic is testable without a server
  server.py     the protocol adapter: 3 tools, 2 resources, 1 prompt
client/
  raw_client.py a ~200-line MCP client. No SDK. Speaks JSON-RPC at a subprocess.
scripts/
  verify_tests.py  deletes each fix, checks the suite notices
tests/
  test_market.py    the data layer
  test_protocol.py  spawns the real server and speaks JSON-RPC at it
```

`market.py` has no MCP imports on purpose. The protocol layer should be a thin adapter over plain functions — the same logic could be served over HTTP or a CLI without touching it.

## Data

`data/DataAnalyst.csv` — 2,253 Glassdoor Data Analyst postings, the same dataset as Weeks 1–2. A 2020 US-metro snapshot: a historical reference, not live market data. The server says so in its `instructions` field, so the model tells users that too.