get-vehicle-history
Retrieve a comprehensive vehicle history report using a 17-character VIN. Get detailed information about accidents, ownership, and more.
Instructions
Get a comprehensive vehicle history report by VIN
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| vin | Yes | 17-character Vehicle Identification Number | |
| format | No | Response format (json or xml, default: json) |
Implementation Reference
- src/tools/getVehicleHistory.ts:7-65 (handler)Main handler function that registers the 'get-vehicle-history' tool with MCP server. Accepts a VIN (17 characters) and optional format, calls the CarsXE API's 'history' endpoint, and returns formatted output.
export function registerGetVehicleHistoryTool( server: McpServer, getApiKey: () => string | null, ) { server.tool( "get-vehicle-history", "Get a comprehensive vehicle history report by VIN", { vin: z .string() .min(17) .max(17) .describe("17-character Vehicle Identification Number"), format: z .string() .optional() .describe("Response format (json or xml, default: json)"), }, async ({ vin, format }) => { const params: Record<string, string> = { vin }; if (format) params.format = format; 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<CarsXEHistoryResponse>( "history", params, apiKey, ); if (!data || !data.success) { return { content: [ { type: "text", text: "❌ Failed to retrieve vehicle history. Please check the VIN and try again.", }, ], }; } return { content: [ { type: "text", text: formatHistoryResponse(data), }, ], }; }, ); } - src/types/carsxe.ts:164-176 (schema)Type definition for the vehicle history API response, containing fields for junk/salvage, insurance, brands, title, and history information.
export interface CarsXEHistoryResponse { vin: string; success: boolean; junkAndSalvageInformation?: any[]; insuranceInformation?: any[]; brandsRecordCount?: number; brandsInformation?: any[]; vinChanged?: boolean; currentTitleInformation?: any[]; historyInformation?: any[]; status?: string; error?: { code?: string; message?: string }; } - src/tools/getVehicleHistory.ts:7-65 (registration)The tool is registered via server.tool() call with the name 'get-vehicle-history'.
export function registerGetVehicleHistoryTool( server: McpServer, getApiKey: () => string | null, ) { server.tool( "get-vehicle-history", "Get a comprehensive vehicle history report by VIN", { vin: z .string() .min(17) .max(17) .describe("17-character Vehicle Identification Number"), format: z .string() .optional() .describe("Response format (json or xml, default: json)"), }, async ({ vin, format }) => { const params: Record<string, string> = { vin }; if (format) params.format = format; 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<CarsXEHistoryResponse>( "history", params, apiKey, ); if (!data || !data.success) { return { content: [ { type: "text", text: "❌ Failed to retrieve vehicle history. Please check the VIN and try again.", }, ], }; } return { content: [ { type: "text", text: formatHistoryResponse(data), }, ], }; }, ); } - Helper formatter that transforms the raw API response into a human-readable string with sections for junk/salvage, insurance, brand records, title info, and historical records.
export function formatHistoryResponse(data: CarsXEHistoryResponse): string { const lines = [ `### 🕓 Vehicle History Report`, `**VIN:** ${data.vin}`, data.success ? "✅ History data found." : "❌ No history data found.", "", ]; if (data.junkAndSalvageInformation?.length) { lines.push("**Junk & Salvage Records:**"); data.junkAndSalvageInformation.forEach((rec) => { const ent = rec.ReportingEntityAbstract || {}; lines.push( `- **Entity:** ${ent.EntityName || "N/A"} (${ ent.LocationCityName || "" }, ${ent.LocationStateUSPostalServiceCode || ""})`, ` - **Obtained Date:** ${ rec.VehicleObtainedDate ? rec.VehicleObtainedDate.split("T")[0] : "N/A" }`, ` - **Disposition:** ${rec.VehicleDispositionText || "N/A"}`, ` - **Intended for Export:** ${ rec.VehicleIntendedForExportCode === "Y" ? "Yes" : "No" }`, ); }); lines.push(""); } if (data.insuranceInformation?.length) { lines.push("**Insurance Records:**"); data.insuranceInformation.forEach((rec) => { const ent = rec.ReportingEntityAbstract || {}; lines.push( `- **Insurer:** ${ent.EntityName || "N/A"} (${ ent.LocationCityName || "" }, ${ent.LocationStateUSPostalServiceCode || ""})`, ` - **Obtained Date:** ${ rec.VehicleObtainedDate ? rec.VehicleObtainedDate.split("T")[0] : "N/A" }`, ); }); lines.push(""); } if (data.brandsInformation?.length) { lines.push("**Brand Records:**"); data.brandsInformation.forEach((brand) => { lines.push( `- **${brand.name || brand.code}:** ${brand.description || ""}`, ); }); lines.push(""); } if (data.currentTitleInformation?.length) { lines.push("**Current Title Information:**"); data.currentTitleInformation.forEach((rec) => { lines.push( `- **Authority:** ${rec.TitleIssuingAuthorityName || "N/A"}`, ` - **Issue Date:** ${ rec.TitleIssueDate?.Date ? rec.TitleIssueDate.Date.split("T")[0] : "N/A" }`, ` - **Odometer:** ${rec.VehicleOdometerReadingMeasure || "N/A"} ${ rec.VehicleOdometerReadingUnitCode || "" }`, ); if (rec.HistoricTitleAbstract?.length) { lines.push(" - **Historic Titles:**"); rec.HistoricTitleAbstract.forEach((h: any) => { lines.push( ` - **Date:** ${ h.TitleIssueDate?.Date ? h.TitleIssueDate.Date.split("T")[0] : "N/A" }, **Odometer:** ${h.VehicleOdometerReadingMeasure || "N/A"} ${ h.VehicleOdometerReadingUnitCode || "" }`, ); }); } }); lines.push(""); } if (data.historyInformation?.length) { lines.push("**Historical Records:**"); data.historyInformation.forEach((rec) => { lines.push( `- **Authority:** ${rec.TitleIssuingAuthorityName || "N/A"}`, ` - **Date:** ${ rec.TitleIssueDate?.Date ? rec.TitleIssueDate.Date.split("T")[0] : "N/A" }`, ` - **Odometer:** ${rec.VehicleOdometerReadingMeasure || "N/A"} ${ rec.VehicleOdometerReadingUnitCode || "" }`, ); }); lines.push(""); } if (data.vinChanged !== undefined) { lines.push(`**VIN Changed:** ${data.vinChanged ? "Yes" : "No"}`); } if (data.status) { lines.push(`**Status:** ${data.status}`); } if (data.error) { lines.push( `**Error:** ${data.error.code || ""} ${data.error.message || ""}`, ); } return lines.filter(Boolean).join("\n"); } - src/utils/carsxeApi.ts:10-30 (helper)Generic API request helper used to call the CarsXE API; invoked with endpoint 'history' for the vehicle history tool.
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; } }