Herramientas del MCP

El servidor MCP tiene 21 herramientas de solo lectura en cuatro grupos. Cada una llama al mismo servicio que su endpoint de la API REST y devuelve { data, meta } en structuredContent (con la fecha de los datos, la atribución y web_url). Los argumentos marcados con * son obligatorios; el resto, opcionales.

Argumentos que se repiten:

fuel: gasoline_95, gasoline_98, diesel, diesel_premium, lpg o cng (ver Conceptos básicos).
level + code: territorio. level es spain, community, province o municipality; code, el código INE de la comunidad o provincia (p. ej. 28 para la provincia de Madrid, 13 para la Comunidad de Madrid), el id de municipio o el slug. Usa search_places para obtenerlos.
limit: número de resultados, de 1 a 50 (por defecto 10).
lat, lng: coordenadas WGS84 dentro de España (se redondean a 3 decimales).

Precios y gasolineras

`search_places`

Busca municipios, códigos postales, provincias, comunidades o gasolineras por nombre y devuelve sus identificadores para el resto de herramientas. Equivale a GET /v1/search.

Argumentos: query* (2–100 caracteres: nombre, código postal o gasolinera), limit (1–20).
Ejemplo: «¿Qué es 28100? ¿Dónde está la Repsol de la A-6?»

`find_cheapest_fuel`

Las gasolineras más baratas de un carburante en España, en un territorio (level + code) o alrededor de un punto (lat + lng + radius_km). En el ranking de toda España, Canarias, Ceuta y Melilla van aparte salvo include_low_tax: true. Equivale a GET /v1/stations/cheapest.

Argumentos: fuel (por defecto gasoline_95), level, code, lat, lng, radius_km (hasta 50), limit, open_24h, brand (slug: repsol, cepsa, bp, ballenoil…), include_low_tax.
Ejemplo: «Diésel más barato en Sevilla, a 10 km de mí o abierto 24 horas»

`find_fuel_near`

Gasolineras con el carburante a menos de radius_km de un punto, por precio o por distancia. Equivale a GET /v1/stations/nearby.

Argumentos: lat*, lng*, radius_km (hasta 50), fuel, sort (price o distance), limit, open_24h.
Ejemplo: «Gasolineras cerca de la estación de Atocha»

`get_station`

Dirección, horario, coordenadas y precios de hoy de todos los carburantes y productos (AdBlue, HVO, E10…) de una gasolinera. Equivale a GET /v1/stations/{id}.

Argumentos: id* (id del Ministerio, p. ej. 14402, o slug de su ficha).
Ejemplo: «Horario y precios de esta gasolinera»

`get_fuel_prices`

Media, mediana, mínimo y máximo de hoy de cada carburante en España o en un territorio, con el número de gasolineras, la variación frente al día anterior y la comparación con la media de España. Equivale a GET /v1/prices.

Argumentos: level, code, fuel.
Ejemplo: «Precio medio de la gasolina en Valencia hoy frente a España»

`get_price_history`

Histórico diario (hasta 90 días) de un territorio o de una gasolinera, con la variación del periodo; con monthly: true, medias mensuales de España desde 2005 (Boletín Petrolero de la UE, solo gasoline_95 y diesel). Equivale a GET /v1/history, GET /v1/stations/{id}/history y GET /v1/history/monthly.

Argumentos: fuel (por defecto gasoline_95), level, code, station_id, days (1–90), monthly, from (AAAA-MM, solo con monthly).
Ejemplo: «¿Cuánto ha subido el diésel este mes?»

`compare_regions`

Provincias o comunidades ordenadas por el precio medio de hoy de un carburante (la más barata primero), con la diferencia frente a España. Equivale a GET /v1/rankings/regions.

Argumentos: level (province por defecto, o community), fuel (por defecto diesel), include_low_tax.
Ejemplo: «¿Qué provincia tiene el diésel más barato?»

`compare_brands`

Precio medio y tamaño de la red de las marcas en España o en una provincia. Con brands, solo esas marcas y sus datos verificados (historia, propietario, carburantes premium) con fuentes. Equivale a GET /v1/brands y GET /v1/brands/{slug}.

Argumentos: fuel, province (código INE o slug; por provincia solo hay medias de gasoline_95 y diesel), brands (hasta 6 slugs).
Ejemplo: «Repsol, Cepsa y BP en Madrid»

`get_product_prices`

Precio medio y mediana de hoy de un producto y las gasolineras más baratas que lo comunican al Ministerio. Equivale a GET /v1/products/{id}.

Argumentos: product* (adblue, diesel_b, hvo, lng, gasoline_95_e10 o gasoline_98_e10), community, limit.
Ejemplo: «¿Dónde hay AdBlue o HVO y a cuánto?»

Carreteras y rutas

`find_routes`

Busca en el catálogo de rutas en coche y en moto de preciosgasolina.es. Equivale a GET /v1/routes.

Argumentos: query, type (moto, rurales, costa, montana o clasicas), region, limit.
Ejemplo: «Rutas en moto por la costa de Andalucía»

`get_route`

Una ruta del catálogo: recorrido, mejor temporada, puntos destacados, fotos con su autor, coste estimado del viaje y las gasolineras más baratas a 3 km o menos del trazado. Equivale a GET /v1/routes/{slug}.

Argumentos: slug* (de find_routes), fuel, consumption (L/100 km), limit.
Ejemplo: «Ruta de los pueblos blancos: recorrido y dónde repostar»

`find_fuel_on_road`

Gasolineras de una carretera (A-6, AP-7, N-340…) con su punto kilométrico y sentido cuando se conocen, por precio o por posición. Equivale a GET /v1/roads/{slug}/stations.

Argumentos: road* (código o slug: A-3, ap-7), fuel (por defecto gasoline_95), sort (price o position), limit.
Ejemplo: «Gasolineras más baratas en la AP-7»

`find_fuel_along_route`

Las gasolineras más baratas a lo largo de la ruta del usuario, con su posición en el recorrido y el coste estimado del viaje. La ruta se envía como puntos [lat, lng] en orden (origen, localidades intermedias, destino): cuantos más puntos, más precisa. Equivale a POST /v1/route/fuel.

Argumentos: points* (2–200 pares [lat, lng]), fuel (por defecto gasoline_95), corridor_km (hasta 10; por defecto 3), consumption (L/100 km), open_24h, limit.
Ejemplo: «Voy de Madrid a Valencia por la A-3, ¿dónde reposto?»

Contenido

`search_content`

Busca en las guías, el blog y las rutas de preciosgasolina.es (tipos de carburante, E10, AdBlue, impuestos, consejos para ahorrar…) y devuelve la respuesta directa de cada pieza y su enlace. Equivale a GET /v1/content.

Argumentos: query* (2–100 caracteres), type (guide, post o route), limit.
Ejemplo: «¿Qué es la gasolina E10?»

`get_article`

Devuelve una guía o un artículo completo, con preguntas frecuentes y fuentes (texto en Markdown). Equivale a GET /v1/content/{type}/{slug}.

Argumentos: type* (guide, post o route), slug*.

`get_monthly_report`

Informe de un mes cerrado: medias de España frente al mes anterior, días más baratos y más caros y provincias por precio. Sin month, lista los meses disponibles. Equivale a GET /v1/reports y GET /v1/reports/{month}.

Argumentos: month (AAAA-MM).
Ejemplo: «¿Cómo fueron los precios en septiembre?»

Calculadoras

`calculate_trip_cost`

Coste en combustible de un viaje: kilómetros de ida (o coordenadas de origen y destino: línea recta × 1,25), consumo y precio de hoy (media de España o de una provincia, o el que indiques). Con tank_capacity, también el coste de llenar el depósito. Equivale a GET /v1/calc/trip-cost y GET /v1/calc/tank-cost.

Argumentos: fuel, km, from_lat, from_lng, to_lat, to_lng, round_trip, consumption (L/100 km; kg con GNC), price, province, people (1–9), tank_capacity.
Ejemplo: «¿Cuánto me cuesta ir de Madrid a Valencia con 6,5 L/100 km?»

`calculate_savings`

Ahorro por repostaje, al mes y al año al repostar en una gasolinera más barata, y si compensa el desvío. Equivale a GET /v1/calc/savings.

Argumentos: usual_price*, cheap_price*, fuel, quantity_per_refuel, refuels_per_month, detour_km (ida y vuelta), consumption.
Ejemplo: «¿Compensa desviarme 5 km para ahorrar 8 céntimos?»

`compare_vehicle_costs`

Coste por 100 km y al año, amortización y kilómetros a partir de los que compensa un diésel frente a un gasolina (compare: "petrol_vs_diesel") o un eléctrico frente a uno de combustión (compare: "ev_vs_fuel"), con los precios de hoy. Equivale a GET /v1/calc/vehicle-costs.

Argumentos: compare*, km_per_year*, petrol_consumption, diesel_consumption, diesel_extra_price, diesel_extra_yearly_cost, ev_consumption (kWh/100 km), electricity_price (€/kWh), ev_extra_price.
Ejemplo: «¿Me compensa un diésel o un eléctrico con 20.000 km al año?»

`calculate_adblue`

Litros y euros de AdBlue al mes y al año de un diésel, con el precio medio de hoy en surtidor (o el que indiques). Equivale a GET /v1/calc/adblue.

Argumentos: km_per_year*, litres_per_1000km, price, tank_litres.
Ejemplo: «¿Cuánto AdBlue gasto al mes?»

`explain_fuel_price`

Cuánto de un litro es IVA, Impuesto sobre Hidrocarburos (con la rebaja vigente) y producto, logística y margen; régimen de Canarias, Ceuta y Melilla. Sin precio, usa la media de hoy. Incluye los tramos de la rebaja y las fuentes. Equivale a GET /v1/calc/price-breakdown + GET /v1/taxes.

Argumentos: fuel (gasoline_95, gasoline_98, diesel o diesel_premium), price, province, tank_litres.
Ejemplo: «¿Cuánto de un litro son impuestos con la rebaja?»

Errores de las herramientas

Si una herramienta no puede responder, el resultado lleva isError: true y un texto con el código y el motivo, por ejemplo PROVINCE_NOT_FOUND: No existe la provincia 99. o INVALID_PARAMETER: …. Los códigos son los mismos que los de la API REST: ver Errores. Un argumento que no cumple el esquema de entrada (tipo o rango) se rechaza antes de ejecutar la herramienta.

Fuente de los datos: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras). Datos de la API y del servidor MCP con licencia CC BY 4.0: cita Gasolina hoy y la fuente.