CarDeals-MCP

Car Deals Search MCP

Busca anuncios de autos usados en Cars.com, Autotrader y KBB con asistentes de IA

Un servidor MCP (Model Context Protocol) que agrega y busca anuncios de autos de múltiples fuentes. Extrae anuncios en paralelo, obtiene precio, kilometraje, información del concesionario y aplica filtros opcionales estilo CARFAX (1 dueño, sin accidentes, uso personal).

---

🚀 Inicio Rápido

Requisitos previos

• Node.js (v16 o superior)
• Navegador Chrome/Chromium instalado (requerido por Puppeteer)
  • Si Chrome no está en la ubicación predeterminada, establece la variable de entorno PUPPETEER_EXECUTABLE_PATH para que apunte a tu binario de Chrome/Chromium

Instalación

# Clone the repository
git clone https://github.com/SiddarthaKoppaka/car_deals_search_mcp.git
cd car_deals_search_mcp

# Install dependencies (includes Puppeteer)
npm install

Uso con clientes MCP

Configura tu cliente MCP (Claude Desktop, VS Code, GitHub Copilot, etc.) para usar este servidor:

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "car-deals": {
      "command": "node",
      "args": ["/absolute/path/to/car_deals_search_mcp/src/server.js"]
    }
  }
}

Para otros clientes MCP, consulta su documentación y usa:

• Comando: node
• Argumentos: ["<absolute-path-to-repo>/src/server.js"]

Pruebas independientes

# Run the test command
npm test

# Or test manually with a specific search
node -e "
const { scrapeCarscom } = require('./src/scraper.js');
scrapeCarscom({
  make: 'Toyota',
  model: 'Camry',
  oneOwner: true,
  noAccidents: true,
  personalUse: true
}, 5).then(listings => listings.forEach(l => console.log(l.format())));
"

---

✨ Características

• Agregación multi-fuente: Busca en Cars.com, Autotrader y KBB simultáneamente
• Filtrado inteligente: Filtros estilo CARFAX (1 Dueño, Sin Accidentes, Uso Personal)
• Calificación de ofertas: Evaluación heurística de la calidad de la oferta
• Extracción en paralelo: Consultas concurrentes rápidas entre fuentes
• Modo sigiloso: Puppeteer con técnicas anti-detección de bots

---

📊 Fuentes compatibles

Fuente	Precio	Kilometraje	Calificación de oferta	Info del concesionario	Filtros CARFAX
Cars.com	✅	✅	✅	✅	✅
Autotrader	✅	✅	⚠️ Limitado	✅	⚠️ Limitado
KBB	✅	✅	✅	⚠️ Limitado	⚠️ Limitado

---

🔧 Herramienta MCP: search_car_deals

Parámetros

Parámetro	Tipo	Requerido	Descripción
make	string	✅	Fabricante del auto (p. ej., "Toyota", "Honda")
model	string	✅	Modelo del auto (p. ej., "Camry", "Accord")
zip	string	❌	Código postal para búsqueda local (predeterminado: "90210")
yearMin	integer	❌	Año mínimo del modelo
yearMax	integer	❌	Año máximo del modelo
priceMax	integer	❌	Precio máximo en USD
mileageMax	integer	❌	Kilometraje máximo
maxResults	integer	❌	Máximo de resultados por fuente (predeterminado: 10)
sources	array	❌	Fuentes a consultar: ["cars.com","autotrader","kbb"] (predeterminado: todas)
oneOwner	boolean	❌	Filtrar solo vehículos con 1 dueño según CARFAX
noAccidents	boolean	❌	Filtrar sin accidentes reportados
personalUse	boolean	❌	Filtrar solo uso personal (no alquiler/flota)

Ejemplo de respuesta

🚗 2021 Toyota Camry XSE
   💰 Price: $23,491
   📏 Mileage: 52,649 mi
   ⭐ Deal Rating: Good Deal
   🏆 CARFAX: 1-Owner | No Accidents | Personal Use
   🏪 Dealer: Valencia BMW
   🌐 Source: Cars.com
   🔗 https://www.cars.com/vehicledetail/...

---

🛠️ Detalles técnicos

• Extracción: Puppeteer (Chromium sin interfaz) con plugin sigiloso para evadir la detección de bots
• Concurrencia: Trabajadores de extracción en paralelo para consultas multi-fuente simultáneas
• Protocolo: Implementa MCP (Model Context Protocol) para integración con asistentes de IA
• Extracción de datos: Analizadores específicos por fuente normalizan los anuncios en un esquema común

Requisito de Chrome/Chromium

Este proyecto usa Puppeteer, que requiere Chrome o Chromium instalado:

• macOS: Chrome normalmente está en /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux: Generalmente se detecta automáticamente con Puppeteer o en /usr/bin/chromium-browser
• Windows: Normalmente en C:\Program Files\Google\Chrome\Application\chrome.exe

Si Puppeteer no puede encontrar tu navegador, establece la variable de entorno:

export PUPPETEER_EXECUTABLE_PATH="/path/to/chrome"

---

🧪 Desarrollo y pruebas

# Run tests
npm test

# Test individual scrapers
node src/scraper.js

# View code structure
ls -la src/

---

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor sigue este flujo de trabajo:

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Agrega pruebas para la nueva funcionalidad
4. Haz commit de tus cambios (git commit -m 'Add amazing feature')
5. Haz push a la rama (git push origin feature/amazing-feature)
6. Abre un Pull Request

Incluye cobertura de pruebas para cambios de extracción/análisis para evitar regresiones cuando los sitios de origen se actualicen.

---

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

---

🔗 Enlaces

• Repositorio: https://github.com/SiddarthaKoppaka/car_deals_search_mcp
• Problemas: https://github.com/SiddarthaKoppaka/car_deals_search_mcp/issues
• Protocolo MCP: https://modelcontextprotocol.io