decode-vehicle-plate

Instructions

Implementation Reference

• src/tools/decodeVehiclePlate.ts:7-62 (handler)

  The registerDecodeVehiclePlateTool function registers the 'decode-vehicle-plate' MCP tool. It defines the handler logic: validates API key, calls carsxeApiRequest with the endpoint 'v2/platedecoder' passing plate/state/country, checks success, and returns formatted output via formatPlateDecoderResponse.

  export function registerDecodeVehiclePlateTool(
    server: McpServer,
    getApiKey: () => string | null,
  ) {
    server.tool(
      "decode-vehicle-plate",
      "Decode a vehicle's license plate to get VIN and basic vehicle info",
      {
        plate: z.string().min(1).describe("License plate number"),
        state: z.string().min(2).max(2).describe("State abbreviation (e.g., CA)"),
        country: z
          .string()
          .min(2)
          .max(2)
          .default("US")
          .describe("Country code (default: US)"),
      },
      async ({ plate, state, country }) => {
        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<CarsXEPlateDecoderResponse>(
          "v2/platedecoder",
          { plate, state, country },
          apiKey,
        );
        if (!data || !data.success) {
          return {
            content: [
              {
                type: "text",
                text: "❌ Failed to decode license plate. Please check the plate and state.",
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text",
              text: formatPlateDecoderResponse(data),
            },
          ],
        };
      },
    );
  }

• src/tools/decodeVehiclePlate.ts:14-23 (schema)

  Input schema for the tool: 'plate' (required string), 'state' (required 2-char string), 'country' (optional 2-char string, defaults to 'US'). Validated using Zod.

  {
    plate: z.string().min(1).describe("License plate number"),
    state: z.string().min(2).max(2).describe("State abbreviation (e.g., CA)"),
    country: z
      .string()
      .min(2)
      .max(2)
      .default("US")
      .describe("Country code (default: US)"),
  },

• src/types/carsxe.ts:50-71 (schema)

  TypeScript interface CarsXEPlateDecoderResponse defining the response shape including success, input, description, make, model, trim, vin, style, year, assembly, fuel_type, color, body_style, engine_size, drive_type, transmission.

  export interface CarsXEPlateDecoderResponse {
    success: boolean;
    input: {
      plate: string;
      state: string;
      country: string;
    };
    description: string;
    make: string;
    model: string;
    trim: string;
    vin: string;
    style: string;
    year: string;
    assembly: string;
    fuel_type: string;
    color: string;
    body_style: string;
    engine_size: string;
    drive_type: string;
    transmission: string;
  }

• src/MyMCP.ts:33-45 (registration)

  Registration call in MyMCP (Cloudflare Workers MCP Agent). registerDecodeVehiclePlateTool is invoked with the server instance and API key getter on line 34.

    registerGetVehicleSpecsTool(this.server, getApiKey);
    registerDecodeVehiclePlateTool(this.server, getApiKey);
    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:48-61 (registration)

  Registration call in the GCP/standalone HTTP server version. registerDecodeVehiclePlateTool is invoked inside registerAllTools on line 50.

  function registerAllTools(server: McpServer, getApiKey: () => string | null): void {
    registerGetVehicleSpecsTool(server, getApiKey);
    registerDecodeVehiclePlateTool(server, getApiKey);
    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);
  }

• src/formatters/formatPlateDecoderResponse.ts:3-37 (helper)

  Helper formatter that takes a CarsXEPlateDecoderResponse and produces a human-readable string with vehicle details (year, make, model, VIN, style, etc.)

  export function formatPlateDecoderResponse(
    data: CarsXEPlateDecoderResponse,
  ): string {
    const {
      year,
      make,
      model,
      trim,
      vin,
      style,
      assembly,
      fuel_type,
      color,
      body_style,
      engine_size,
      drive_type,
      transmission,
      description,
    } = data;
    return [
      `🚗 ${year} ${make} ${model} ${trim}`,
      `VIN: ${vin}`,
      `Style: ${style}`,
      `Body: ${body_style}`,
      `Color: ${color}`,
      `Engine: ${engine_size}`,
      `Fuel: ${fuel_type}`,
      `Drive: ${drive_type}`,
      `Transmission: ${transmission}`,
      `Assembly: ${assembly}`,
      `Description: ${description}`,
    ]
      .filter(Boolean)
      .join("\n");
  }

• src/utils/carsxeApi.ts:10-30 (helper)

  Generic API request helper used by the handler to call the CarsXE API endpoint v2/platedecoder.

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