get-vehicle-images
Get vehicle images by make and model, with optional filters for year, trim, color, angle, photo type, and more. Retrieve photos of interior, exterior, or engine from specified views.
Instructions
Get vehicle images by make, model, and optional filters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| make | Yes | Vehicle make (required) | |
| model | Yes | Vehicle model (required) | |
| year | No | Vehicle year (optional) | |
| trim | No | Vehicle trim (optional) | |
| color | No | Vehicle color (optional) | |
| transparent | No | Transparent background (optional) | |
| angle | No | Angle: front, side, back (optional) | |
| photoType | No | interior, exterior, engine (optional) | |
| size | No | Small, Medium, Large, Wallpaper, All (optional) | |
| license | No | Public, Share, ShareCommercially, Modify, ModifyCommercially (optional) | |
| format | No | json or xml (optional, default: json) |
Implementation Reference
- src/tools/getVehicleImages.ts:47-93 (handler)The async handler function that executes the 'get-vehicle-images' tool logic: processes input params, makes API request to CarsXE 'images' endpoint, and returns formatted vehicle image results.
async (params) => { // Convert all params to string for the API const stringParams: Record<string, string> = {}; for (const [key, value] of Object.entries(params)) { if (typeof value === "boolean") { stringParams[key] = value ? "true" : "false"; } else if (value !== undefined) { stringParams[key] = String(value); } } const apiKey = getApiKey(); if (!apiKey) { return { content: [ { type: "text", text: "❌ API key not provided. Please ensure X-API-Key header is set.", }, ], }; } const data = await carsxeApiRequest<CarsXEImagesResponse>( "images", stringParams, apiKey, ); if (!data) { return { content: [ { type: "text", text: "❌ Failed to retrieve images. Please check your parameters and try again.", }, ], }; } return { content: [ { type: "text", text: formatImagesResponse(data), }, ], }; }, ); - src/tools/getVehicleImages.ts:14-46 (schema)Zod schema defining input parameters: make (required), model (required), year, trim, color, transparent, angle, photoType, size, license, format (all optional).
{ make: z.string().describe("Vehicle make (required)"), model: z.string().describe("Vehicle model (required)"), year: z.string().optional().describe("Vehicle year (optional)"), trim: z.string().optional().describe("Vehicle trim (optional)"), color: z.string().optional().describe("Vehicle color (optional)"), transparent: z .boolean() .optional() .describe("Transparent background (optional)"), angle: z .string() .optional() .describe("Angle: front, side, back (optional)"), photoType: z .string() .optional() .describe("interior, exterior, engine (optional)"), size: z .string() .optional() .describe("Small, Medium, Large, Wallpaper, All (optional)"), license: z .string() .optional() .describe( "Public, Share, ShareCommercially, Modify, ModifyCommercially (optional)", ), format: z .string() .optional() .describe("json or xml (optional, default: json)"), }, - src/tools/getVehicleImages.ts:7-94 (registration)The function that registers the tool with the MCP server using server.tool('get-vehicle-images', ...) with schema and handler.
export function registerGetVehicleImagesTool( server: McpServer, getApiKey: () => string | null, ) { server.tool( "get-vehicle-images", "Get vehicle images by make, model, and optional filters", { make: z.string().describe("Vehicle make (required)"), model: z.string().describe("Vehicle model (required)"), year: z.string().optional().describe("Vehicle year (optional)"), trim: z.string().optional().describe("Vehicle trim (optional)"), color: z.string().optional().describe("Vehicle color (optional)"), transparent: z .boolean() .optional() .describe("Transparent background (optional)"), angle: z .string() .optional() .describe("Angle: front, side, back (optional)"), photoType: z .string() .optional() .describe("interior, exterior, engine (optional)"), size: z .string() .optional() .describe("Small, Medium, Large, Wallpaper, All (optional)"), license: z .string() .optional() .describe( "Public, Share, ShareCommercially, Modify, ModifyCommercially (optional)", ), format: z .string() .optional() .describe("json or xml (optional, default: json)"), }, async (params) => { // Convert all params to string for the API const stringParams: Record<string, string> = {}; for (const [key, value] of Object.entries(params)) { if (typeof value === "boolean") { stringParams[key] = value ? "true" : "false"; } else if (value !== undefined) { stringParams[key] = String(value); } } const apiKey = getApiKey(); if (!apiKey) { return { content: [ { type: "text", text: "❌ API key not provided. Please ensure X-API-Key header is set.", }, ], }; } const data = await carsxeApiRequest<CarsXEImagesResponse>( "images", stringParams, apiKey, ); if (!data) { return { content: [ { type: "text", text: "❌ Failed to retrieve images. Please check your parameters and try again.", }, ], }; } return { content: [ { type: "text", text: formatImagesResponse(data), }, ], }; }, ); } - src/MyMCP.ts:38-46 (registration)Registration call in the MyMCP class (CloudFlare Workers MCP agent).
registerGetVehicleImagesTool(this.server, getApiKey); registerGetVehicleRecallsTool(this.server, getApiKey); registerVinOcrTool(this.server, getApiKey); registerGetYearMakeModelTool(this.server, getApiKey); registerDecodeObdCodeTool(this.server, getApiKey); registerRecognizePlateImageTool(this.server, getApiKey); registerGetLienTheftTool(this.server, getApiKey); } } - src/index.gcp.ts:54-61 (registration)Registration call in the GCP/HTTP server entry point.
registerGetVehicleImagesTool(server, getApiKey); registerGetVehicleRecallsTool(server, getApiKey); registerVinOcrTool(server, getApiKey); registerGetYearMakeModelTool(server, getApiKey); registerDecodeObdCodeTool(server, getApiKey); registerRecognizePlateImageTool(server, getApiKey); registerGetLienTheftTool(server, getApiKey); } - Helper function that formats the CarsXE images API response into a human-readable markdown string showing image links, thumbnails, dimensions, etc.
export function formatImagesResponse(data: CarsXEImagesResponse): string { if (!data.success) { return `❌ Failed to retrieve images. ${data.error || ""}`; } if (!data.images?.length) { return "No images found for the specified vehicle."; } const lines = [ "### 🖼️ Vehicle Images", data.query ? `**Query:** ${Object.entries(data.query) .map(([k, v]) => `\`${k}\`: ${v}`) .join(", ")}` : "", "", ...data.images .slice(0, 5) .map((img, i) => [ `**Image ${i + 1}:**`, `- [Full Image Link](${img.link})`, img.thumbnailLink ? `- [Thumbnail](${img.thumbnailLink})` : null, img.contextLink ? `- [Source Page](${img.contextLink})` : null, img.mime ? `- **Type:** ${img.mime}` : null, img.width && img.height ? `- **Dimensions:** ${img.width}×${img.height}` : null, img.byteSize ? `- **Size:** ${img.byteSize} bytes` : null, img.accentColor ? `- **Accent Color:** #${img.accentColor}` : null, img.datePublished ? `- **Published:** ${img.datePublished.split("T")[0]}` : null, ] .filter(Boolean) .join("\n"), ), data.images.length > 5 ? `...and ${data.images.length - 5} more images.` : "", ]; return lines.filter(Boolean).join("\n\n"); } - src/utils/carsxeApi.ts:10-30 (helper)Generic API request helper that constructs the URL and calls the CarsXE API with the provided endpoint and parameters.
export async function carsxeApiRequest<T>( endpoint: string, params: Record<string, string>, apiKey: string ): Promise<T | null> { const CARSXE_API_BASE = "https://api.carsxe.com"; const queryParams = new URLSearchParams({ key: apiKey, source: "mcp", ...params, }); const url = `${CARSXE_API_BASE}/${endpoint}?${queryParams.toString()}`; try { const response = await fetch(url); if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`); return (await response.json()) as T; } catch (error) { console.error(`Error making CarsXE request to ${endpoint}:`, error); return null; } } - src/types/carsxe.ts:178-196 (schema)TypeScript interface for the CarsXE images API response (CarsXEImagesResponse).
export interface CarsXEImagesResponse { success: boolean; error?: string; images?: Array<{ mime: string; link: string; contextLink?: string; height?: number; width?: number; byteSize?: number; thumbnailLink?: string; thumbnailHeight?: number; thumbnailWidth?: number; hostPageDomainFriendlyName?: string; accentColor?: string; datePublished?: string; }>; query?: Record<string, any>; }