airline_lookup

Instructions

Implementation Reference

• src/tools.ts:235-240 (handler)

  The handler function for airline_lookup. Calls apiGet('airlines', ...) passing query parameters (q, iata, icao, prefix, country) to the FreightUtils API.

    handler: async (args) =>
      apiGet('airlines', {
        q: args.query, iata: args.iata, icao: args.icao,
        prefix: args.prefix, country: args.country,
      }),
  };

• src/tools.ts:225-231 (schema)

  Zod schema defining the input parameters for airline_lookup: optional query (min 2 chars), iata (exactly 2 chars), icao (exactly 3 chars), prefix (exactly 3 digits), and country (min 2 chars). Uses .strict() to reject unknown keys.

  schema: z.object({
    query: z.string().min(2, 'Query must be at least 2 characters').optional().describe('General search (name, code, prefix, or country — min 2 chars)'),
    iata: z.string().length(2, 'IATA code must be exactly 2 characters').optional().describe('Exact IATA code (2 chars, e.g., "EK")'),
    icao: z.string().length(3, 'ICAO code must be exactly 3 characters').optional().describe('Exact ICAO code (3 chars, e.g., "UAE")'),
    prefix: z.string().regex(/^\d{3}$/, 'AWB prefix must be exactly 3 digits').optional().describe('AWB prefix (3 digits, e.g., "176")'),
    country: z.string().min(2, 'Country must be at least 2 characters').optional().describe('Filter by country name (min 2 chars)'),
  }).strict(),

• src/tools.ts:713-733 (registration)

  airlineLookup is listed in the ALL_TOOLS array (line 720), which is iterated over in server.ts (line 19-42) to register each tool with the MCP server via server.tool(...).

  export const ALL_TOOLS: ToolDef[] = [
    cbmCalculator,
    chargeableWeightCalculator,
    ldmCalculator,
    adrLookup,
    adrExemptionCalculator,
    adrLqEqCheck,
    airlineLookup,
    containerLookup,
    hsCodeLookup,
    incotermsLookup,
    palletFittingCalculator,
    unitConverter,
    consignmentCalculator,
    unlocodeLookup,
    ukDutyCalculator,
    shipmentSummary,
    uldLookup,
    vehicleLookup,
    getSubscribeLink,
  ];

• src/server.ts:19-42 (registration)

  The registration loop that iterates ALL_TOOLS and calls server.tool(...) for each, including airline_lookup, binding its name, description, schema, annotations, and handler.

  for (const tool of ALL_TOOLS) {
    server.tool(
      tool.name,
      tool.description,
      tool.schema.shape,
      tool.annotations,
      async (args: Record<string, unknown>) => {
        try {
          const result = await tool.handler(args);
          return {
            content: [
              { type: 'text' as const, text: JSON.stringify(result, null, 2) },
            ],
          };
        } catch (err: unknown) {
          const message = err instanceof Error ? err.message : String(err);
          return {
            content: [{ type: 'text' as const, text: `Error: ${message}` }],
            isError: true,
          };
        }
      },
    );
  }

• src/api.ts:7-39 (helper)

  The apiGet helper function used by the airline_lookup handler to make a GET request to the FreightUtils API.

  export async function apiGet(endpoint: string, params: Record<string, unknown>): Promise<unknown> {
    const url = new URL(`${BASE_URL}/${endpoint}`);
    for (const [k, v] of Object.entries(params)) {
      if (v === undefined || v === null || v === '') continue;
      url.searchParams.set(k, String(v));
    }
  
    const res = await fetch(url.toString(), {
      headers: { 'Accept': 'application/json' },
    });
  
    if (!res.ok) {
      const body = await res.text();
      throw new Error(`FreightUtils API error ${res.status}: ${body}`);
    }
  
    return res.json();
  }
  
  export async function apiPost(endpoint: string, body: unknown): Promise<unknown> {
    const res = await fetch(`${BASE_URL}/${endpoint}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
      body: JSON.stringify(body),
    });
  
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`FreightUtils API error ${res.status}: ${text}`);
    }
  
    return res.json();
  }