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에서 사용하는 활성 상태 프로브.
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 코드베이스에는 도구 로직이 포함되지 않습니다.

이를 통해 도구 계층을 중앙 집중화하여, 도구를 한 번만 추가하면 모든 서비스에서 사용할 수 있습니다.