Skip to main content
Glama
Workshop Assistant

Workshop Assistant

by sayan1xs

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.

Related MCP server: Jobber MCP Server

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.

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:

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:

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

Development

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.

Available Tools

6 tools
add_job_noteA

Add a note to a job card.

The only tool here that changes anything. It is narrow on purpose: it can append a note and nothing else. It cannot alter a job's status, its parts or its price - those are decisions that need a person.

Args: job_card: The job card ID to attach the note to. note: The text of the note. author: Who the note is from.

Inputs: note (required), job_card (required), author. Returns: object

jobs_blocked_on_partsA

Open job cards that cannot proceed because a required part is short.

This is the question a service manager actually asks each morning, and it is the reason the assistant is worth having: answering it by hand means cross-referencing every open job against the stock list.

Inputs: no named parameters. Returns: object

parts_availabilityA

Look up parts stock.

Args: query: Part name or SKU, full or partial. Omit to list everything. only_low_stock: If true, return only parts at or below reorder level.

Inputs: query, only_low_stock. Returns: object

search_jobsA

Search job cards in the workshop.

Args: status: One of booked, in_progress, waiting_parts, completed, invoiced. Use "open" for anything not yet finished. reg: Registration plate, full or partial (e.g. "LM19" or "LM19 KTZ"). technician: Technician name, full or partial. limit: Maximum number of job cards to return.

Inputs: reg, limit, status, technician. Returns: object

technician_scheduleA

Workshop bookings for a given day.

Args: day: ISO date (YYYY-MM-DD), or "today" / "tomorrow". Defaults to today. technician: Technician name, full or partial. Omit for the whole workshop.

Inputs: day, technician. Returns: object

vehicle_historyA

Full service history for one vehicle, newest first.

Use this to answer questions like "has this car been in before for the same fault?" - repeat visits for one symptom are the useful signal.

Args: reg: Registration plate, full or partial.

Inputs: reg (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct query: jobs, vehicle history, parts stock, blocked jobs, schedule, and notes. The overlap between search_jobs and jobs_blocked_on_parts is minimal because the latter is a specific cross-reference of open jobs against parts shortages, making their purposes clearly separable.

    Naming Consistency4/5

    All tool names use snake_case and are descriptive, but they mix verb-noun (search_jobs, add_job_note) with noun-noun (vehicle_history, parts_availability) forms. The style is consistent and no naming is chaotic, though a stricter verb_noun pattern would make it fully predictable.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a workshop assistant. Each tool serves a clear purpose and there is no bloat or sense of missing essential tools for the intended read-heavy, note-taking workflow.

    Completeness4/5

    The surface covers the core informational needs: job search, vehicle history, parts availability, blocked jobs, and technician schedules, plus a narrow note-adding action. It intentionally excludes job creation or status changes, which is clearly stated, so only minor gaps exist for full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to interact with the Shopmonkey REST API to manage shop management data including work orders, customers, vehicles, and inventory. It provides 33 tools across 9 resource groups with built-in support for rate limiting, concurrency control, and multi-location management.
      69
      3
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Enables AI assistants to access and manage Jobber field-service data including clients, jobs, invoices, and quotes through natural language interactions.
      6
      79 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI tools to Remapdb vehicle tuning data, enabling search and retrieval of manufacturers, models, engines, and tuning information.
      190 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to decode VINs, check stolen vehicle databases, and retrieve market valuations through natural language.
      3
      -