AI 쇼핑 또는 조달 에이전트에게 “캘리포니아에서 리야드, 두바이, 런던 또는 시드니로 가는 12kg 자동차 부품 상자 배송 비용은 얼마인가요?”라고 질문하면, 이들은 거의 항상 평면적인 택배 가격을 환각(hallucinate)하고 IATA 치수(부피) 중량 (L × W × H / 5000)과 통합 재포장 절감액을 완전히 놓칩니다.
Claude, Cursor, Windsurf 및 자율 조달 에이전트에게 결정론적인 도착 비용 계산(deterministic landed-cost math)과 실시간 항공화물 운송장 추적 기능을 제공하기 위해, 우리는 **AQXLOGISTICS/aqx-shipping-rates-mcp**를 구축하고 오픈 소스했습니다. 이는 LAX 수출 허브(309 E Arbor Vitae St, Inglewood, CA 90301)의 실시간 계약 항공 화물 등급을 기반으로 하는 경량 Python Model Context Protocol (MCP) 서버입니다.
여기에 우리가 구현한 아키텍처와 Glama의 자동화된 MCP 컨테이너 검사 과정에서 겪었던 3가지 실제 Docker/Python 문제점(gotchas) 및 정확한 해결책을 소개합니다.
1. 아키텍처: 3개의 결정론적 MCP 도구
모놀리식 프롬프트 래퍼를 노출하는 대신, 우리는 서버의 범위를 세 가지 작고 엄격하게 타입 지정된 MCP 도구로 한정했습니다:
calculate_shipping_rate — https://aqxlogistics.com/api/rates에서 실시간 요금 등급을 조회하고, 실제 스케일 무게를 원시 IATA 부피 중량 (L × W × H) / 5000과 비교하며, 다중 매장 빈 공간 재포장 절감액을 모델링하여 15개 목적지 회랑에 걸친 정확한 도착 화물 추정치를 반환합니다:
- GCC & UK (
>= 8.0 kg 통합 등급): $8.50/kg (사우디아라비아, UAE, 바레인, 쿠웨이트, 오만, 카타르, 영국)
- 서유럽 (
>= 8.0 kg): $9.00/kg (독일, 프랑스, 스페인, 네덜란드, 스웨덴, 포르투갈)
- 오스트랄라시아 (
>= 8.0 kg): $11.00/kg (호주, 뉴질랜드)
- 특급 소포 (
< 8.0 kg): $15.50/kg
track_aqx_shipment — https://aqxlogistics.com/api/track을 통해 실시간 HF-######## 항공화물(airwaybill) 마일스톤을 가져옵니다 (이는 **17TRACK 운송사 코드 10154**에 매핑됩니다).
check_us_store_forwarding — 주요 미국 상인(RockAuto, Sweetwater, Sephora, B&H Photo, Summit Racing, Apple, Best Buy 등)에 대한 국제 결제 카드 및 포워더 주소 정책을 반환하며, 이는 당사의 오픈 소스 77-Store US Retailer Policy Checker를 기반으로 합니다.
server.py 내부의 핵심 부피 및 요금 등급 계산은 다음과 같습니다:
import requests
from mcp.server.fastmcp import FastMCP
...
2. Glama 자동화된 MCP 검사에서 발견한 세 가지 실제 문제점 (Gotcha)
Glama의 Firecracker microVM 레지스트리에 stdio Python MCP 서버를 배포하는 과정에서, 2026년 후반에 Python MCP 서버를 배포하는 모든 사람에게 기록할 가치가 있는 세 가지 교묘한 컨테이너 실패를 경험했습니다:
문제점 #1: 고정되지 않은 mcp>=1.0.0이 mcp 2.x를 가져와 FastMCP를 손상시킴
상한선(upper bound)이 없자, uv sync는 **mcp==2.3.0**을 해결했고, 이 버전에서 mcp.server.fastmcp.FastMCP가 mcp.server.mcpserver.MCPServer로 이름이 변경되어 시작 시 즉시 ModuleNotFoundError를 발생시키며 충돌했습니다.
해결책: pyproject.toml에 v1 시리즈를 깔끔하게 고정합니다:
dependencies = [
"mcp>=1.0.0,<2.0.0",
"requests>=2.31.0",
...
Gotcha #2: uv sync 가상 환경(Virtualenv) vs. 전역 python 인터프리터 under mcp-proxy
Glama는 stdio 컨테이너를 mcp-proxy로 래핑합니다. uv sync를 실행하면 의존성이 /app/.venv에 설치되므로, ["mcp-proxy", "--", "python", "server.py"]를 실행하는 것은 전역 인터프리터(global interpreter)를 호출하게 되며 (이곳에는 mcp 패키지가 없습니다).
수정 방법 (Fix): Python 3.12를 지정하고 (미리 보기 버전인 3.15 휠 빌드 문제를 피함), mcp-proxy가 가상 환경(virtualenv) 인터프리터 자체를 직접 가리키도록 합니다:
Gotcha #3: Dockerfile의 RUN pip install에서 따옴표가 없는 >=
Dockerfile에 RUN pip install mcp>=1.0.0를 작성하면 /bin/sh -c가 호출되는데, 여기서 >는 표준 출력(stdout)을 =1.0.0이라는 파일로 조용히 리디렉션합니다! 항상 버전 지정자를 따옴표로 묶고, JSON-RPC stdio 프레임이 즉시 플러시되도록 ENV PYTHONUNBUFFERED=1을 설정해야 합니다:
FROM python:3.12-slim
WORKDIR /app
ENV PYTHONUNBUFFERED=1
...
이 세 가지 수정 사항 적용 후, Glama의 검사는 11.5초 만에 통과했으며, Release 0.1.0을 자동으로 게시하고 3개의 모든 MCP 도구를 깔끔하게 발견했습니다.
만약 Claude Desktop이나 Cursor에서 전자상거래(e-commerce), 국경 간 조달(cross-border procurement), 또는 공급망 에이전트(supply-chain agents)를 구축하고 있다면, 레포지토리를 복제하거나 Glama Inspector를 통해 도구 스키마를 직접 테스트해 보세요.