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 契约

方法	路径	用途
GET	`/`	服务发现（名称、版本、工具数量、端点）。
GET	`/health`	Render 使用的存活探针。
POST	`/tools/list`	返回所有已注册工具的模式。
POST	`/tools/call`	使用提供的参数按名称执行工具。

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

认证

如果服务器上设置了 MCP_API_KEY，则每个 POST /tools/* 请求都必须在 X-MCP-Api-Key 中发送匹配的值。如果 MCP_API_KEY 为空，则禁用认证（仅限本地开发）。

工具

名称	描述
`validate_address`	通过配置的承运商验证并标准化收货地址。
`get_quote_preview`	包裹的非约束性运费预览。最终费率来自 Java API。

工具委托给由 SHIPPING_PROVIDER 选择的可插拔 ShippingProvider 实现（mock、ups、fedex、dhl、usps）。添加工具只需将新类放入 app/tools/ 并在 app/main.py 中注册即可。

本地运行

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

使用者

ShipSmart-API (Python/FastAPI)：将 SHIPSMART_MCP_URL 指向已部署的服务器，并从其编排和顾问服务中调用 /tools/list + /tools/call。
ShipSmart-Orchestrator (Java/Spring Boot)：将从其即将推出的 AI 辅助流程中调用相同的 HTTP 契约。Java 代码库中不包含任何工具逻辑。

这保持了工具层的集中化——添加一次工具，所有服务都能使用。