cbm_calculator

Instructions

Implementation Reference

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

  The cbm_calculator tool definition including its handler function. The handler calls apiGet('cbm', ...) with the input dimensions converted to short param names (l, w, h, pcs). This is the primary implementation of the tool logic.

  const cbmCalculator: ToolDef = {
    name: 'cbm_calculator',
    description: `Calculate cubic metres (CBM) for a shipment.
  
  CBM is the standard volume unit in international shipping. One CBM = 1m x 1m x 1m = 1,000 litres. Ocean freight carriers price per "freight tonne" (1 CBM or 1,000 kg, whichever is greater).
  
  Use this tool when you need to:
  - Calculate the volume of a shipment for sea freight quoting
  - Convert dimensions to CBM, cubic feet, or litres
  - Determine freight tonnes for ocean shipping
  
  Input dimensions in centimetres. Specify pieces to get total volume for multiple identical items.`,
  
    schema: z.object({
      length_cm: z.number().positive().describe('Length in centimetres'),
      width_cm: z.number().positive().describe('Width in centimetres'),
      height_cm: z.number().positive().describe('Height in centimetres'),
      pieces: z.number().int().positive().optional().describe('Number of identical pieces (default: 1)'),
    }).strict(),
  
    annotations: readOnlyAnnotations('CBM Calculator'),
  
    handler: async (args) =>
      apiGet('cbm', { l: args.length_cm, w: args.width_cm, h: args.height_cm, pcs: args.pieces }),
  };

• src/tools.ts:54-59 (schema)

  Input schema for cbm_calculator defined via Zod: requires positive numbers for length_cm, width_cm, height_cm, and an optional positive integer for pieces.

  schema: z.object({
    length_cm: z.number().positive().describe('Length in centimetres'),
    width_cm: z.number().positive().describe('Width in centimetres'),
    height_cm: z.number().positive().describe('Height in centimetres'),
    pieces: z.number().int().positive().optional().describe('Number of identical pieces (default: 1)'),
  }).strict(),

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

  The ALL_TOOLS array where cbmCalculator is registered as the first exported tool. This array is iterated over in server.ts to register the tool with the MCP server.

  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/tools.ts:61-61 (helper)

  Uses the readOnlyAnnotations('CBM Calculator') helper to mark the tool as read-only, idempotent, and non-destructive.

  annotations: readOnlyAnnotations('CBM Calculator'),

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

  The apiGet helper function that the handler delegates to. It makes an HTTP GET request to the FreightUtils API at /api/cbm with the query parameters.

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