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는 항상 인증되지 않으므로 공유 비밀 키 없이도 상태 확인 및 서비스 검색이 작동합니다.

오류 응답

유효성 검사 및 실행 오류는 의도적으로 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 16진수를 생성합니다.

• W3C traceparent를 읽거나, 없거나 형식이 잘못된 경우 새로 생성합니다.

• 호출자가 서비스 전반에서 ID로 grep할 수 있도록 응답에 두 헤더를 모두 에코합니다.

• shipsmart_mcp.requests 로거에서 요청당 하나의 로그 라인을 출력합니다:

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

ShipSmart-API → MCP → 운송업체 API에 걸쳐 단일 요청을 연결하려면 업스트림 서비스에서 X-Request-Id를 전달하십시오.

배포 (Render)

render.yaml은 배포된 서비스를 정의하는 Render 블루프린트입니다:

• Python 웹 서비스, 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 코드베이스에는 도구 로직이 포함되지 않습니다.

이렇게 하면 도구 계층이 중앙 집중화되어 도구를 한 번 추가하면 모든 서비스가 이를 사용할 수 있습니다.