ShipSmart-MCP

独立的 MCP (Model Context Protocol) 服务器，通过简单的 HTTP 契约公开 ShipSmart 的物流工具（validate_address、get_quote_preview 等）。

它是平台中工具行为的唯一事实来源。ShipSmart-API（Python / FastAPI — RAG 和 LLM）和 ShipSmart-Orchestrator（Java / Spring Boot — 即将推出的 AI 功能）都会调用此服务器，而不是在进程内实现工具。

HTTP 契约

与 MCP tools/list 和 tools/call 语义兼容：每次调用返回 { success, content: [...], error? }，其中 content 是适合 LLM 使用的 {type, text} 块列表。

/docs 和 /redoc 仅在 APP_ENV != production 时挂载。

身份验证

如果服务器上设置了 MCP_API_KEY，则每个 POST /tools/* 请求都必须在 X-MCP-Api-Key 中发送匹配的值。如果 MCP_API_KEY 为空，则禁用身份验证（仅限本地开发）。GET / 和 GET /health 始终无需身份验证，以便健康检查和服务发现可以在没有共享密钥的情况下工作。

错误响应

验证和执行错误特意返回 HTTP 200 和 success=false，以便消费者可以将协议级故障 (4xx) 与工具级故障 (200 + success=false) 区分开来。

Related MCP server: DB2ST MCP

工具

工具委托给由 SHIPPING_PROVIDER 选择的可插拔 ShippingProvider 实现。

添加工具只需将新类放入 app/tools/ 并在 app/main.py 中注册即可。

提供程序启动行为

• SHIPPING_PROVIDER=mock（默认）在启动时会发出响亮的 WARNING，以免操作员对伪造数据感到惊讶。

• 在没有所有必需凭据的情况下选择真实承运商（ups/fedex/dhl/usps）会在启动时引发 ValueError。没有静默回退到 mock 的机制 — 错误配置会快速且明显地失败。

配置

所有设置均从环境变量（或本地开发的 .env）加载。有关完整列表和默认值，请参阅 .env.example。

本地运行

先决条件：Python 3.13+ 和 uv。

cp .env.example .env
# fill in credentials if you want real carrier integration; default is SHIPPING_PROVIDER=mock
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

冒烟测试：

curl -s http://localhost:8001/health
curl -s -X POST http://localhost:8001/tools/list
curl -s -X POST http://localhost:8001/tools/call \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "validate_address",
        "arguments": {
          "street": "123 Main St",
          "city":   "San Francisco",
          "state":  "CA",
          "zip_code": "94105"
        }
      }'

测试

uv run pytest

可观测性

RequestLoggingMiddleware (app/core/middleware.py) 处理每个请求的相关 ID：

• 从入站请求读取 X-Request-Id，如果不存在则生成一个 UUID 十六进制字符串。

• 读取 W3C traceparent，如果不存在或格式错误则生成一个新的。

• 在响应中回显这两个标头，以便调用者可以跨服务按 ID 进行 grep。

• 在 shipsmart_mcp.requests 记录器上为每个请求发出一条日志行：

GET /health → 200 (1.4ms) [a1b2c3...]

从上游服务传递 X-Request-Id，以将 ShipSmart-API → MCP → 承运商 API 的单个请求串联起来。

部署 (Render)

render.yaml 是定义已部署服务的 Render 蓝图：

• Python Web 服务，通过 pip install uv && uv sync 构建，通过 uvicorn app.main:app --host 0.0.0.0 --port $PORT 启动。

• /health 处的健康检查。

• MCP_API_KEY 设置为 sync: false — 在 Render 仪表板中设置一次，并为每个消费者的 SHIPSMART_MCP_API_KEY 使用相同的值。

• 默认 SHIPPING_PROVIDER=fedex 指向 https://apis-sandbox.fedex.com（FedEx 沙盒，非生产环境）。在提升到实时承运商流量时覆盖基础 URL。

• CORS 来源在蓝图中固定为已部署的消费者 URL。

通过将 Render 指向此存储库进行配置；所有 sync: false 环境变量必须在第一次部署成功之前填写。

消费者

• ShipSmart-API（Python / FastAPI；在 Render 上部署为 shipsmart-api-python）：将 SHIPSMART_MCP_URL 指向此服务器，并从其编排和顾问服务中调用 /tools/list + /tools/call。

• ShipSmart-Orchestrator（Java / Spring Boot；在 Render 上部署为 shipsmart-api-java）：将从其即将推出的 AI 辅助流程中调用相同的 HTTP 契约。Java 代码库中不包含任何工具逻辑。

这保持了工具层的集中化 — 添加一次工具，每个服务都可以使用它。