decode-obd-code

Instructions

Implementation Reference

• src/tools/decodeObdCode.ts:7-65 (handler)

  Main handler function for the 'decode-obd-code' tool. Registers the tool on the McpServer with a Zod schema accepting a 'code' string. The handler validates the API key, calls carsxeApiRequest to the 'obdcodesdecoder' endpoint, and formats the response using formatObdCodeResponse.

  export function registerDecodeObdCodeTool(
    server: McpServer,
    getApiKey: () => string | null,
  ) {
    server.tool(
      "decode-obd-code",
      "Decode an OBD code and get diagnosis information",
      {
        code: z.string().describe("OBD code to decode (e.g., P0115)"),
      },
      async ({ code }) => {
        if (!code) {
          return {
            content: [
              {
                type: "text",
                text: "❌ OBD code lookup failed. Code is required.",
              },
            ],
          };
        }
        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<CarsXEObdCodeResponse>(
          "obdcodesdecoder",
          { code },
          apiKey,
        )) as CarsXEObdCodeResponse;
        if (!data || !data.success) {
          return {
            content: [
              {
                type: "text",
                text: `❌ OBD code lookup failed.`,
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text",
              text: formatObdCodeResponse(data),
            },
          ],
        };
      },
    );
  }

• src/tools/decodeObdCode.ts:11-16 (schema)

  Input schema for the 'decode-obd-code' tool: a single required 'code' string (the OBD code like P0115).

  server.tool(
    "decode-obd-code",
    "Decode an OBD code and get diagnosis information",
    {
      code: z.string().describe("OBD code to decode (e.g., P0115)"),
    },

• src/types/carsxe.ts:298-303 (schema)

  Type definition for CarsXEObdCodeResponse interface with success, diagnosis, date, and code fields.

  export interface CarsXEObdCodeResponse {
    success: boolean;
    diagnosis?: string;
    date?: string;
    code?: string;
  }

• src/formatters/formatObdCodeResponse.ts:1-15 (helper)

  Formats the OBD code API response into a human-readable string with code, diagnosis, and date.

  export function formatObdCodeResponse(
    data: import("../types/carsxe.js").CarsXEObdCodeResponse,
  ): string {
    if (!data.success) {
      return `❌ OBD code lookup failed.`;
    }
    return [
      `### 🛠️ OBD Code Diagnosis`,
      data.code ? `**Code:** ${data.code}` : undefined,
      data.diagnosis ? `**Diagnosis:** ${data.diagnosis}` : undefined,
      data.date ? `**Date:** ${data.date.split("T")[0]}` : undefined,
    ]
      .filter(Boolean)
      .join("\n");
  }

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

  Generic API request helper that calls the CarsXE API. Used by the handler to call the 'obdcodesdecoder' endpoint.

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