freightlane

freightlane

freightlane is a thin local bridge to EuroCollis, a shipping service running corridors between Europe and Africa — Morocco in particular. Its hosted MCP server publishes the read-only logistics data behind the service's public pricing and tracking: the shippable item catalogue, supported routes and cities, price quotes from the same engine the website uses, live courier trips and storefronts, shipment tracking, and indicative customs estimates.

The bridge stores nothing and prices nothing itself. It serves the upstream server's tool list locally — exactly as captured from the live endpoint — and forwards each tool call upstream, returning the result untouched. There is deliberately no booking tool here: the upstream surface is read-only, and bookings are confirmed outside it.

Tools

• get_eurocollis_info — what EuroCollis is: the corridors it operates, its currency and deposit model, and where bookings are completed. No arguments.
• get_services — the shippable item catalogue with its pricing units. The item_id values here are what get_quote accepts in its items list. No arguments.
• get_prohibited_items — items that EuroCollis and Morocco/EU customs prohibit. Worth surfacing before any booking recommendation. No arguments.
• get_routes — every supported Europe ⇔ Africa corridor. Optional: origin_country and destination_country (ISO-3166 alpha-2) to scope the answer to one corridor with live trip volume.
• get_cities — supported pickup and delivery cities for one country (country, required, ISO-3166 alpha-2 such as MA or FR). Quote calls expect these exact names.
• get_quote — the authoritative price quote for a shipment. Required: origin_country, origin_city, destination_country, destination_city. Provide weight_kg for box/suitcase shipments or items for catalogue goods (each with a quantity, plus item_id or name from get_services); optional pickup_date (YYYY-MM-DD, defaults to today) and flex_days (search window after pickup, default 14). Prices come from the upstream engine — never re-compute them locally.
• search_couriers — live, verified couriers with upcoming trips on a corridor; demo accounts, unverified couriers and past departures are excluded upstream. Optional: origin_country, destination_country, from_date (YYYY-MM-DD, defaults to today) and limit.
• get_courier — the public profile for one courier (courier, required: storefront slug or courier id). No personal data is returned.
• get_storefront — a published courier storefront with its canonical URL and corridor pages. Optional: slug to pick one storefront, limit when listing; omit slug to list storefronts.
• track_shipment — public shipment status. Both reference (e.g. BK-XXXXXX) and delivery_city are required, as an anti-enumeration measure. No personal data is returned.
• estimate_customs — an indicative duty and VAT estimate. Required: destination_country and declared_value_eur; optional category. The estimate is not authoritative, and the disclaimer it returns should be rendered verbatim.
• convert_currency — convert an amount between EuroCollis-supported currencies using live MAD-based rates. Required: amount, from_currency, to_currency.

Configuration

• EUROCOLLIS_MCP_URL (optional) — override the upstream endpoint. Defaults to https://api.eurocollis.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• EUROCOLLIS_API_KEY (optional) — when set, its value is sent to the upstream on every request under the x-eurocollis-key header, the header name pinned by the upstream's registry record. When unset, no auth header is sent; the captured surface was read keyless. (This forwarding is a labelled reconstruction.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name freightlane), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with freightlane error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

npx @reneturcios/freightlane get_cities '{"country":"MA"}'
npx @reneturcios/freightlane get_quote '{"origin_country":"FR","origin_city":"Paris","destination_country":"MA","destination_city":"Casablanca","weight_kg":12.5}'
npx @reneturcios/freightlane get_routes
npx @reneturcios/freightlane --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/freightlane mcp

MCP client config:

{
  "mcpServers": {
    "freightlane": {
      "command": "npx",
      "args": ["-y", "@reneturcios/freightlane", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/freightlane
docker run --rm ghcr.io/cloudcorprecords/freightlane --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.