Add MCP server, --min-price floor, tests, and CI (v0.1.0)

- --min-price drops placeholder prices (e.g. 1.000) that polluted --cheapest
- MCP server (pitstop-mcp, optional [mcp] extra) exposes list_fuels,
  find_stations, find_cheapest over the same core as the CLI
- extract shared core.query_stations / core.response_envelope
- pytest suite (parsing, join, haversine, price filtering) and GitHub Actions CI

Author: galjos

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  mcp-import:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[mcp]"
+      - run: python -c "import pitstop.mcp_server; print('mcp server imports OK')"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims
 to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0] - 2026-05-29
+
+### Added
+- `--min-price` floor on `pitstop stations` to drop placeholder/junk prices
+  (e.g. `1.000`) that otherwise pollute `--cheapest`.
+- **MCP server** (`pitstop-mcp`, optional `[mcp]` extra) exposing `list_fuels`,
+  `find_stations`, and `find_cheapest` over the same core as agent tools.
+- pytest test suite covering parsing, the registry+price join, geo distance,
+  and price filtering.
+- GitHub Actions CI (tests on Python 3.10/3.12, MCP import check, wheel build).
+
+### Changed
+- Filtering and sorting moved into a shared `core.query_stations` /
+  `core.response_envelope` used by both the CLI and the MCP server.
+
 ## [0.0.1] - 2026-05-29
 
 Initial release.
@@ -26,4 +41,5 @@ Initial release.
 - `--fuel` is a substring match, so `Gasolio` also matches variants such as
   `Gasolio Alpino`.
 
+[0.1.0]: https://github.com/galjos/pitstop/releases/tag/v0.1.0
 [0.0.1]: https://github.com/galjos/pitstop/releases/tag/v0.0.1

README.md

@@ -40,8 +40,8 @@ PYTHONPATH=src python3 -m pitstop --help
 ## Usage
 
 ```bash
-# Cheapest diesel in a municipality
-pitstop stations --comune ROMA --fuel Gasolio --cheapest --limit 5
+# Cheapest diesel in a municipality (skip placeholder prices with --min-price)
+pitstop stations --comune ROMA --fuel Gasolio --cheapest --min-price 1.2 --limit 5
 
 # Self-service petrol within 5 km of a coordinate, as JSON
 pitstop stations --near 46.498,11.354 --radius 5 --fuel Benzina --self --json
@@ -50,7 +50,29 @@ pitstop stations --near 46.498,11.354 --radius 5 --fuel Benzina --self --json
 pitstop fuels
 ```
 
-`stations` flags: `--comune`, `--provincia`, `--brand`, `--near "lat,lon"`, `--radius`, `--fuel` (substring, case-insensitive), `--self`, `--served`, `--cheapest` (needs `--fuel`), `--limit`, `--json`. Loading flags (`--refresh`, `--max-age`, `--timeout`) apply to any data command.
+`stations` flags: `--comune`, `--provincia`, `--brand`, `--near "lat,lon"`, `--radius`, `--fuel` (substring, case-insensitive), `--self`, `--served`, `--cheapest` (needs `--fuel`), `--min-price` (drop values below a floor; e.g. `1.2` to skip placeholders), `--limit`, `--json`. Loading flags (`--refresh`, `--max-age`, `--timeout`) apply to any data command.
+
+## MCP server
+
+For agents that speak MCP, the same data is exposed as tools (`list_fuels`, `find_stations`, `find_cheapest`) over the shared core:
+
+```bash
+pip install "pitstop[mcp]"   # or: uv tool install "pitstop[mcp]"
+pitstop-mcp                  # stdio MCP server
+```
+
+Example client config entry:
+
+```json
+{ "mcpServers": { "pitstop": { "command": "pitstop-mcp" } } }
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
 
 ## Automation contract
 
@@ -62,12 +84,9 @@ pitstop fuels
 
 ## Status & roadmap
 
-v0.0.1 — working fuel-price core (registry+price join, filters, proximity, cheapest, JSON).
+v0.1.0 — fuel-price core (registry+price join, filters, proximity, cheapest, `--min-price` floor, JSON), an MCP server, a Claude skill, tests, and CI.
 
 Planned, roughly in order:
-- price sanity-floor to suppress placeholder values;
-- an **MCP server** exposing the same core as agent tools;
-- a Claude **skill** that drives the CLI;
 - **EV charging** (locations via Open Charge Map; prices via the AFIR National Access Point / DATEX II as that data matures);
 - additional countries behind a per-country source adapter (e.g. Germany Tankerkönig, France/Spain official feeds).
 

pyproject.toml

@@ -4,16 +4,25 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pitstop"
-version = "0.0.1"
+version = "0.1.0"
 description = "Unofficial JSON-first CLI for Italian fuel-station prices (MIMIT Osservaprezzi Carburanti open data)."
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = []
 authors = [{ name = "Josef M. Gallmetzer" }]
 keywords = ["fuel", "prices", "italy", "mimit", "carburanti", "cli", "agent"]
 
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+dev = ["pytest>=7"]
+
 [project.scripts]
 pitstop = "pitstop.cli:main"
+pitstop-mcp = "pitstop.mcp_server:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/pitstop"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

skills/pitstop/SKILL.md

@@ -21,7 +21,8 @@ Always pass `--json` when consuming the output programmatically.
 
 ```bash
 # Cheapest of a fuel in a municipality (--cheapest requires --fuel)
-pitstop stations --comune ROMA --fuel Gasolio --cheapest --limit 5 --json
+# Add --min-price 1.2 to skip placeholder values when ranking by price.
+pitstop stations --comune ROMA --fuel Gasolio --cheapest --min-price 1.2 --limit 5 --json
 
 # Nearest stations to a coordinate, self-service petrol within 5 km
 pitstop stations --near 46.498,11.354 --radius 5 --fuel Benzina --self --json
@@ -30,7 +31,9 @@ pitstop stations --near 46.498,11.354 --radius 5 --fuel Benzina --self --json
 pitstop fuels --json
 ```
 
-Key flags: `--comune`, `--provincia` (2-letter, e.g. `BZ`), `--brand`, `--near "lat,lon"` + `--radius` (km), `--fuel` (substring, case-insensitive), `--self` / `--served`, `--cheapest`, `--limit`, `--json`.
+Key flags: `--comune`, `--provincia` (2-letter, e.g. `BZ`), `--brand`, `--near "lat,lon"` + `--radius` (km), `--fuel` (substring, case-insensitive), `--self` / `--served`, `--cheapest`, `--min-price` (price floor), `--limit`, `--json`.
+
+If your client speaks MCP instead of shelling out, the same capabilities are available as MCP tools (`list_fuels`, `find_stations`, `find_cheapest`) via `pitstop-mcp` (install `pitstop[mcp]`).
 
 ## JSON contract
 
@@ -42,4 +45,4 @@ Exit codes: `0` ok, `1` runtime error (e.g. network), `2` usage error.
 
 - **Daily, not real-time** — prices are as of ~08:00 the day before `price_extraction_date`. State this when answering.
 - **`--fuel` is a substring match** — `Gasolio` also matches `Gasolio Premium`, `Gasolio Oro Diesel`, etc. Use `pitstop fuels` to pick exact names; inspect the `fuel` field in results.
-- **Placeholder prices** — some operators report junk values like `1.000`; with `--cheapest` these can rank first. Sanity-check the lowest results before reporting them as real.
+- **Placeholder prices** — some operators report junk values like `1.000`; with `--cheapest` these can rank first. Pass `--min-price 1.2` (petrol/diesel) to drop them; use a lower floor for cheaper fuels like GPL. Still sanity-check the lowest result.

src/pitstop/cli.py

@@ -59,6 +59,8 @@ def _build_parser() -> argparse.ArgumentParser:
     stations.add_argument("--self", dest="self_only", action="store_true", help="only self-service prices")
     stations.add_argument("--served", dest="served_only", action="store_true", help="only served prices")
     stations.add_argument("--cheapest", action="store_true", help="sort by ascending price (needs --fuel)")
+    stations.add_argument("--min-price", dest="min_price", type=float, default=0.0,
+                          help="drop prices below this floor (e.g. 1.2 to skip placeholder values); 0 = off")
     stations.add_argument("--limit", type=int, default=20, help="max stations; 0 = no limit")
     stations.set_defaults(func=_cmd_stations)
 
@@ -104,31 +106,20 @@ def _cmd_stations(args) -> int:
 
     ds = _load(args)
 
-    out: list[core.Station] = []
-    for st in ds.stations.values():
-        if args.comune and st.comune.casefold() != args.comune.strip().casefold():
-            continue
-        if args.provincia and st.provincia.casefold() != args.provincia.strip().casefold():
-            continue
-        if args.brand and args.brand.lower() not in st.brand.lower():
-            continue
-
-        prices = core.filter_prices(st.prices, args.fuel, args.self_only, args.served_only)
-        if (args.fuel or args.self_only or args.served_only) and not prices:
-            continue
-        st.prices = prices
-
-        if use_near:
-            d = core.haversine_km(near_lat, near_lon, st.lat, st.lon)
-            if d > args.radius:
-                continue
-            st.distance_km = round(d, 2)
-        out.append(st)
-
-    _sort_stations(out, cheapest=args.cheapest, use_near=use_near)
-
-    if args.limit > 0:
-        out = out[: args.limit]
+    out = core.query_stations(
+        ds,
+        comune=args.comune,
+        provincia=args.provincia,
+        brand=args.brand,
+        near=(near_lat, near_lon) if use_near else None,
+        radius_km=args.radius,
+        fuel=args.fuel,
+        self_only=args.self_only,
+        served_only=args.served_only,
+        cheapest=args.cheapest,
+        min_price=args.min_price,
+        limit=args.limit,
+    )
 
     query: dict = {}
     for key, val in (("comune", args.comune), ("provincia", args.provincia),
@@ -144,6 +135,8 @@ def _cmd_stations(args) -> int:
         query["served"] = True
     if args.cheapest:
         query["cheapest"] = True
+    if args.min_price > 0:
+        query["min_price"] = args.min_price
 
     if args.as_json:
         return _print_stations_json(ds, out, query)
@@ -174,28 +167,8 @@ def _cmd_fuels(args) -> int:
     return 0
 
 
-def _sort_stations(out: list[core.Station], *, cheapest: bool, use_near: bool) -> None:
-    if cheapest:
-        out.sort(key=lambda s: (core.min_price(s.prices) is None,
-                                core.min_price(s.prices) or 0.0))
-    elif use_near:
-        out.sort(key=lambda s: s.distance_km if s.distance_km is not None else float("inf"))
-    else:
-        out.sort(key=lambda s: (s.comune, s.name))
-
-
 def _print_stations_json(ds: core.Dataset, stations: list[core.Station], query: dict) -> int:
-    _dump({
-        "source": core.SOURCE_NAME,
-        "source_url": core.SOURCE_URL,
-        "registry_extraction_date": ds.registry_date,
-        "price_extraction_date": ds.price_date,
-        "generated_at": core.now_iso(),
-        "query": query,
-        "count": len(stations),
-        "stations": [s.to_dict() for s in stations],
-        "disclaimer": core.DISCLAIMER,
-    })
+    _dump(core.response_envelope(ds, stations, query))
     return 0
 
 

src/pitstop/core.py

@@ -204,7 +204,11 @@ def load(
 
 
 def filter_prices(
-    prices: list[Price], fuel: str = "", self_only: bool = False, served_only: bool = False
+    prices: list[Price],
+    fuel: str = "",
+    self_only: bool = False,
+    served_only: bool = False,
+    min_price: float = 0.0,
 ) -> list[Price]:
     fuel = fuel.strip().lower()
     out = []
@@ -215,14 +219,81 @@ def filter_prices(
             continue
         if served_only and p.self_service:
             continue
+        if min_price > 0 and p.price < min_price:
+            continue
         out.append(p)
     return out
 
 
-def min_price(prices: list[Price]) -> float | None:
+def min_price_of(prices: list[Price]) -> float | None:
     return min((p.price for p in prices), default=None)
 
 
+def query_stations(
+    ds: Dataset,
+    *,
+    comune: str = "",
+    provincia: str = "",
+    brand: str = "",
+    near: tuple[float, float] | None = None,
+    radius_km: float = 10.0,
+    fuel: str = "",
+    self_only: bool = False,
+    served_only: bool = False,
+    cheapest: bool = False,
+    min_price: float = 0.0,
+    limit: int = 20,
+) -> list[Station]:
+    """Filter, sort, and limit stations. Mutates the dataset's Station objects
+    (narrows prices, sets distance_km), so pass a freshly loaded Dataset."""
+    out: list[Station] = []
+    for st in ds.stations.values():
+        if comune and st.comune.casefold() != comune.strip().casefold():
+            continue
+        if provincia and st.provincia.casefold() != provincia.strip().casefold():
+            continue
+        if brand and brand.lower() not in st.brand.lower():
+            continue
+
+        prices = filter_prices(st.prices, fuel, self_only, served_only, min_price)
+        if (fuel or self_only or served_only or min_price > 0) and not prices:
+            continue
+        st.prices = prices
+
+        if near is not None:
+            d = haversine_km(near[0], near[1], st.lat, st.lon)
+            if d > radius_km:
+                continue
+            st.distance_km = round(d, 2)
+        out.append(st)
+
+    if cheapest:
+        out.sort(key=lambda s: (min_price_of(s.prices) is None, min_price_of(s.prices) or 0.0))
+    elif near is not None:
+        out.sort(key=lambda s: s.distance_km if s.distance_km is not None else float("inf"))
+    else:
+        out.sort(key=lambda s: (s.comune, s.name))
+
+    if limit > 0:
+        out = out[:limit]
+    return out
+
+
+def response_envelope(ds: Dataset, stations: list[Station], query: dict) -> dict:
+    """Build the stable JSON response object shared by the CLI and MCP server."""
+    return {
+        "source": SOURCE_NAME,
+        "source_url": SOURCE_URL,
+        "registry_extraction_date": ds.registry_date,
+        "price_extraction_date": ds.price_date,
+        "generated_at": now_iso(),
+        "query": query,
+        "count": len(stations),
+        "stations": [s.to_dict() for s in stations],
+        "disclaimer": DISCLAIMER,
+    }
+
+
 def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
     r = 6371.0
     d_lat = math.radians(lat2 - lat1)