# gdebenz-mcp

MCP-сервер для поиска бензина и дизеля на АЗС России. Объединяет **два независимых источника** — [gdebenz.ru](https://gdebenz.ru) и [gdebenzi.ru](https://gdebenzi.ru) — народные карты наличия топлива с отметками водителей в реальном времени.

Позволяет вашему ИИ-ассистенту (Claude, Cursor, OpenClaw и др.) отвечать на вопросы вроде:

> «Где рядом с Химками есть 95-й бензин?»
> «Какая ближайшая заправка Лукойл с дизелем, и есть ли там очередь?»

Работает через публичные API обоих сервисов. **Без API-ключей** — нужен только Python и два пакета.

### Два источника данных

| Источник | Что даёт |
|---|---|
| `gdebenz` | статус наличия, список топлива, подтверждения, свежесть (`last_at`), уверенность, цены |
| `gdebenzi` | статус, **текст очереди** («очередь 25–50 авто»), **лимиты** (л), подтверждённое топливо (`fuels_yes/no`), средние цены региона, отметки/отчёты |

У инструментов поиска есть параметр `source`: `"gdebenz"`, `"gdebenzi"` или `"both"` (по умолчанию `both` — максимум покрытия).

---

## Установка

### 1. Склонируй репозиторий

```bash
git clone https://github.com/ivanegorenkov/gdebenz-mcp.git
cd gdebenz-mcp
```

### 2. Установи зависимости

```bash
pip install -r requirements.txt
```

Нужен Python 3.10+.

### 3. Подключи сервер к своему ассистенту

**Claude Desktop** — открой/создай `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gdebenz": {
      "command": "python3",
      "args": ["/АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py"]
    }
  }
}
```

**Cursor** — в `.cursor/mcp.json` проекта (или глобальный `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "gdebenz": {
      "command": "python3",
      "args": ["/АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py"]
    }
  }
}
```

**OpenClaw**:

```bash
openclaw mcp add gdebenz --command python3 --arg /АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py
```

> ⚠️ Замените `/АБСОЛЮТНЫЙ/ПУТЬ/` на реальный путь, куда склонирован репозиторий (узнать можно командой `pwd` внутри папки).

---

## Инструкция для ИИ-агента

Если пользователь просит «поставь этот MCP-сервер» — сделай следующее:

1. `git clone https://github.com/ivanegorenkov/gdebenz-mcp.git`
2. `cd gdebenz-mcp && pip install -r requirements.txt`
3. Определи MCP-хост пользователя (Claude Desktop / Cursor / OpenClaw) и добавь запись `gdebenz` в его конфиг, как показано выше (с абсолютным путём к `server.py`).
4. Перезапусти хост/приложение.
5. Проверь, что сервер виден (в OpenClaw: `openclaw mcp probe gdebenz`).

Сервер stdio, внешних ключей не требует.

---

## Что умеет (9 инструментов)

| Инструмент | Что делает |
|---|---|
| `find_fuel` | **Главный.** Заправки с топливом рядом с местом (по названию или координатам). Фильтры: топливо, сеть, статус, радиус, `source`. Сортировка по расстоянию. |
| `nearby_stations` | Заправки вокруг точки (lat/lon + радиус + `source`). |
| `stations_with_prices` | Заправки в области + цены (bbox + `source`). |
| `search_stations` | Поиск заправки по названию/адресу. |
| `resolve_location` | Название места → координаты. |
| `get_geoip_location` | Моё местоположение по IP. |
| `get_city_by_coords` | Город по координатам. |
| `list_fuels` | Марки топлива: 92 / 95 / 98 / 100 / ДТ. |
| `list_brands` | Частые сети АЗС (фильтр принимает любую строку). |

**Пример запроса к ассистенту:** `find_fuel(location="Химки", fuel="95", brand="Лукойл", source="both")`.

### Семантика

- **Топливо**: `92, 95, 98, 100, ДТ`. У gdebenz — `fuels_now` (строка через запятую), у gdebenzi — `fuels_yes` / `fuels_no` / `fuels_maybe` (массивы с русскими названиями, напр. `["АИ-95", "ДТ"]`).
- **Статус**: `yes` — есть, `queue` — есть/очередь, `low` — мало, `no` — нет, `unknown` — неизвестно, `changing` — обновляется, `dtonly` — только дизель.
- **Актуальность**: у gdebenz — `last_at`, `confirmations`, `confidence` (0..1); у gdebenzi — `last_mark` (время отметки), `confidence_pct`, `marks`, `reports`. Оба источника отдают `age_minutes` и `freshness` («только что», «3 ч назад»).
- **Очередь/лимиты** (gdebenzi): `queue` («очередь 25–50 авто»), `limits` (лимит в литрах на марку).
- **Цены**: gdebenz — `prices_now[fuel].t` (время отчёта о цене); gdebenzi — `prices` (ключи `ai92/ai95/ai98/ai100/dt/gas`) и `regional_prices` (средние по региону).

## API (откуда данные)

**gdebenz.ru**

| Endpoint | Назначение |
|---|---|
| `GET /api/nearby?lat=&lon=&radius_km=` | станции вокруг точки |
| `GET /api/stations?lat1=&lon1=&lat2=&lon2=` | станции в bbox + цены |
| `GET /api/search?q=` | текстовый поиск |
| `GET /api/cities?q=` | геокодинг |
| `GET /api/geoip` | местоположение по IP |
| `GET /api/reverse-city?lat=&lon=` | город по координатам |

**gdebenzi.ru**

| Endpoint | Назначение |
|---|---|
| `GET /api/stations.php?bbox=lon1,lat1,lon2,lat2` | станции в bbox (статус, очередь, лимиты, цены, отметки) |

## Лицензия

MIT