# v-radion MCP search server

Удобный поисковик по каталогу магазина радиоэлектроники
[https://v-radion.ru](https://v-radion.ru) в виде **HTTP MCP-сервера** (Model
Context Protocol). Сайт сам по себе неудобный — статика, кривая кодировка, цены
«не определена», нет нормального поиска. Сервер делает его пригодным для
использования из MCP-клиента (opencode, Claude Desktop и др.): поиск по всему
сайту, просмотр категорий с фильтрами и карточки товаров.

## Возможности

- **Поиск и осмотр за один вызов** — `find_product` ищет и сканирует до `limit`
  карточек, нормализует запросы (`1k`→`1 кОм`), переводит EN→RU (`LED`→`светодиод`),
  автоматически расширяет до тип+корпус.
- **Весь BOM за один вызов** — `find_bom` принимает список позиций или таблицу
  KiCad целиком.
- **Просмотр категорий с фильтрами** — `browse_category` отдаёт товары и, не
  делая лишних запросов, фильтрует/сортирует их по атрибутам, извлечённым из
  названия. Фильтр — **абстрактный** `filter: dict` (напр. `{"package":"0805"}`,
  `{"chemistry":"NiCd","voltage":"1.2В"}`, `{"form_factor":"AA","with_leads":True}`)
  плюс `query` и `sort` (`name`/`voltage`).
- **Структурированные атрибуты** — каждый товар в категории несёт распарсенные
  `chemistry`, `voltage`, `form_factor`, `package`, `capacity`, `with_leads`.
- **Бережём сайт** — каждый вызов делает не более одного HTTP-запроса, повторы
  кэшируются в памяти на 5 минут (`scraper._CACHE_TTL`). Сайт не краулится.

## Требования

- Python 3.11+
- Доступ к сайту v-radion.ru (самоподписанный/просроченный TLS — проверка
  отключена намеренно)

## Установка и запуск

Через виртуальное окружение (прямой вызов интерпретатора, без активации):

```bat
python -m venv venv
.\venv\Scripts\python.exe -m pip install -r requirements.txt
.\venv\Scripts\python.exe server.py
```

Сервер поднимается на `http://127.0.0.1:8000/mcp` (transport: `streamable-http`).
Поменять адрес можно переменными окружения `HOST` и `PORT`.

Или просто двойным кликом по `start_mcp.bat` (он держит окно открытым).

## Подключение MCP-клиента

Сервер работает по протоколу `streamable-http` на
`http://127.0.0.1:8000/mcp`. Ниже — примеры добавления в популярные клиенты.
Во всех случаях сначала запустите сервер (см. «Установка и запуск»), затем
перезапустите клиент. Сервер не стартует сам — его держит `.bat`.

**opencode** — добавьте в `opencode.json` (пример уже лежит в корне проекта):

```json
{
  "mcpServers": {
    "v-radion": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

Проверить подключение:

```bat
opencode mcp list
```

**Claude Desktop** — вставьте в `mcpServers` файла
`%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "v-radion": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

**Другой MCP-клиент** — добавьте сервер типа `streamable-http` (или `http` /
`remote`, в зависимости от клиента) с URL `http://127.0.0.1:8000/mcp`. Адрес
можно изменить переменными окружения `HOST` и `PORT` при запуске сервера.

После подключения агенту станут доступны инструменты `find_product`,
`find_bom`, `list_categories`, `browse_category`, `get_product`, `get_catalog`,
`site_info`.

## Инструменты

| Инструмент | Назначение |
|------------|------------|
| `find_product(query, limit=5)` | поиск + осмотр карточек за один вызов; авто-расширение до тип+корпус |
| `find_bom(items, limit_per=2)` | весь BOM за один вызов (список или таблица KiCad) |
| `list_categories()` | список категорий (id → название), читает `catalog.json` офлайн |
| `browse_category(identifier, page=0, limit=50, query="", sort="", filter=None)` | товары категории + **абстрактный** `filter: dict` и `sort` по атрибутам из названия |
| `get_catalog()` | всё дерево категорий из `catalog.json` (офлайн-ориентация, без запросов) |
| `get_product(url, query="")` | карточка товара; при `query` — только совпавшие строки `matches` |
| `site_info()` | контакты, часы, примечание про цены (без запросов) |

## Переменные окружения

| Переменная | По умолчанию | Назначение |
|------------|--------------|------------|
| `HOST` | `127.0.0.1` | адрес MCP-сервера |
| `PORT` | `8000` | порт MCP-сервера |
| `RUN_INTEGRATION` | (не задана) | если `=1` — запускаются интеграционные тесты |

## Файлы

- `server.py` — MCP-сервер (FastMCP, transport `streamable-http`).
- `scraper.py` — on-demand HTTP-клиент/парсер сайта (смешанная кодировка,
  отключённая TLS-проверка, кэш, извлечение атрибутов из названий).
- `test_client.py` — end-to-end тест через MCP-клиент.
- `Tests/` — автотесты (`test_units.py`, `test_integration.py`, `TEST_GUIDE.md`).

## Ссылки

- Каталог: https://v-radion.ru
- Спецификация MCP: https://modelcontextprotocol.io