Skip to main content
Glama
README.md
# 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

A3.9/5.0

Scored across 1 tool

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness3/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues