carsearch — канадская платформа поиска, мониторинга и рыночного анализа подержанных автомобилей

carsearch превращает объявления канадских маркетплейсов в постоянную, доступную для поиска, историческую базу данных и открывает к ней доступ Claude Code (или любому агенту) через MCP, а также предоставляет полноценный CLI. Он собирает реальные объявления с AutoTrader.ca (можно подключать других провайдеров), сохраняет каждое изменение цены/статуса как историю, дедуплицирует физические автомобили по объявлениям, корректно геокодирует (реальные расстояния), извлекает индикаторы риска из описаний, вычисляет статистику сопоставимых цен, оценивает проектные автомобили по настраиваемым профилям, находит выгодные предложения, регулярно запускает сохранённые поиски и отправляет оповещения.

Задавайте Claude вопросы вроде:

• Найди все BMW E90 328i на механике до $8,000 в радиусе 800 км от Торонто, предпочти частных продавцов, отбрасывай ржавые корыта, ранжируй по ценности как проект-кар.

• Какие интересные проектные автомобили до $7k появились в Онтарио за последние 48 часов?

• Действительно ли этот Audi TT за $6,200 дёшев по сравнению с похожими объявлениями, которые мы наблюдали?

• Покажи все снижения цены > 10% за эту неделю. / Автомобили, висящие 30+ дней, где продавец уже дважды снижал цену.

Статус по фазам, протестированные команды и известные проблемы: PROJECT_STATUS.md.

Архитектура (кратко)

providers/ (autotrader ✓, cargurus/kijiji/facebook interface+probe)  →  VehicleListing (canonical)
   → collectors/ (checkpointed ProviderRun, ingest w/ snapshots+events, raw payloads)
   → dedupe/ (VIN → weighted soft signals → vehicles + candidates)  → geo/ (geocode, haversine)
   → SQLite/PostgreSQL (SQLAlchemy)  → search/  analysis/ (description, comps, deals, market)
   → scoring/ (profiles + model knowledge JSON)  → monitoring/ (saved searches, scheduler) → notifications/
   → cli/ (carsearch …)  and  mcp/ (23 tools)

Подробности: docs/architecture.md, docs/providers.md, docs/schema.md.

Установка

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"            # add ".[postgres]" for PostgreSQL
cp .env.example .env               # optional; SQLite in ./data works out of the box
carsearch db-init                  # creates/upgrades data/carsearch.db

Python ≥ 3.11 (разрабатывалось на 3.14). Для AutoTrader не нужны ни браузер, ни API-ключи.

Настройка базы данных

• По умолчанию: sqlite:///./data/carsearch.db (WAL). Ничего делать не нужно.

• PostgreSQL: CARSEARCH_DATABASE_URL=postgresql+psycopg://user:pass@host/carsearch в .env, pip install -e ".[postgres]", carsearch db-init. Схема/миграции находятся в src/carsearch/database/ (версионируются, записываются в schema_migrations).

Краулинг (сбор реальных данных)

# targeted, with detail pages for new listings (VIN, exact coordinates, drivetrain, created date)
carsearch crawl autotrader --make BMW --model "3 Series" --transmission manual --max-price 8000 --min-year 2006 --max-year 2013 --details new
# regional bulk (20 listings/page, ~1.5 s/page, no detail pages)
carsearch crawl autotrader --max-price 7000 --location Toronto --radius-km 500 --max-pages 200 --details none
# province scope (centroid + covering radius server-side, exact province locally)
carsearch crawl autotrader --province ON --transmission manual --max-price 6000 --seller-type private
# incremental refresh: stop after 3 consecutive pages with nothing new/changed
carsearch crawl autotrader --transmission manual --max-price 8000 --stop-when-seen 3
# resume an interrupted run
carsearch crawl autotrader --resume 12
# re-check listings not seen for 3 days (marks removed on 404); fetch missing detail pages; geocode backfill
carsearch refresh autotrader --older-than-days 3 --limit 200
carsearch details autotrader --limit 200
carsearch geocode --limit 60
scripts/bootstrap_crawl.sh   # example multi-band bootstrap used to seed the DB

AutoTrader ограничивает запрос 200 страницами (4000 объявлений) → разбивайте по ценовым диапазонам/регионам для полного покрытия (truncated=True в сводке запуска сообщит вам об этом).

Поиск

carsearch search --make BMW --model 328i --max-price 7000 --transmission manual --location Toronto --radius-km 800 --seller-type private
carsearch search --generation E90 --keywords '"one owner" -salvage' --province ON,QC --sort price_asc
carsearch new --since 48h --province ON --max-price 7000
carsearch price-drops --min 10 --since 7d
carsearch deals --province ON --max-price 7000 --profile project_car_enthusiast
carsearch deals --location Toronto --radius-km 500 --transmission manual --max-price 7000 --since 7d \
    --profile project_car_enthusiast --sort-by project --exclude-flags salvage_title,frame_rust,doesnt_run   # "best project cars" ranking
carsearch listing 42            # full record + price history + description flags
carsearch history 42            # snapshots + change events
carsearch comps 42              # comparable-price analysis with methodology
carsearch score 42 --profile project_car_enthusiast
carsearch analyze 42            # everything above + deal signals in one JSON
carsearch market --metric manual_premium --make Subaru --model WRX
carsearch market --metric price_by_mileage --generation E90 --province ON
carsearch market --metric cheapening --days 90
carsearch status [--check-providers]  ·  carsearch runs  ·  carsearch alerts

Каждая команда принимает --json для машиночитаемого вывода.

Мониторинг / сохранённые поиски / оповещения

carsearch saved seed                       # the four example searches from the brief
carsearch saved create "manual E90 328i under $8k" '{"make":"BMW","model":"3 Series","min_year":2006,"max_year":2011,"max_price":8000,"transmission":"manual"}' \
    --interval-minutes 240 --alert-rules '{"price_drop_pct":10,"target_price":6500,"min_deal_score":65}' --profile project_car_enthusiast
carsearch saved run "manual E90 328i under $8k"   # incremental crawl → new listings + alerts
carsearch schedule                          # long-running loop: runs due searches, maintenance
carsearch schedule --once                   # one pass (cron-friendly)

Оповещения отправляются в консоль, data/alerts.jsonl и опциональный вебхук (CARSEARCH_WEBHOOK_URL); новые приёмники — подклассы notifications.alerts.AlertSink. Каждое оповещение содержит reasons[] (и риски).

MCP-сервер

carsearch serve-mcp                # stdio (default)  |  --transport streamable-http --port 8765

Инструменты: search_cars, search_live_marketplace, get_listing, get_vehicle, get_new_listings, get_price_history, get_listing_changes, get_comparables, compare_cars, find_deals, find_price_drops, find_long_sitting_listings, analyze_listing, score_listing, analyze_market, list_saved_searches, create_saved_search, run_saved_search, delete_saved_search, get_alerts, get_status, get_generation_codes, analyze_listing_images. Все возвращают структурированный JSON с пагинацией (limit/offset/next_offset); тяжёлые поля (description, photos, raw) подключаются по желанию.

Подключение Claude Code

claude mcp add carsearch -- /ABSOLUTE/PATH/autotrader/.venv/bin/carsearch serve-mcp
# or in .mcp.json:
{ "mcpServers": { "carsearch": { "command": "/ABSOLUTE/PATH/autotrader/.venv/bin/carsearch", "args": ["serve-mcp"] } } }

Затем: “Найди лучшие проектные автомобили на механике до $7,000 CAD в радиусе 500 км от Торонто, которые появились за последнюю неделю. Сравни их с историческими ценами, отметь основные механические/коррозийные риски из объявлений и ранжируй топ-10.” — Claude обычно вызывает search_cars/get_new_listings (или search_live_marketplace для свежих данных), затем analyze_listing/compare_cars.

Как работают контрольные точки

Каждый обход — это строка provider_runs. После каждой страницы объявления фиксируются, а last_checkpoint.next_page продвигается; сбои по отдельным объявлениям логируются в errors и пропускаются. Обогащение деталей фиксируется по каждому объявлению (detail_fetched_at). Упавший запуск помечается как failed/interrupted, и carsearch crawl --resume <id> продолжает с next_page (уже полученные страницы берутся из локального http_cache). Состояние сохранённых поисков хранится в БД. См. docs/architecture.md.

Как добавить провайдера

Реализуйте BaseProvider в src/carsearch/providers/<name>/, сопоставьте его с VehicleListing в parser.py (сохраняйте raw), зарегистрируйте, добавьте фикстуры и тесты, опишите его в docs/providers.md. Больше ничего не меняется.

Тесты

pytest -q          # 42 tests: normalization, parser fixtures, ingest/price history, dedupe,
                   # geo/search, analysis (flags/comps/scoring/deals/market), crawler checkpoints, MCP tools

Ни один тест не обращается к сети (реальные фикстуры данных + фейковый провайдер).

Известные ограничения

• Провайдеры: собирает только AutoTrader.ca. CarGurus (DataDome), Kijiji (edge 403 / kijijiautos.ca больше нет) и Facebook (логин) — это интерфейсы с живыми проверками доступности; никаких попыток обхода антибот-защиты или логина не предпринимается (см. docs/providers.md).

• Запрашиваемые цены — не цены продажи. Исчезновение ≠ продажа; мы записываем not_observed/removed.

• Покрытие зависит от того, что вы обходите (лимит 200 страниц на запрос; разбивайте по диапазонам). «Появилось за последние N дней» использует дату создания на маркетплейсе, если она известна (страница объявления), иначе — наше первое наблюдение.

• Координаты: точные для объявлений со страницами деталей; в остальных случаях — на уровне города (стартовая таблица / выученные центроиды / резолвер маркетплейса). Фильтры по расстоянию пропускают объявления без координат.

• Скоринг, флаги и оценки выгодности — это эвристики с указанными обоснованиями и настраиваемыми правилами (src/carsearch/config/*.json); они являются входными данными для рассуждений, а не вердиктами. Regex-флаги могут ложно срабатывать на необычных формулировках (обоснование всегда возвращается).

• Сопоставимые объявления используют прогрессивное ослабление; небольшие выборки помечаются (warnings, confidence).

• Анализ изображений включает хеширование/кэширование и подключаемый хук машинного зрения (бэкенд Anthropic входит в комплект, по умолчанию выключен); без настройки модель зрения не запускается.

• SQLite отлично подходит для сотен тысяч объявлений; для одновременной записи переходите на PostgreSQL.