Polovnjak MCP

Мультипровайдерный MCP сервер для маркетплейсов подержанных автомобилей. Агенты получают единый набор инструментов — поиск, детали объявлений, статистику цен, историю цен и персональные отслеживания сохранённых поисков — на основе подключаемых адаптеров маркетплейсов. Включённые адаптеры: polovniautomobili.com (идентификатор источника pa) и mojauto.rs (идентификатор источника ma), оба — Сербия.

Пользователи входят через Google с помощью стандартного потока MCP OAuth 2.1; отслеживания приватны для каждого пользователя. Каждое объявление, которое хаб наблюдает (из поисков любого пользователя, выборки статистики или проверок отслеживаний), записывается в общую Postgres «рыночную память», которая обеспечивает запросы истории цен и трендов, недоступные ни на одном отдельном маркетплейсе.

Архитектура

• Адаптеры (src/adapters/) реализуют общий интерфейс SourceAdapter: search, getListing, getMakesModels, а также флаги возможностей. Каждый адаптер переводит канонические фильтры в запрос своего провайдера и отображает результаты обратно в каноническую модель объявления. Объявления имеют составные идентификаторы вида pa:12345678 или ma:3554254. Названия марок разрешаются по псевдонимам для каждого источника («VW» и «Volkswagen» работают везде); фильтры, которые источник не может выразить, сообщаются как warnings для конкретного источника в результатах.

• Инструменты (src/tools/) распределяют запросы по адаптерам и объединяют результаты, помечая всё источником. Категории охватывают автомобили, мотоциклы, фургоны, лёгкие/тяжёлые грузовики, автобусы, прицепы, кемперы, спецтехнику, тракторы, лодки и велосипеды.

• Рекордер (src/recorder.ts) выполняет upsert каждого наблюдаемого объявления в таблицу listings и добавляет строку price_observations при первом обнаружении или изменении цены.

• Аутентификация (src/auth/) — это самостоятельно размещённый сервер авторизации OAuth 2.1 (динамическая регистрация клиентов, PKCE, refresh-токены) с Google OIDC в качестве слоя идентификации. Токены хранятся в Postgres в хешированном виде.

• Хранилище — Postgres через Drizzle ORM; миграции выполняются автоматически при запуске.

Related MCP server: Vehicle Database MCP Server

Быстрый старт (Docker Compose)

1. Создайте Google OAuth-клиент в Google Cloud Console (тип «Веб-приложение») с авторизованным redirect URI <PUBLIC_URL>/auth/google/callback (например, http://localhost:8321/auth/google/callback для локального использования).

2. Настройте окружение:

cp .env.example .env
# set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (and PUBLIC_URL for non-local deployments)

3. Запустите всё (MCP-сервер + Postgres + FlareSolverr):

docker compose up -d --build

4. Укажите вашему MCP-клиенту адрес http://localhost:8321/mcp. Клиент обнаружит метаданные OAuth, зарегистрируется сам и откроет окно браузера для входа через Google. Всё после этого — для каждого пользователя.

Для быстрого локального теста без учётных данных Google установите AUTH_MODE=none — сервер тогда пропустит аутентификацию и будет использовать одного локального dev-пользователя.

Инструменты

Навык агента

В репозитории поставляется навык агента в .cursor/skills/car-market-hub/SKILL.md, который обучает LLM-агентов эффективно использовать этот сервер (рабочие процессы инструментов, подводные камни), с руководствами по подключению для OpenAI, Claude, LibreChat и Cursor в clients.md. Cursor подхватывает его автоматически; для других платформ скопируйте каталог навыка в соответствующее место для навыков этой платформы (например, .claude/skills/) или вставьте его содержимое в инструкции агента.

Рабочий процесс отслеживания

1. create_watch с именем и фильтрами (опционально ограниченными конкретными sources) — текущие совпадения становятся базовой линией.

2. Позже (например, запланированный запрос: «проверь мои отслеживания автомобилей») check_watches возвращает только объявления, появившиеся с тех пор, по каждому отслеживанию и источнику.

Добавление нового адаптера маркетплейса

1. Создайте src/adapters/<name>/ и реализуйте интерфейс SourceAdapter из src/adapters/types.ts: выберите короткий стабильный id (используется в составных идентификаторах объявлений), переведите канонические фильтры SearchQuery в запрос вашего провайдера и отобразите необработанные результаты в канонические формы ListingSummary / ListingDetail из src/domain/listing.ts.

2. Зарегистрируйте его в src/server.ts с помощью registerAdapter(...).

Распределение поиска, отслеживания, запись и история цен автоматически подхватывают новый источник.

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

Локальная разработка

npm install
docker compose up -d postgres        # or point DATABASE_URL at your own Postgres
AUTH_MODE=none npm run dev           # server on http://localhost:8080/mcp

Изменения схемы: отредактируйте src/db/schema.ts, затем выполните npm run db:generate, чтобы создать новую миграцию в drizzle/ (применяется автоматически при запуске).

Примечания и ограничения

• polovniautomobili.com не имеет публичного API; адаптер читает данные Next.js-эндпоинтов сайта, используя имитацию TLS Chrome (impit), с FlareSolverr как запасным решением для Cloudflare-вызовов. Используйте ответственно и соблюдайте условия обслуживания сайта.

• Цены ниже 100 EUR считаются «ценой по запросу» и исключаются из статистики и наблюдений.

• Проверки отслеживаний сканируют первые две страницы результатов (~50 самых новых объявлений) по каждому источнику.

• get_price_history отражает только объявления, наблюдаемые через этот хаб — это растущая выборка, а не полный рынок.

• Предыдущая реализация с одним провайдером сохранена для справки в old/ (не входит в сборку).