fuel-mcp
# fuel-mcp
Fuel prices near a place, said in one sentence: an MCP server and claude-voice plugin.
Ask for a fuel near a point, and it names the cheapest station in one
sentence. The made-up stations sit around the point 0,0, far out at sea.
They touch no network, and every answer says it is simulated:
```console
$ uv run fuel-mcp price --simulate --lat 0 --lon 0
Simulated: Diesel is cheapest at Fake Fuel Beta, nineteen seventy-nine, 2 kilometres away. Drivstoffpriser's price is about a day old.
Data: Drivstoffpriser (ODbL), stations © OpenStreetMap contributors
```
The same tool is served to a voice session over stdio, and the server stops
when its input closes:
```console
$ uv run fuel-mcp serve --simulate < /dev/null
```
## The tool
| Tool | What it does |
| --- | --- |
| `fuel_price` | Names the cheapest station within about 5 km, its price, distance and age. It reads only. |
It takes `fuel` (`diesel`, the default, `petrol95` or `petrol98`), and the
phone's position as `lat`, `lon` and `accuracy_m`. The search widens by the
position's accuracy, which is taken as 100 m when not given. With no
position, it asks where. A price more than a week old is never said as
current: it is given with the day it was last reported.
## Real prices
No price source is on until you list one. Settings live in
`~/.config/fuel-mcp/config.toml`, never in this repository. Home is used
when the voice gives no position:
```toml
sources = ["drivstoffpriser"] # one source; with none listed, nothing is fetched
[home]
lat = 0.0
lon = 0.0
```
With Drivstoffpriser listed, its export is checked at most once an hour,
and only when someone asks
([ADR-FM-001](decisions/ADR-FM-001-check-the-export-hourly-with-a-conditional-get.md)).
The copy is kept in `~/.cache/fuel-mcp/`. Its times are read as Norwegian
time, because the app stores the reporting phone's local time.
A mistake in the file is said with the fix:
```console
$ XDG_CONFIG_HOME=tests/settings-examples uv run fuel-mcp price
unknown source 'petrolbot'; the known ones are drivstoffpriser. Fix sources in tests/settings-examples/fuel-mcp/config.toml
```
## The data
Data: Drivstoffpriser (ODbL), stations © OpenStreetMap contributors.
Prices come from [Drivstoffpriser](https://github.com/Drivstoffpriser/Drivstoffpriser-App),
a community project whose open data is free to use for any purpose. Every
answer carries that credit in its `credit` field, and says how old its price is.
## The gates
Every one of these runs in continuous integration, and all of them run here:
```console
$ uv run ruff check .
All checks passed!
```
<!-- not run: the workflow runs each of these; nesting them here would run the suite inside itself -->
```bash
uv run ruff format --check . # layout
uv run mypy src # types
uv run pytest -q # behaviour
python scripts/mutate.py # that each rule's own test can fail
```
`CONTRIBUTING.md` says what each one is for, and
[`decisions/`](decisions/README.md) records the choices that shaped them,
including how a change is made here.
## Licence
GPL-3.0-or-later. See [LICENSE](LICENSE).
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of misselection between overlapping tools. Its purpose (find the cheapest nearby fuel price, read-only) is unambiguous.
A single snake_case name, 'fuel_price', is clean and readable. It is a noun phrase rather than a verb_noun pattern, but with one tool there is no internal inconsistency.
The server's scope is genuinely narrow (one lookup), so a single tool is defensible, but 1 tool is on the thin side of the scale. There is no coverage for adjacent needs such as listing multiple stations or choosing fuel type.
The core read operation is covered, but notable gaps exist: no fuel-type selection (petrol/diesel/etc.), no way to return more than the single cheapest station, and no radius or sort control. These are workable but real limitations.