freightlane

freightlane

freightlane は、ヨーロッパとアフリカ、特にモロッコ間の輸送ルートを運行する配送サービス EuroCollis への、薄型のローカルブリッジです。ホスト型 MCP サーバーは、サービスの公開料金情報と追跡機能を支える読み取り専用の物流データを公開します。これには、配送可能な品目カタログ、対応ルートと都市、ウェブサイトと同じエンジンが算出する料金見積もり、運行中の配達員の移動情報とストアフロント、配送状況の追跡、概算の通関費用が含まれます。

このブリッジは何も保存せず、料金も独自に計算しません。上流サーバーのツール一覧を、ライブエンドポイントから取得したそのままの形でローカルに提供し、各ツール呼び出しを上流に転送して、結果に手を加えずに返します。ここに予約ツールは意図的にありません。上流の機能は読み取り専用であり、予約はその外部で確定します。

ツール

• get_eurocollis_info — EuroCollis についての情報を取得します。運行ルート、通貨とデポジットの仕組み、予約の完了場所を確認できます。引数はありません。
• get_services — 料金単位を含む、配送可能な品目カタログを取得します。ここにある item_id の値は、get_quote の items リストで指定します。引数はありません。
• get_prohibited_items — EuroCollis およびモロッコ／EUの税関が禁止している品目を取得します。予約を推奨する前に提示しておくとよい情報です。引数はありません。
• get_routes — 対応しているヨーロッパ ⇔ アフリカ間のすべてのルートを取得します。オプション：origin_country と destination_country（ISO-3166 alpha-2）。指定すると、運行中の移動件数がある1つのルートに回答を絞り込めます。
• get_cities — 1か国の対応する集荷都市と配達都市を取得します（country は必須。MA や FR などのISO-3166 alpha-2）。見積もりでは、これらの正確な名称を指定する必要があります。
• get_quote — 配送の正式な料金見積もりを取得します。必須：origin_country、origin_city、destination_country、destination_city。箱／スーツケースでの配送では weight_kg を、カタログ商品では items（各項目に quantity と、get_services にある item_id または name）を指定します。オプション：pickup_date（YYYY-MM-DD。既定値は今日）と flex_days（集荷後の検索期間。既定値は14日間）。料金は上流エンジンから取得します。ローカルで再計算しないでください。
• search_couriers — ルート上で今後の移動予定がある、現在有効で確認済みの配達員を取得します。デモアカウント、未確認の配達員、出発済みの便は上流で除外されます。オプション：origin_country、destination_country、from_date（YYYY-MM-DD。既定値は今日）、limit。
• get_courier — 1人の配達員の公開プロフィールを取得します（courier は必須。ストアフロントのスラッグまたは配達員ID）。個人データは返されません。
• get_storefront — 公開済みの配達員ストアフロントを、正規URLとルートページとともに取得します。オプション：ストアフロントを1つ選択する slug、一覧表示時の limit。ストアフロントを一覧表示するには slug を省略します。
• track_shipment — 公開されている配送状況を取得します。列挙攻撃を防ぐため、reference（例：BK-XXXXXX）と delivery_city の両方が必須です。個人データは返されません。
• estimate_customs — 関税とVATの概算を取得します。必須：destination_country と declared_value_eur。オプション：category。この概算は確定的なものではなく、返される免責事項はそのまま表示してください。
• convert_currency — ライブのMAD基準為替レートを使って、EuroCollis が対応する通貨間で金額を換算します。必須：amount、from_currency、to_currency。

設定

• EUROCOLLIS_MCP_URL（オプション） — 上流エンドポイントを上書きします。既定値は https://api.eurocollis.com/mcp です。（この上書き用フックは、この再構築で独自に付加したことを明示しています。）
• EUROCOLLIS_API_KEY（オプション） — 設定すると、その値が上流へのすべてのリクエストで x-eurocollis-key ヘッダーに送信されます。このヘッダー名は上流のレジストリレコードで指定されています。未設定の場合、認証ヘッダーは送信されません。取得した機能一覧はキーなしで読み取られました。（この転送は、独自に付加したことを明示しています。）

転送の仕組み

最初のツール呼び出しで、クライアントはアップストリームとのストリーミング可能な HTTP セッションを開始します。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、 clientInfo name freightlane）に続いて、 notifications/initialized 通知、さらに呼び出し元の引数を 変更せずに格納した tools/call リクエストを送信します。アップストリームが Mcp-Session-Id ヘッダーを付けて initialize に応答すると、その値は セッションの後続のすべてのリクエストに付与され、プロセスの存続中 再利用されます。応答はプレーンな JSON またはサーバー送信イベントで 届く場合があり、どちらも読み取ります。

アップストリームからの成功結果は、アップストリームが設定した isError フラグも含め、 そのまま渡されます。JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、完了できないリクエストなどの失敗は、 テキストが freightlane error: で始まる isError 結果として 返されます（この表現は、この再構築で独自に付けたラベルです）。

CLI

各ツールはサブコマンドとしても実行でき、JSON 引数文字列を 1 つ指定します （引数が不要なツールでは省略します）。

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

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/freightlane mcp

MCP クライアントの設定：

{
  "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

コンテナのデフォルトコマンドは mcp です。そのため、最初の形式では stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化した JSON-RPC アップストリームを対象に実行されます。実際のネットワーク呼び出しは行いません。

ライセンス

MIT — LICENSE を参照してください。