ShipSmart-MCP

ShipSmartの配送ツール（validate_address、get_quote_previewなど）をシンプルなHTTPコントラクト経由で公開する、スタンドアロンのMCP（Model Context Protocol）サーバーです。

これは、プラットフォーム全体におけるツール動作の唯一の信頼源です。ShipSmart-API（Python / FastAPI — RAGおよびLLM）とShipSmart-Orchestrator（Java / Spring Boot — 今後のAI機能）の両方は、プロセス内でツールを実装する代わりに、このサーバーを呼び出します。

HTTPコントラクト

メソッド	パス	目的
GET	`/`	サービスディスカバリ（名前、バージョン、ツール数、エンドポイント）。
GET	`/health`	Renderで使用される生存確認（Liveness probe）。
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コードベースにはツールロジックは含まれません。

これにより、ツール層が一元化され、ツールを一度追加すればすべてのサービスで利用可能になります。