freightlane

freightlane

freightlane 是一个连接到 EuroCollis 的轻量本地桥接服务。EuroCollis 是一家提供欧洲与非洲（尤其是摩洛哥）间运输线路的服务商。其托管的 MCP 服务公开了该服务公共定价和追踪功能背后的只读物流数据：可运输物品目录、支持的线路和城市、由网站使用的同一引擎生成的报价、实时承运人行程和店面、货件追踪，以及参考性海关费用估算。

该桥接服务不存储任何数据，也不自行计算价格。它在本地提供上游服务的工具列表——与从实时端点捕获的内容完全一致——并将每次工具调用转发到上游，原样返回结果。这里刻意不提供预订工具：上游接口是只读的，预订需在其外部确认。

工具

• get_eurocollis_info — 介绍 EuroCollis：其运营线路、货币和押金模式，以及完成预订的地点。不需要参数。
• get_services — 可运输物品目录及其计价单位。此处的 item_id 值可用于 get_quote 的 items 列表。不需要参数。
• get_prohibited_items — EuroCollis 和摩洛哥／欧盟海关禁止运输的物品。在提供任何预订建议前，值得先说明这些信息。不需要参数。
• get_routes — 所有受支持的欧洲 ⇔ 非洲线路。可选参数：origin_country 和 destination_country（ISO-3166 alpha-2），用于查询单条线路及其实时行程量。
• get_cities — 某个国家支持的取件和配送城市（必填参数 country，使用 ISO-3166 alpha-2 格式，例如 MA 或 FR）。报价调用必须使用这些确切名称。
• 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 — 某位承运人的公开资料（必填参数 courier：店面 slug 或承运人 ID）。不会返回个人数据。
• get_storefront — 已发布承运人店面的规范 URL 和线路页面。可选参数：slug 用于选择某个店面，limit 用于设置列表上限；省略 slug 即可列出所有店面。
• track_shipment — 查询公开货件状态。必须同时提供 reference（例如 BK-XXXXXX）和 delivery_city，以防止枚举查询。不会返回个人数据。
• estimate_customs — 估算关税和增值税，仅供参考。必填参数：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 请求。上游在响应 initialize 时若返回 Mcp-Session-Id 标头，该值便会随会话中的 后续每个请求一同发送；此会话会在进程运行期间复用。 响应可能是普通 JSON，也可能是服务器发送事件；两种格式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标记。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取响应，或 无法完成的请求——会作为 isError 结果返回，其文本以 freightlane error: 开头（此呈现方式是本次重建自行标注的复原结果）。

CLI

每个工具也都是一个子命令，接受一个 JSON 参数字符串（不需要参数的工具可省略）：

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。