search_car_deals
Search for used car deals across Cars.com, Autotrader, and KBB. Filter by make, model, price, mileage, year, and vehicle history to find matching listings with prices and dealer information.
Instructions
Search for car deals across multiple sources (Cars.com, Autotrader, KBB). Returns listings with prices, mileage, deal ratings, and links.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| make | Yes | Car manufacturer (e.g., Toyota, Honda, Ford) | |
| model | Yes | Car model (e.g., Camry, Civic, F-150) | |
| zip | No | ZIP code for location-based search (default: 90210) | |
| yearMin | No | Minimum model year | |
| yearMax | No | Maximum model year | |
| priceMax | No | Maximum price in dollars | |
| mileageMax | No | Maximum mileage | |
| maxResults | No | Maximum results per source (default: 10) | |
| sources | No | Sources to search: "cars.com", "autotrader", "kbb". Default: all | |
| oneOwner | No | Filter for CARFAX 1-Owner vehicles only | |
| noAccidents | No | Filter for vehicles with no accidents or damage reported | |
| personalUse | No | Filter for vehicles used for personal use only (not rental/fleet) |
Implementation Reference
- src/server.js:32-96 (registration)Registers the 'search_car_deals' tool by defining its name, description, and input schema in the ListToolsRequestSchema handler.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'search_car_deals', description: 'Search for car deals across multiple sources (Cars.com, Autotrader, KBB). Returns listings with prices, mileage, deal ratings, and links.', inputSchema: { type: 'object', properties: { make: { type: 'string', description: 'Car manufacturer (e.g., Toyota, Honda, Ford)', }, model: { type: 'string', description: 'Car model (e.g., Camry, Civic, F-150)', }, zip: { type: 'string', description: 'ZIP code for location-based search (default: 90210)', }, yearMin: { type: 'integer', description: 'Minimum model year', }, yearMax: { type: 'integer', description: 'Maximum model year', }, priceMax: { type: 'integer', description: 'Maximum price in dollars', }, mileageMax: { type: 'integer', description: 'Maximum mileage', }, maxResults: { type: 'integer', description: 'Maximum results per source (default: 10)', }, sources: { type: 'array', items: { type: 'string' }, description: 'Sources to search: "cars.com", "autotrader", "kbb". Default: all', }, oneOwner: { type: 'boolean', description: 'Filter for CARFAX 1-Owner vehicles only', }, noAccidents: { type: 'boolean', description: 'Filter for vehicles with no accidents or damage reported', }, personalUse: { type: 'boolean', description: 'Filter for vehicles used for personal use only (not rental/fleet)', }, }, required: ['make', 'model'], }, }, ], }; }); - src/server.js:38-92 (schema)Input schema definition for the 'search_car_deals' tool, specifying parameters such as make, model, location, price/mileage limits, sources, and CarFax filters.
inputSchema: { type: 'object', properties: { make: { type: 'string', description: 'Car manufacturer (e.g., Toyota, Honda, Ford)', }, model: { type: 'string', description: 'Car model (e.g., Camry, Civic, F-150)', }, zip: { type: 'string', description: 'ZIP code for location-based search (default: 90210)', }, yearMin: { type: 'integer', description: 'Minimum model year', }, yearMax: { type: 'integer', description: 'Maximum model year', }, priceMax: { type: 'integer', description: 'Maximum price in dollars', }, mileageMax: { type: 'integer', description: 'Maximum mileage', }, maxResults: { type: 'integer', description: 'Maximum results per source (default: 10)', }, sources: { type: 'array', items: { type: 'string' }, description: 'Sources to search: "cars.com", "autotrader", "kbb". Default: all', }, oneOwner: { type: 'boolean', description: 'Filter for CARFAX 1-Owner vehicles only', }, noAccidents: { type: 'boolean', description: 'Filter for vehicles with no accidents or damage reported', }, personalUse: { type: 'boolean', description: 'Filter for vehicles used for personal use only (not rental/fleet)', }, }, required: ['make', 'model'], }, - src/server.js:102-241 (handler)The core handler function that executes the tool: parses arguments, runs selected scrapers (scrapeCarscom, scrapeAutotrader, scrapeKBB), aggregates CarListing objects, and returns formatted markdown results.
if (name === 'search_car_deals') { try { const params = { make: args.make, model: args.model, zip: args.zip || '90210', yearMin: args.yearMin, yearMax: args.yearMax, priceMax: args.priceMax, mileageMax: args.mileageMax, // CarFax history filters oneOwner: args.oneOwner, noAccidents: args.noAccidents, personalUse: args.personalUse, }; const maxResults = args.maxResults || 10; // Default to just cars.com for reliability const sources = args.sources || ['cars.com']; console.error(`[MCP] Searching for ${params.make} ${params.model} in ${params.zip}`); console.error(`[MCP] Sources: ${sources.join(', ')}, Max: ${maxResults}`); let allListings = []; let errors = []; // Run selected scrapers const scraperPromises = []; if (sources.includes('cars.com')) { console.error('[MCP] Starting Cars.com scraper...'); scraperPromises.push( scrapeCarscom(params, maxResults) .then(listings => { console.error(`[MCP] Cars.com returned ${listings.length} listings`); return { source: 'Cars.com', listings }; }) .catch(err => { console.error(`[MCP] Cars.com error: ${err.message}`); return { source: 'Cars.com', error: err.message, listings: [] }; }) ); } if (sources.includes('autotrader')) { console.error('[MCP] Starting Autotrader scraper...'); scraperPromises.push( scrapeAutotrader(params, maxResults) .then(listings => { console.error(`[MCP] Autotrader returned ${listings.length} listings`); return { source: 'Autotrader', listings }; }) .catch(err => { console.error(`[MCP] Autotrader error: ${err.message}`); return { source: 'Autotrader', error: err.message, listings: [] }; }) ); } if (sources.includes('kbb')) { console.error('[MCP] Starting KBB scraper...'); scraperPromises.push( scrapeKBB(params, maxResults) .then(listings => { console.error(`[MCP] KBB returned ${listings.length} listings`); return { source: 'KBB', listings }; }) .catch(err => { console.error(`[MCP] KBB error: ${err.message}`); return { source: 'KBB', error: err.message, listings: [] }; }) ); } const results = await Promise.all(scraperPromises); console.error(`[MCP] All scrapers completed`); for (const result of results) { allListings.push(...result.listings); if (result.error) { errors.push(`${result.source}: ${result.error}`); } } console.error(`[MCP] Total listings: ${allListings.length}`); // Format output let output = `# Car Deals Search Results\n\n`; output += `**Search:** ${params.make} ${params.model}`; if (params.yearMin || params.yearMax) { output += ` (${params.yearMin || 'any'}-${params.yearMax || 'any'})`; } if (params.priceMax) output += ` | Max Price: $${params.priceMax.toLocaleString()}`; if (params.mileageMax) output += ` | Max Mileage: ${params.mileageMax.toLocaleString()}`; // Show active CarFax filters const activeFilters = []; if (params.oneOwner) activeFilters.push('1-Owner'); if (params.noAccidents) activeFilters.push('No Accidents'); if (params.personalUse) activeFilters.push('Personal Use'); if (activeFilters.length > 0) output += `\n**CarFax Filters:** ${activeFilters.join(', ')}`; output += `\n**Location:** ${params.zip}\n\n`; if (allListings.length === 0) { output += `No listings found.\n`; } else { output += `Found **${allListings.length}** listings:\n\n`; for (const listing of allListings) { output += listing.format() + '\n\n---\n\n'; } } if (errors.length > 0) { output += `\n**Errors:**\n`; for (const err of errors) { output += `- ${err}\n`; } } return { content: [ { type: 'text', text: output, }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error searching for car deals: ${error.message}`, }, ], isError: true, }; } } - src/scraper.js:63-199 (helper)Helper function to scrape Cars.com listings using Puppeteer, parsing vehicle cards into CarListing objects supporting all tool filters.
async function scrapeCarscom(params, maxResults = 20) { const listings = []; let browser; try { browser = await launchBrowser(); const page = await browser.newPage(); await page.setViewport({ width: 1920, height: 1080 }); // Build URL let url = 'https://www.cars.com/shopping/results/?'; const urlParams = new URLSearchParams(); urlParams.append('stock_type', 'used'); if (params.make) urlParams.append('makes[]', params.make.toLowerCase()); if (params.model) urlParams.append('models[]', `${params.make.toLowerCase()}-${params.model.toLowerCase()}`); if (params.zip) urlParams.append('zip', params.zip); if (params.yearMin) urlParams.append('year_min', params.yearMin); if (params.yearMax) urlParams.append('year_max', params.yearMax); if (params.priceMax) urlParams.append('list_price_max', params.priceMax); if (params.mileageMax) urlParams.append('mileage_max', params.mileageMax); // CarFax history filters if (params.oneOwner) urlParams.append('one_owner', 'true'); if (params.noAccidents) urlParams.append('no_accidents', 'true'); if (params.personalUse) urlParams.append('personal_use', 'true'); url += urlParams.toString(); await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }); await new Promise(r => setTimeout(r, 5000)); // Extract listings from .vehicle-card elements const rawListings = await page.evaluate(() => { const results = []; const cards = document.querySelectorAll('.vehicle-card'); cards.forEach(card => { const text = card.innerText; const lines = text.split('\n').filter(l => l.trim()); let title = null; let price = null; let mileage = null; let dealRating = null; let dealerName = null; let location = null; for (const line of lines) { const trimmed = line.trim(); // Title: Year Make Model (e.g., "2020 Toyota Camry XSE") if (/^(19|20)\d{2}\s+\w+/.test(trimmed) && !title) { title = trimmed; continue; } // Price: "$XX,XXX" (may have "price drop" suffix) const priceMatch = trimmed.match(/^\$[\d,]+/); if (priceMatch && !price) { price = priceMatch[0]; continue; } // Mileage: "XX,XXX mi." if (/^[\d,]+\s*mi\.?$/i.test(trimmed) && !mileage) { mileage = trimmed; continue; } // Deal rating: "Good Deal", "Great Deal", etc. if (/^(great|good|fair|high|no price)/i.test(trimmed) && !dealRating) { dealRating = trimmed.split('|')[0].trim(); continue; } // Location: "City, ST (XX mi.)" if (/^[A-Z][a-z]+.*,\s*[A-Z]{2}\s*\(/i.test(trimmed) && !location) { location = trimmed; continue; } } // Get dealer name - usually after reviews count const dealerMatch = card.querySelector('.dealer-name'); if (dealerMatch) { dealerName = dealerMatch.innerText.trim(); } else { // Fallback: look for line before reviews for (let i = 0; i < lines.length; i++) { if (lines[i].includes('reviews') && i > 0) { dealerName = lines[i - 1].trim(); break; } } } // Get URL from the card link const linkEl = card.querySelector('a.vehicle-card-link'); const href = linkEl ? linkEl.getAttribute('href') : null; // Check for CarFax badges const fullText = text.toLowerCase(); const isOneOwner = fullText.includes('1-owner') || fullText.includes('one owner'); const noAccidents = fullText.includes('no accident') || fullText.includes('clean'); const personalUse = fullText.includes('personal use'); if (title) { results.push({ title, price, mileage, dealRating, dealerName, location, href, isOneOwner, noAccidents, personalUse }); } }); return results; }); for (const item of rawListings.slice(0, maxResults)) { listings.push(new CarListing({ title: item.title, price: item.price, mileage: item.mileage, dealerName: item.dealerName, dealRating: item.dealRating, url: item.href ? `https://www.cars.com${item.href}` : null, source: 'Cars.com', isOneOwner: item.isOneOwner, noAccidents: item.noAccidents, personalUse: item.personalUse })); } await browser.close(); } catch (err) { if (browser) await browser.close(); throw new Error(`Cars.com scraping failed: ${err.message}`); } return listings; } - src/scraper.js:8-42 (helper)Data class for car listings used by all scrapers, with format() method for tool output.
class CarListing { constructor(data) { this.title = data.title || null; this.price = data.price || null; this.mileage = data.mileage || null; this.dealerName = data.dealerName || null; this.location = data.location || null; this.dealRating = data.dealRating || null; this.url = data.url || null; this.source = data.source || null; // CarFax badges this.isOneOwner = data.isOneOwner || false; this.noAccidents = data.noAccidents || false; this.personalUse = data.personalUse || false; } format() { let result = `${this.title || 'Unknown Vehicle'}`; if (this.price) result += `\n Price: ${this.price}`; if (this.mileage) result += `\n Mileage: ${this.mileage}`; if (this.dealRating) result += `\n Deal Rating: ${this.dealRating}`; // CarFax badges const badges = []; if (this.isOneOwner) badges.push('1-Owner'); if (this.noAccidents) badges.push('No Accidents'); if (this.personalUse) badges.push('Personal Use'); if (badges.length > 0) result += `\n CarFax: ${badges.join(' | ')}`; if (this.dealerName) result += `\n Dealer: ${this.dealerName}`; if (this.location) result += `\n Location: ${this.location}`; if (this.source) result += `\n Source: ${this.source}`; if (this.url) result += `\n ${this.url}`; return result; }