shipment_summary

Instructions

Implementation Reference

• src/tools.ts:526-584 (handler)

  The handler for the 'shipment_summary' tool. It defines the ToolDef object with name, description, schema (Zod validation), annotations, and the handler function that maps snake_case args to camelCase and POSTs to 'shipment/summary' API endpoint.

  const shipmentSummary: ToolDef = {
    name: 'shipment_summary',
    description: `Composite endpoint — chains CBM, weight, LDM/volumetric/W&M, ADR compliance, and UK duty estimation into one response.
  
  The flagship composite tool. Accepts multiple items with a transport mode and returns comprehensive calculations. Road mode includes LDM, pallet spaces, and vehicle suggestion. Air mode includes volumetric weight. Sea mode includes revenue tonnes and container suggestion. All modes include ADR compliance checks and UK duty estimates when HS codes and customs values are provided.
  
  Use this tool when you need a complete shipment analysis in one call.`,
  
    schema: z.object({
      mode: z.enum(['road', 'air', 'sea', 'multimodal']).describe('Transport mode'),
      items: z.array(z.object({
        description: z.string().optional(),
        length: z.number().positive().describe('Length in cm'),
        width: z.number().positive().describe('Width in cm'),
        height: z.number().positive().describe('Height in cm'),
        weight: z.number().describe('Gross weight per item in kg'),
        quantity: z.number().int().positive().describe('Number of items'),
        stackable: z.boolean().optional().describe('Whether this item can be stacked (affects pallet fitting calc)'),
        pallet_type: z.enum(['euro', 'uk', 'us', 'custom', 'none']).optional().describe('Pallet standard the item sits on, if any'),
        hs_code: z.string().optional().describe('HS code for customs'),
        un_number: z.string().optional().describe('UN number for dangerous goods'),
        customs_value: z.number().optional().describe('Customs value per item in GBP'),
      })).describe('Array of shipment items with dimensions, weight, and optional HS/UN codes'),
      origin: z.object({ country: z.string(), locode: z.string().optional() }).optional().describe('Origin location — ISO country code and optional UN/LOCODE'),
      destination: z.object({ country: z.string(), locode: z.string().optional() }).optional().describe('Destination location — ISO country code and optional UN/LOCODE'),
      incoterm: z.string().optional().describe("Incoterms 2020 three-letter code (e.g. 'DAP', 'EXW', 'FOB')"),
      freight_cost: z.number().optional().describe('Optional freight cost in GBP for duty calculation'),
      insurance_cost: z.number().optional().describe('Optional insurance cost in GBP for duty calculation'),
    }).strict(),
  
    annotations: readOnlyAnnotations('Shipment Summary'),
  
    // The /api/shipment/summary input parser only recognises camelCase aliases
    // on freightCost / insuranceCost / items[].palletType / items[].hsCode /
    // items[].unNumber / items[].customsValue. Map snake_case → camelCase on
    // the wire until the website's input parser adds snake_case aliases.
    handler: async (args) =>
      apiPost('shipment/summary', {
        mode: args.mode,
        items: (args.items as Array<Record<string, unknown>>).map((i) => ({
          description: i.description,
          length: i.length,
          width: i.width,
          height: i.height,
          weight: i.weight,
          quantity: i.quantity,
          stackable: i.stackable,
          palletType: i.pallet_type,
          hsCode: i.hs_code,
          unNumber: i.un_number,
          customsValue: i.customs_value,
        })),
        origin: args.origin,
        destination: args.destination,
        incoterm: args.incoterm,
        freightCost: args.freight_cost,
        insuranceCost: args.insurance_cost,
      }),
  };

• src/tools.ts:534-554 (schema)

  Zod schema defining the input validation for the shipment_summary tool: mode (transport mode enum), items array (dimensions, weight, quantity, optional stackable/pallet_type/hs_code/un_number/customs_value), origin/destination (country + optional locode), incoterm, freight_cost, insurance_cost.

  schema: z.object({
    mode: z.enum(['road', 'air', 'sea', 'multimodal']).describe('Transport mode'),
    items: z.array(z.object({
      description: z.string().optional(),
      length: z.number().positive().describe('Length in cm'),
      width: z.number().positive().describe('Width in cm'),
      height: z.number().positive().describe('Height in cm'),
      weight: z.number().describe('Gross weight per item in kg'),
      quantity: z.number().int().positive().describe('Number of items'),
      stackable: z.boolean().optional().describe('Whether this item can be stacked (affects pallet fitting calc)'),
      pallet_type: z.enum(['euro', 'uk', 'us', 'custom', 'none']).optional().describe('Pallet standard the item sits on, if any'),
      hs_code: z.string().optional().describe('HS code for customs'),
      un_number: z.string().optional().describe('UN number for dangerous goods'),
      customs_value: z.number().optional().describe('Customs value per item in GBP'),
    })).describe('Array of shipment items with dimensions, weight, and optional HS/UN codes'),
    origin: z.object({ country: z.string(), locode: z.string().optional() }).optional().describe('Origin location — ISO country code and optional UN/LOCODE'),
    destination: z.object({ country: z.string(), locode: z.string().optional() }).optional().describe('Destination location — ISO country code and optional UN/LOCODE'),
    incoterm: z.string().optional().describe("Incoterms 2020 three-letter code (e.g. 'DAP', 'EXW', 'FOB')"),
    freight_cost: z.number().optional().describe('Optional freight cost in GBP for duty calculation'),
    insurance_cost: z.number().optional().describe('Optional insurance cost in GBP for duty calculation'),
  }).strict(),

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

  The ALL_TOOLS array where shipmentSummary is listed (line 729), which is then iterated over in server.ts to register each 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/server.ts:18-42 (registration)

  The server.ts registration loop that calls server.tool(...) for each ToolDef in ALL_TOOLS, including shipment_summary.

  // Register every tool
  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/tools.ts:26-39 (helper)

  The readOnlyAnnotations helper and ToolDef interface used by the shipment_summary tool definition.

  // Every FreightUtils tool is a pure, read-only lookup or deterministic
  // calculation. This helper keeps the annotations consistent.
  const readOnlyAnnotations = (title: string): ToolAnnotationShape => ({
    title,
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false,
  });
  
  
  // ─────────────────────────────────────────────────────────────
  //  1. CBM Calculator
  // ─────────────────────────────────────────────────────────────