Skip to main content
Glama
SiddarthaKoppaka

Car Deals Search MCP Server

by SiddarthaKoppaka
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Remote

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
NameRequiredDescriptionDefault
makeYesCar manufacturer (e.g., Toyota, Honda, Ford)
modelYesCar model (e.g., Camry, Civic, F-150)
zipNoZIP code for location-based search (default: 90210)
yearMinNoMinimum model year
yearMaxNoMaximum model year
priceMaxNoMaximum price in dollars
mileageMaxNoMaximum mileage
maxResultsNoMaximum results per source (default: 10)
sourcesNoSources to search: "cars.com", "autotrader", "kbb". Default: all
oneOwnerNoFilter for CARFAX 1-Owner vehicles only
noAccidentsNoFilter for vehicles with no accidents or damage reported
personalUseNoFilter 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;
    }

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool searches across multiple sources and returns listings with specific fields. However, it does not mention any limitations, rate limits, authentication requirements, or what happens if no results are found. It does not contradict anything, but it lacks depth in behavioral disclosure beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the primary action and result. Every part is informative with no waste. It efficiently communicates the tool's purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 12 parameters and no output schema, the description provides enough context by mentioning the return fields (prices, mileage, deal ratings, links). It does not explain ordering, pagination, or error handling, but the schema covers parameter semantics. Given the tool's complexity, it is reasonably complete, though slightly more detail on result behavior would justify a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage with descriptions for every parameter. The tool description does not add additional parameter-specific semantics beyond what the schema already states, such as the use of 'maxResults' or 'oneOwner'. Per the baseline rule, since schema coverage is high, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Search'), a specific resource ('car deals'), and names the sources (Cars.com, Autotrader, KBB) and return types (prices, mileage, deal ratings, links). It is clear and distinct, though there are no sibling tools to differentiate from. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies usage: search for car deals using the provided filters. Since no sibling tools are listed, there is no need to specify alternatives or exclusions. The context is clear, but it does not explicitly state when not to use or what alternatives exist. Given the absence of siblings, this is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools