CarDeals-MCP

Car Deals Search MCP

Pesquise anúncios de carros usados no Cars.com, Autotrader e KBB com assistentes de IA

Um servidor MCP (Model Context Protocol) que agrega e pesquisa anúncios de carros de múltiplas fontes. Faz scraping de anúncios em paralelo, extrai preço, quilometragem, informações da concessionária e aplica filtros opcionais no estilo CARFAX (1º proprietário, sem acidentes, uso pessoal).

---

🚀 Início Rápido

Pré-requisitos

• Node.js (v16 ou superior)
• Navegador Chrome/Chromium instalado (necessário para o Puppeteer)
  • Se o Chrome não estiver no local padrão, defina a variável de ambiente PUPPETEER_EXECUTABLE_PATH para apontar para o binário do seu Chrome/Chromium

Instalação

# 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 com Clientes MCP

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

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

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

Para outros clientes MCP, consulte a documentação deles e use:

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

Teste Autônomo

# 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())));
"

---

✨ Recursos

• Agregação multi-fonte: Pesquise no Cars.com, Autotrader e KBB simultaneamente
• Filtros inteligentes: Filtros no estilo CARFAX (1º Proprietário, Sem Acidentes, Uso Pessoal)
• Avaliação de ofertas: Avaliação heurística da qualidade das ofertas
• Extração paralela: Consultas concorrentes rápidas entre fontes
• Modo furtivo: Puppeteer com técnicas anti-detecção de bots

---

📊 Fontes Suportadas

Fonte	Preço	Quilometragem	Avaliação de Oferta	Informações da Concessionária	Filtros CARFAX
Cars.com	✅	✅	✅	✅	✅
Autotrader	✅	✅	⚠️ Limitada	✅	⚠️ Limitados
KBB	✅	✅	✅	⚠️ Limitadas	⚠️ Limitados

---

🔧 Ferramenta MCP: search_car_deals

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
make	string	✅	Fabricante do carro (ex.: "Toyota", "Honda")
model	string	✅	Modelo do carro (ex.: "Camry", "Accord")
zip	string	❌	CEP para busca local (padrão: "90210")
yearMin	integer	❌	Ano mínimo do modelo
yearMax	integer	❌	Ano máximo do modelo
priceMax	integer	❌	Preço máximo em USD
mileageMax	integer	❌	Quilometragem máxima
maxResults	integer	❌	Máximo de resultados por fonte (padrão: 10)
sources	array	❌	Fontes a consultar: ["cars.com","autotrader","kbb"] (padrão: todas)
oneOwner	boolean	❌	Filtrar apenas veículos com 1º proprietário no CARFAX
noAccidents	boolean	❌	Filtrar por nenhum acidente registrado
personalUse	boolean	❌	Filtrar apenas por uso pessoal (não aluguel/frota)

Exemplo de Resposta

🚗 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/...

---

🛠️ Detalhes Técnicos

• Scraping: Puppeteer (Chromium headless) com plugin stealth para contornar a detecção de bots
• Concorrência: Workers de scraping paralelos para consultas multi-fonte simultâneas
• Protocolo: Implementa MCP (Model Context Protocol) para integração com assistentes de IA
• Extração de dados: Parsers específicos por fonte normalizam os anúncios em um esquema comum

Requisito de Chrome/Chromium

Este projeto usa Puppeteer, que requer Chrome ou Chromium instalado:

• macOS: O Chrome normalmente fica em /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux: Geralmente detectado automaticamente pelo Puppeteer ou em /usr/bin/chromium-browser
• Windows: Normalmente em C:\Program Files\Google\Chrome\Application\chrome.exe

Se o Puppeteer não encontrar seu navegador, defina a variável de ambiente:

export PUPPETEER_EXECUTABLE_PATH="/path/to/chrome"

---

🧪 Desenvolvimento e Testes

# Run tests
npm test

# Test individual scrapers
node src/scraper.js

# View code structure
ls -la src/

---

🤝 Contribuições

Contribuições são bem-vindas! Siga este fluxo de trabalho:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Adicione testes para novas funcionalidades
4. Faça commit das suas alterações (git commit -m 'Add amazing feature')
5. Envie para o branch (git push origin feature/amazing-feature)
6. Abra um Pull Request

Inclua cobertura de testes para alterações de scraping/parse para evitar regressões quando os sites de origem forem atualizados.

---

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes

---

🔗 Links

• Repositório: https://github.com/SiddarthaKoppaka/car_deals_search_mcp
• Issues: https://github.com/SiddarthaKoppaka/car_deals_search_mcp/issues
• Protocolo MCP: https://modelcontextprotocol.io