recognize-plate-image

Instructions

Implementation Reference

• src/tools/recognizePlateImage.ts:14-103 (handler)

  Handler function (registerRecognizePlateImageTool) that registers the 'recognize-plate-image' MCP tool. It accepts an imageUrl, sends a POST request to the CarsXE plate recognition API, and returns formatted results.

  export function registerRecognizePlateImageTool(
    server: McpServer,
    getApiKey: () => string | null,
  ) {
    server.tool(
      "recognize-plate-image",
      "Recognize and extract license plate(s) from a vehicle image URL",
      {
        imageUrl: z
          .string()
          .url()
          .describe("Direct URL to an image of a vehicle's license plate"),
      },
      async ({ imageUrl }) => {
        if (!imageUrl) {
          return {
            content: [
              {
                type: "text",
                text: "❌ Plate recognition failed. Image URL is required.",
              },
            ],
          };
        }
        // POST request with body as imageUrl
        const apiKey = getApiKey();
        console.log(
          "apiKey recognizePlateImage",
          apiKey ? `***${apiKey.slice(-4)}` : "null",
        );
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "❌ API key not provided. Please ensure X-API-Key header is set.",
              },
            ],
          };
        }
  
        const CARSXE_API_BASE = "https://api.carsxe.com";
        const url = `${CARSXE_API_BASE}/platerecognition?key=${apiKey}&source=mcp`;
        let data: CarsXEPlateRecognitionResponse | null = null;
        try {
          const response = await fetch(url, {
            method: "POST",
            headers: { "Content-Type": "text/plain" },
            body: imageUrl,
          });
          if (!response.ok)
            throw new Error(`HTTP error! status: ${response.status}`);
          data = await response.json();
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `❌ Plate recognition failed. ${
                  error instanceof Error
                    ? error.message
                    : String(error) || "Unknown error."
                }`,
              },
            ],
          };
        }
        if (!data || !data.success) {
          return {
            content: [
              {
                type: "text",
                text: `❌ Plate recognition failed. ${
                  data?.message || "Unknown error."
                }`,
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text",
              text: formatPlateRecognitionResponse(data),
            },
          ],
        };
      },
    );
  }

• src/types/carsxe.ts:305-334 (schema)

  Type definition for CarsXEPlateRecognitionResponse, defining the shape of the API response including results with candidates, region, vehicle, box, and scores.

  export interface CarsXEPlateRecognitionResponse {
    success: boolean;
    message?: string;
    camera_id?: string | null;
    filename?: string;
    processing_time?: number;
    results?: Array<{
      box: {
        xmax: number;
        xmin: number;
        ymax: number;
        ymin: number;
      };
      candidates: Array<{
        plate: string;
        score: number;
      }>;
      dscore?: number;
      plate: string;
      region?: {
        code: string;
        score: number;
      };
      score: number;
      vehicle?: {
        score: number;
        type: string;
      };
    }>;
  }

• src/tools/recognizePlateImage.ts:14-103 (registration)

  Registration call: server.tool('recognize-plate-image', ...) registers this tool with the MCP server.

  export function registerRecognizePlateImageTool(
    server: McpServer,
    getApiKey: () => string | null,
  ) {
    server.tool(
      "recognize-plate-image",
      "Recognize and extract license plate(s) from a vehicle image URL",
      {
        imageUrl: z
          .string()
          .url()
          .describe("Direct URL to an image of a vehicle's license plate"),
      },
      async ({ imageUrl }) => {
        if (!imageUrl) {
          return {
            content: [
              {
                type: "text",
                text: "❌ Plate recognition failed. Image URL is required.",
              },
            ],
          };
        }
        // POST request with body as imageUrl
        const apiKey = getApiKey();
        console.log(
          "apiKey recognizePlateImage",
          apiKey ? `***${apiKey.slice(-4)}` : "null",
        );
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "❌ API key not provided. Please ensure X-API-Key header is set.",
              },
            ],
          };
        }
  
        const CARSXE_API_BASE = "https://api.carsxe.com";
        const url = `${CARSXE_API_BASE}/platerecognition?key=${apiKey}&source=mcp`;
        let data: CarsXEPlateRecognitionResponse | null = null;
        try {
          const response = await fetch(url, {
            method: "POST",
            headers: { "Content-Type": "text/plain" },
            body: imageUrl,
          });
          if (!response.ok)
            throw new Error(`HTTP error! status: ${response.status}`);
          data = await response.json();
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `❌ Plate recognition failed. ${
                  error instanceof Error
                    ? error.message
                    : String(error) || "Unknown error."
                }`,
              },
            ],
          };
        }
        if (!data || !data.success) {
          return {
            content: [
              {
                type: "text",
                text: `❌ Plate recognition failed. ${
                  data?.message || "Unknown error."
                }`,
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text",
              text: formatPlateRecognitionResponse(data),
            },
          ],
        };
      },
    );
  }

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

  Registration invocation in MyMCP (Cloudflare Workers MCP Agent).

    registerRecognizePlateImageTool(this.server, getApiKey);
    registerGetLienTheftTool(this.server, getApiKey);
  }

• src/index.gcp.ts:59-61 (registration)

  Registration invocation in index.gcp.ts (Node.js HTTP server with streamable HTTP transport).

    registerRecognizePlateImageTool(server, getApiKey);
    registerGetLienTheftTool(server, getApiKey);
  }