Car Deals Search MCP Server

Instructions

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; }