international-vin-decoder

Instructions

Implementation Reference

• src/tools/internationalVinDecoder.ts:1-60 (handler)

  Tool handler: registers the 'international-vin-decoder' tool on the MCP server. Accepts a 17-character VIN, calls the CarsXE API endpoint 'v1/international-vin-decoder', and returns formatted results.

  import { z } from "zod";
  import { carsxeApiRequest } from "../utils/carsxeApi.js";
  import { CarsXEInternationalVinDecoderResponse } from "../types/carsxe.js";
  import { formatInternationalVinDecoderResponse } from "../formatters/carsxe.js";
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  
  export function registerInternationalVinDecoderTool(
    server: McpServer,
    getApiKey: () => string | null,
  ) {
    server.tool(
      "international-vin-decoder",
      "Decode an international VIN and get detailed vehicle info",
      {
        vin: z
          .string()
          .min(17)
          .max(17)
          .describe("17-character Vehicle Identification Number"),
      },
      async ({ vin }) => {
        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<CarsXEInternationalVinDecoderResponse>(
            "v1/international-vin-decoder",
            { vin },
            apiKey,
          );
        if (!data || !data.success) {
          return {
            content: [
              {
                type: "text",
                text: "❌ Failed to decode international VIN. Please check the VIN and try again.",
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text",
              text: formatInternationalVinDecoderResponse(data),
            },
          ],
        };
      },
    );
  }

• src/types/carsxe.ts:73-123 (schema)

  Schema: CarsXEInternationalVinDecoderResponse interface defining all response fields (VIN, make, model, year, dimensions, emissions, etc.)

  export interface CarsXEInternationalVinDecoderResponse {
    success: boolean;
    input: {
      vin: string;
    };
    attributes: {
      vin: string;
      vid: string;
      make: string;
      model: string;
      year: string;
      product_type: string;
      body: string;
      series: string;
      fuel_type: string;
      gears: string;
      emission_standard: string;
      manufacturer: string;
      manufacturer_address: string;
      plant_country: string;
      engine_manufacturer: string;
      avg_co2_emission_g_km: string;
      no_of_axels: string;
      no_of_doors: string;
      no_of_seats: string;
      rear_brakes: string;
      steering_type: string;
      rear_suspension: string;
      front_suspension: string;
      wheel_size: string;
      wheel_size_array: string;
      wheelbase_mm: string;
      wheelbase_array_mm: string;
      height_mm: string;
      length_mm: string;
      width_mm: string;
      track_front_mm: string;
      track_rear_mm: string;
      max_speed_kmh: string;
      max_trunk_capacity_liters: string;
      min_trunk_capacity_liters: string;
      weight_empty_kg: string;
      max_weight_kg: string;
      max_roof_load_kg: string;
      permitted_trailer_load_without_brakes_kg: string;
      abs: string;
      check_digit: string;
      sequential_number: string;
    };
    timestamp: string;
  }

• src/formatters/formatInternationalVinDecoderResponse.ts:1-52 (helper)

  Helper: formatInternationalVinDecoderResponse transforms the API response into a formatted multiline string with all vehicle attributes.

  import { CarsXEInternationalVinDecoderResponse } from "../types/carsxe.js";
  
  export function formatInternationalVinDecoderResponse(
    data: CarsXEInternationalVinDecoderResponse,
  ): string {
    const a = data.attributes;
    return [
      `🌍 International VIN Decode`,
      `VIN: ${a.vin}`,
      `Make: ${a.make}`,
      `Model: ${a.model}`,
      `Year: ${a.year}`,
      `Product Type: ${a.product_type}`,
      `Body: ${a.body}`,
      `Series: ${a.series}`,
      `Fuel Type: ${a.fuel_type}`,
      `Gears: ${a.gears}`,
      `Emission Standard: ${a.emission_standard}`,
      `Manufacturer: ${a.manufacturer}`,
      `Manufacturer Address: ${a.manufacturer_address}`,
      `Plant Country: ${a.plant_country}`,
      `Engine Manufacturer: ${a.engine_manufacturer}`,
      `CO2 Emission (g/km): ${a.avg_co2_emission_g_km}`,
      `Axels: ${a.no_of_axels}`,
      `Doors: ${a.no_of_doors}`,
      `Seats: ${a.no_of_seats}`,
      `Rear Brakes: ${a.rear_brakes}`,
      `Steering: ${a.steering_type}`,
      `Rear Suspension: ${a.rear_suspension}`,
      `Front Suspension: ${a.front_suspension}`,
      `Wheel Size: ${a.wheel_size}`,
      `Wheelbase (mm): ${a.wheelbase_mm}`,
      `Height (mm): ${a.height_mm}`,
      `Length (mm): ${a.length_mm}`,
      `Width (mm): ${a.width_mm}`,
      `Track Front (mm): ${a.track_front_mm}`,
      `Track Rear (mm): ${a.track_rear_mm}`,
      `Max Speed (km/h): ${a.max_speed_kmh}`,
      `Trunk Capacity (L): ${a.min_trunk_capacity_liters} - ${a.max_trunk_capacity_liters}`,
      `Weight Empty (kg): ${a.weight_empty_kg}`,
      `Max Weight (kg): ${a.max_weight_kg}`,
      `Max Roof Load (kg): ${a.max_roof_load_kg}`,
      `Permitted Trailer Load (kg, no brakes): ${a.permitted_trailer_load_without_brakes_kg}`,
      `ABS: ${a.abs === "1" ? "Yes" : "No"}`,
      `Check Digit: ${a.check_digit}`,
      `Sequential Number: ${a.sequential_number}`,
      `Timestamp: ${data.timestamp}`,
    ]
      .filter(Boolean)
      .join("\n");
  }

• src/MyMCP.ts:35-46 (registration)

  Registration: calls registerInternationalVinDecoderTool(this.server, getApiKey) in the MyMCP agent initialization.

      registerInternationalVinDecoderTool(this.server, getApiKey);
      registerGetMarketValueTool(this.server, getApiKey);
      registerGetVehicleHistoryTool(this.server, getApiKey);
      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:51-61 (registration)

  Registration: calls registerInternationalVinDecoderTool(server, getApiKey) in the registerAllTools function for the HTTP server deployment.

    registerInternationalVinDecoderTool(server, getApiKey);
    registerGetMarketValueTool(server, getApiKey);
    registerGetVehicleHistoryTool(server, getApiKey);
    registerGetVehicleImagesTool(server, getApiKey);
    registerGetVehicleRecallsTool(server, getApiKey);
    registerVinOcrTool(server, getApiKey);
    registerGetYearMakeModelTool(server, getApiKey);
    registerDecodeObdCodeTool(server, getApiKey);
    registerRecognizePlateImageTool(server, getApiKey);
    registerGetLienTheftTool(server, getApiKey);
  }