soap

Posted on Apr 29 • Originally published at dev.to

Migrating to freightutils-mcp v2.0.0: snake_case across every surface

#mcp #ai #api #freight

I shipped v2.0.0 of freightutils-mcp on 25 April. It's a breaking change with one purpose: one canonical input schema across the npm package, the n8n node, the Zapier app, and the HTTP MCP endpoint at freightutils.com/api/mcp.

If you're integrating against any of these, here's what you need to know.

Why snake_case

Response keys were already snake_case across the REST API. Input keys were polyglot — some camelCase, some snake_case, depending on which surface you hit. That asymmetry is fine when you're building one integration. It rots when you maintain four.

The fix is one canonical schema. Inputs and outputs both snake_case, across every surface. Agents you build against the npm package work identically against the HTTP MCP endpoint. n8n workflows port to Zapier with field-name parity.

What changed: 13 keys, 3 tools

Every other tool (cbm, ldm, chargeable_weight, the ADR family, airline, container, hs_code, incoterms, unlocode, uld, vehicle, pallet_fitting, unit_converter) was already snake-clean in v1.x. Only three tools had camelCase inputs:

uk_duty_calculator

Old	New
commodityCode	commodity_code
originCountry	origin_country
customsValue	customs_value
freightCost	freight_cost
insuranceCost	insurance_cost

consignment_calculator (items[] fields)

Old	New
grossWeight	gross_weight
palletType	pallet_type

shipment_summary

Old	New
freightCost	freight_cost
insuranceCost	insurance_cost
items[].palletType	items[].pallet_type
items[].hsCode	items[].hs_code
items[].unNumber	items[].un_number
items[].customsValue	items[].customs_value

How to migrate

Using the npm package

npm install freightutils-mcp@2.0.0

Update any agent or script calling the three affected tools. If you use TypeScript, the types now require snake_case — TS will tell you which call sites to fix.

Using the HTTP MCP endpoint

No install step. Update your tools/call arguments to snake_case for the three affected tools. Endpoint: https://www.freightutils.com/api/mcp

Using n8n

Update to n8n-nodes-freightutils@0.2.0. Fields renamed in the workflow UI:

Consignment item: grossWeight → gross_weight
Duty Calculator: commodityCode / originCountry / customsValue
ULD / Container / Vehicle lookup: *Type / *Category → snake_case
Convert: from → from_unit, to → to_unit

Using Zapier

Update to v0.2.0. Renamed user-input fields:

Consignment: grossWeight → gross_weight
UK Duty: commodityCode / originCountry / customsValue

Action-level keys ukDuty, chargeableWeight) are kept as-is to avoid breaking existing Zaps.

Why this matters for agent builders

If you're building an agent that needs landed-cost reasoning or shipment summary calculation, you can now write one schema-aware prompt and deploy through whichever channel fits the user. Same field names, same response shape, same canonical answer.

That's the whole point of the migration.

DEV Community