# Workshop assistant

An MCP server that lets a language model answer questions about a garage's
workshop — open jobs, vehicle history, parts stock, the day's bookings — by
querying the workshop database directly instead of guessing.

Built as a learning project while working through Anthropic's Model Context
Protocol material. The database is fictional; the point is the interface
between the model and the business system, not the data behind it.

---

## The problem

A service manager starts the day with a handful of questions that are boring
to answer and expensive to get wrong:

- Which jobs are stuck waiting on a part, and how long have they been stuck?
- Has this car been in before for the same fault?
- What does Tuesday look like — is there room to fit someone in?
- Do we have front pads in stock, or does that job need ordering first?

Every one of these is a join across two or three tables. A person answers them
by opening several screens and holding the result in their head. It is exactly
the kind of repeated lookup that gets skipped when the workshop is busy, which
is when getting it wrong costs the most.

An assistant that can read the workshop database answers them in one sentence.

## Why MCP rather than a chatbot with the data pasted in

A language model on its own knows nothing about this workshop, and pasting the
database into a prompt does not scale past a few dozen rows — nor does it stay
current for more than a minute.

MCP is the contract between the two. The server below advertises six named
tools with typed arguments. The model chooses which to call and with what
arguments; the server runs a reviewed SQL query and returns plain structured
data. The model's job is to interpret the question and present the answer. The
database's job is to be correct. Neither has to know how the other works.

## Design decisions

**Narrow tools, not a general `run_sql`.** One tool that executes arbitrary SQL
would be far more flexible and much worse. It would make the model responsible
for correctness against a schema it has only been told about, and it would hand
a language model unrestricted write access to a live business system. Six
specific tools mean each query is written and reviewed once, by a person, and
the model only picks between them.

**Read-only by default.** The five read tools open the database with
`mode=ro`, so a bug in a query cannot modify anything. Only `add_job_note`
opens a writable connection. There is a test that asserts this.

**One write tool, deliberately dull.** `add_job_note` appends a note. It cannot
change a job's status, its parts or its price — those are decisions that need a
person, and an agent that can quietly re-price a job is a liability, not a
feature. Adding a note is genuinely useful (chasing a supplier, recording a
call) and safe to get wrong.

**Empty results say so.** Every tool returns an explicit `message` when nothing
matched. Handed a bare empty list, a model will often fill the silence with a
plausible-sounding job card that does not exist.

**The interesting query is its own tool.** `jobs_blocked_on_parts` could be
assembled by the model from `search_jobs` and `parts_availability`, but that
means three round trips and a join done in the model's head. It is the question
the workshop actually asks every morning, so it gets a tool.

**The database path is resolved in one place.** `workshop.db.database_path()`
reads the `WORKSHOP_DB` environment variable and falls back to `garage.db` in
the project root. That one indirection is what lets the test suite build a
fresh throwaway database for every single test, so no test can leak state into
another and any test can be run on its own.

## The tools

| Tool | What it answers |
|---|---|
| `search_jobs` | Job cards, filtered by status, registration plate or technician |
| `vehicle_history` | Every visit for one vehicle, plus technician notes |
| `parts_availability` | Stock levels, with a low-stock filter |
| `jobs_blocked_on_parts` | Open jobs where a required part is short |
| `technician_schedule` | Bookings for a day, with bay, hours and job |
| `add_job_note` | *(write)* Append a note to a job card |

## Layout

```
src/workshop/
    db.py          connection handling and where the database lives
    seed.py        the fictional workshop, and the script that builds it
    server.py      the six MCP tools
    schema.sql     eight tables, shipped inside the package
tests/
    conftest.py    a freshly seeded database per test
    test_tools.py  38 tests
.mcp.json          project-scoped MCP registration, no absolute paths
pyproject.toml     dependencies, entry points, ruff, mypy, pytest
```

## Running it

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync             # creates .venv and installs everything, including dev tools
uv run workshop-seed   # builds garage.db
uv run pytest          # 38 tests
```

The MCP SDK is pinned to the 1.x line. Version 2.0 renamed `FastMCP` to
`MCPServer` and moved its import path with no deprecation period, so this
server does not run unmodified on 2.x.

### From Claude Code

`.mcp.json` is committed, so from inside a clone of this repo there is nothing
to configure — Claude Code picks the server up automatically and asks once
whether to trust it. To register it by hand instead:

```bash
claude mcp add garage-workshop -- uv run --directory /absolute/path/to/workshop-mcp-server workshop-mcp
```

### From Claude Desktop

`claude_desktop_config.json` has no notion of a project directory, so this one
does need an absolute path:

```json
{
  "mcpServers": {
    "garage-workshop": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/workshop-mcp-server", "workshop-mcp"]
    }
  }
}
```

## Development

```bash
uv run pytest        # 38 tests
uv run ruff check .  # lint and import order
uv run ruff format . # formatting
uv run mypy          # types, with disallow_untyped_defs
```

All four are clean on `main`.

## Example session

> **Which jobs are blocked waiting on parts?**
>
> Three jobs are held up:
>
> - **1013** — MT66 ZXB (BMW 320d), MOT failure, catalytic converter. None in
>   stock, on order from Driveline Components. Open 9 days.
> - **1014** — GK17 OPL (Vauxhall Astra), clutch slipping, clutch kit. None in
>   stock. Open 6 days.
> - **1015** — BF15 NRV (Audi A4), timing belt kit. Needs 2, one in stock, so
>   short by one. Open 4 days.
>
> The BMW has been waiting longest, and Derek's note from the day it came in
> says the supplier quoted 7–10 days — that was nine days ago, so it is worth
> chasing today.

> **Has the BMW been in before for this?**
>
> Not for the emissions failure, but it has a repeat history worth knowing
> about. MT66 ZXB has been in three times. Seven months ago it came in for an
> intermittent starting fault and had a battery fitted; three months ago it came
> back with the same symptom and the alternator was replaced. Derek's note on
> the second visit says the charging voltage was low at idle — so the battery
> replacement had treated the symptom rather than the cause.

> **Add a note to 1013 saying I chased the supplier and it's due Thursday.**
>
> Added to job card 1013 (MT66 ZXB, MOT failure — catalytic converter):
> "Chased supplier, catalytic converter due Thursday." Note 6.

## What I would add next

- The parts data has a `supplier` column but nothing uses it. A tool that
  groups outstanding orders by supplier would turn three separate chase-up
  calls into one.
- `technician_schedule` reports booked hours but not free capacity, so it can
  tell you what Tuesday looks like but not whether a job fits.
- No authentication or audit trail. Fine for a local prototype, the first thing
  I would need for anything real — a note written by an agent should record
  that it was written by an agent.

## A note on the data

Every customer, vehicle, registration plate, phone number and email address in
`src/workshop/seed.py` is invented for this project. The phone numbers use
Ofcom's reserved `07700 900xxx` range and the email addresses use
`example.com`, both of which exist precisely so that test data cannot collide
with a real person.