carsearch — Plataforma canadiense de búsqueda, seguimiento y análisis de mercado de coches de segunda mano

carsearch convierte los anuncios del marketplace canadiense en una base de datos persistente, consultable e histórica y la expone a Claude Code (o a cualquier agente) a través de MCP, además de una CLI completa. Recopila anuncios reales de AutoTrader.ca (con más proveedores conectables), guarda cada cambio de precio/estado como historial, deduplica vehículos físicos entre anuncios, geocodifica correctamente (distancias reales), extrae señales de riesgo de las descripciones, calcula estadísticas de precios comparables, puntúa coches proyecto según perfiles configurables, detecta ofertas, vuelve a ejecutar búsquedas guardadas según una programación y genera alertas.

Pregunta a Claude cosas como:

• Encuentra todos los BMW E90 328i manuales por menos de $8,000 en un radio de 800 km de Toronto, prefiere vendedores particulares, rechaza los cacharros oxidados y clasifícalos por valor de coche proyecto.

• ¿Qué coches proyecto interesantes de menos de $7k han aparecido en Ontario en las últimas 48 horas?

• ¿Es este Audi TT de $6,200 realmente barato en comparación con anuncios similares que hemos observado?

• Muéstrame todas las bajadas de precio superiores al 10 % esta semana. / Coches que llevan más de 30 días a la venta y donde el vendedor ya ha rebajado el precio dos veces.

Estado por fase, comandos probados y problemas conocidos: PROJECT_STATUS.md.

Arquitectura (breve)

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)

Detalles: docs/architecture.md, docs/providers.md, docs/schema.md.

Instalación

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 (desarrollado en 3.14). No se requiere navegador ni claves de API para AutoTrader.

Configuración de la base de datos

• Predeterminado: sqlite:///./data/carsearch.db (WAL). No hay que hacer nada.

• PostgreSQL: CARSEARCH_DATABASE_URL=postgresql+psycopg://user:pass@host/carsearch en .env, pip install -e ".[postgres]", carsearch db-init. El esquema y las migraciones están en src/carsearch/database/ (versionado, registrado en schema_migrations).

Rastreo (recopilación de datos reales)

# 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 limita una consulta a 200 páginas (4000 anuncios) → divide por franja de precio/región para una cobertura completa (truncated=True en el resumen de la ejecución te indica cuándo).

Búsqueda

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

Todos los comandos aceptan --json para una salida legible por máquina.

Monitorización / búsquedas guardadas / alertas

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)

Las alertas van a la consola, a data/alerts.jsonl y a un webhook opcional (CARSEARCH_WEBHOOK_URL); los nuevos destinos son subclases de notifications.alerts.AlertSink. Cada alerta incluye reasons[] (y riesgos).

Servidor MCP

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

Herramientas: 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. Todas devuelven JSON estructurado con paginación (limit/offset/next_offset); los campos pesados (description, photos, raw) son opcionales.

Conectar 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"] } } }

Luego: "Encuentra los mejores coches proyecto manuales por menos de $7,000 CAD en un radio de 500 km de Toronto que hayan aparecido la semana pasada. Compáralos con los precios históricos, señala los principales riesgos mecánicos/de óxido de los anuncios y clasifica los 10 mejores." — Claude normalmente llamará a search_cars/get_new_listings (o search_live_marketplace para datos recientes) y luego a analyze_listing/compare_cars.

Cómo funcionan los puntos de control

Cada rastreo es una fila de provider_runs. Después de cada página, los anuncios se confirman y last_checkpoint.next_page avanza; los fallos por anuncio se registran en errors y se omiten. El enriquecimiento de detalles se confirma por anuncio (detail_fetched_at). Una ejecución que muere se marca como failed/interrupted y carsearch crawl --resume <id> continúa desde next_page (las páginas ya obtenidas provienen de la caché local http_cache). El estado de las búsquedas guardadas vive en la base de datos. Ver docs/architecture.md.

Cómo añadir un proveedor

Implementa BaseProvider en src/carsearch/providers/<name>/, asigna a VehicleListing en un parser.py (mantén raw), regístralo, añade fixtures y pruebas, documéntalo en docs/providers.md. Nada más cambia.

Pruebas

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

Ninguna prueba toca la red (fixtures de payload reales + un proveedor falso).

Limitaciones conocidas

• Proveedores: solo AutoTrader.ca recopila. CarGurus (DataDome), Kijiji (edge 403 / kijijiautos.ca desaparecido) y Facebook (login) son interfaces con sondas de salud en vivo; no se intenta eludir el anti-bot ni el inicio de sesión (ver docs/providers.md).

• Precios pedidos, no precios de venta. La desaparición ≠ vendido; registramos not_observed/removed.

• Cobertura: depende de lo que rastrees (límite de 200 páginas por consulta; divide por franjas). "Apareció en los últimos N días" utiliza la fecha de creación en el marketplace cuando se conoce (página de detalle); si no, nuestra primera observación.

• Coordenadas: exactas para los anuncios con página de detalle; en caso contrario, a nivel de ciudad (tabla semilla / centroides aprendidos / resolvedor del marketplace). Los filtros de distancia omiten los anuncios sin coordenadas.

• La puntuación, los indicadores y las puntuaciones de ofertas son heurísticas con evidencia declarada y reglas configurables (src/carsearch/config/*.json); son entradas para el razonamiento, no veredictos. Los indicadores regex pueden fallar ante frases inusuales (la evidencia siempre se devuelve).

• Los comparables usan relajación progresiva; las muestras pequeñas se señalan (warnings, confidence).

• El análisis de imágenes incluye hash/caché y un hook de visión conectable (backend de Anthropic incluido, desactivado por defecto); ningún modelo de visión se ejecuta salvo que esté configurado.

• SQLite es suficiente para cientos de miles de anuncios; cambia a PostgreSQL para escritores concurrentes.