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コントラクト

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 は常に認証不要であり、共有シークレットなしでヘルスチェックとサービスディスカバリが機能するように設計されています。

エラーレスポンス

検証エラーや実行エラーは、コンシューマーがプロトコルレベルの失敗（4xx）とツールレベルの失敗（200 + success=false）を区別できるように、意図的にHTTP 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 が発生します。モックへのサイレントフォールバックは存在しません。設定ミスは迅速かつ目に見える形で失敗します。

設定

すべての設定は環境変数（またはローカル開発用の .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の16進数を生成します。

• W3C traceparent を読み取るか、存在しない、または不正な場合は新しく生成します。

• 呼び出し元がサービス間でIDによって grep できるように、レスポンスで両方のヘッダーをエコーバックします。

• shipsmart_mcp.requests ロガーでリクエストごとに1行のログを出力します。

  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コードベースにはツールロジックは含まれません。

これにより、ツールレイヤーが一元化され、ツールを一度追加すればすべてのサービスがそれを利用できるようになります。