수입 소싱 어드바이저(Import Sourcing Advisor)

우크라이나를 위한 거시적 수입 소싱 스크리닝을 위한 도메인 특화 데이터 에이전트입니다. 어떤 국가에서 어떤 제품군을 소싱해야 하는지 질문하면, 에이전트가 공개 무역 데이터를 통해 질문을 처리합니다: 어떤 원산지가 실제로 공급하는지, 공급이 얼마나 집중되어 있는지, 각 후보의 착지 비용(landed cost)은 얼마인지, 후보들이 서로 어떻게 순위가 매겨지는지.

에이전트는 두 개의 MCP 연결을 통해 확장됩니다:

모든 것은 기밀 입력이 없는 공개 데이터로 실행되며, 커스텀 서버는 어떤 종류의 API 자격 증명도 필요로 하지 않습니다.

가장 먼저 보게 되는 것

채팅 창이 아닌 작업 목록(worklist)입니다. 추적 중인 6개 수입 품목이 각각 한 행씩, 위험 등급과 금액 순으로 정렬되어 있습니다: 주요 공급업체, 점유율, 그 점유율의 가치, 그 뒤에 있는 유효 원산지 수, 그리고 한 단어 상태 표시. 행을 펼치면 해당 위치에서 원산지 세부 정보가 확장되며, 에이전트 실행은 그 지점에서 의도적인 작업입니다.

목록 위에는 집계 수치 스트립이 있습니다. 현재 창 기준: 5억 5,400만 USD 수입, 그중 3억 4,600만이 품목당 단일 원산지에 집중(62%), 튀르키예가 6개 품목 중 3개를 선도 — 노출액 1억 8,300만. 마지막 수치는 어떤 제품별 보고서도 보여줄 수 없는 수치입니다: 함께 실패할 품목들입니다.

목록은 추론이 아닌 계산으로 생성됩니다. web/portfolio.py는 에이전트가 사용하는 동일한 커스텀 서버에 MCP stdio 세션 하나를 열고, 모델 개입 없이 도구를 직접 호출합니다. 방문자가 처음 로드하는 화면은 에이전트를 기다리거나 비용이 들지 않아야 합니다.

통화(Currency). 연간 무역 시계열은 약 2년 정도 지연되므로, 목록은 월별 보고서로 구축된 12개월 이동 창으로 실행되며, 소스가 실제로 게시한 달까지 종료됩니다 — 현재 2024년 10월 ~ 2025년 9월, 최신 완전 연간 연도보다 약 11개월 앞섭니다. 이는 미관상의 문제가 아닙니다: 2024년 연간 데이터에서는 신선 토마토가 71.8% 튀르키예산으로 읽히며 단일 소스 플래그가 붙었지만, 이동 창에서는 64.6%로 읽히며 플래그가 붙지 않습니다.

Related MCP server: supply-chain-mcp-server

사전 요구 사항

세 가지 데이터 API 중 어느 것에도 키, 토큰 또는 계정이 필요하지 않습니다.

설치

git clone <repository-url> logistics_mcp
cd logistics_mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

브라우저 서버와 Chromium 빌드를 한 번 설치합니다 (PATH에 Node 18+ 필요):

npm install
npx -y playwright install chromium

npm install은 @playwright/mcp를 고정하며, 에이전트는 이후 이를 node node_modules/@playwright/mcp/cli.js로 시작합니다. npx를 거치지 않습니다: Windows에는 npx라는 실행 파일이 없고, Node는 셸 없이 npx.cmd를 생성(spawn)하기를 거부하므로, 해당 이름으로 서버를 실행하면 조용히 실패했습니다 — 실행은 계속되었고 모델은 브라우저 도구가 없다고 보고했습니다. npm install이 없으면 에이전트는 npx -y @playwright/mcp@latest로 대체되며, POSIX 셸이 이를 해석할 수 있는 환경에서 작동합니다.

구성

cp .env.example .env

.env는 git-ignore됩니다. 커스텀 MCP 서버에 필수인 것은 없으며, 값들은 에이전트와 데이터 전송 모드에만 영향을 줍니다.

구성 요소를 독립적으로 실행하기

커스텀 MCP 서버는 별도 프로세스이며 자체적으로 시작됩니다. 에이전트와는 아무런 의존 관계가 없습니다.

1. 커스텀 MCP 서버

python -m mcp_server.server

stdio를 통해 MCP를 제공하며 시작 시 전송 방식과 데이터 모드를 stderr로 출력합니다. 에이전트 없이 게시된 계약(contract)을 검사하려면:

python scripts/inspect_tools.py           # summary of all five tool contracts
python scripts/inspect_tools.py --json    # full input and output JSON schemas

또는 공식 인스펙터로 구동:

npx -y @modelcontextprotocol/inspector python -m mcp_server.server

2. Playwright MCP 서버

에이전트가 직접 생성(spawn)합니다. 검사 목적으로만 수동 실행하세요.

node node_modules/@playwright/mcp/cli.js --headless --isolated

3. 에이전트 및 웹 애플리케이션

python -m web.app          # serves http://127.0.0.1:8000

웹 앱은 두 MCP 연결을 자식 프로세스로 실행하고 각각이 노출한 도구를 표시합니다.

설치 확인

python -m pytest tests -q        # 47 unit tests, no network, ~2s
python scripts/smoke_tools.py    # calls every tool end to end against the live APIs
REPLAY=1 python scripts/smoke_tools.py   # the same run, offline, from fixtures
python scripts/run_e2e.py        # the whole agent flow, both MCP servers, live
python scripts/run_failure_demo.py       # the same flow with the browser server broken

run_e2e.py는 데모가 의존하는 검증입니다. 두 서버가 모두 연결되고 5개 전부의 커스텀 도구가 실제로 호출되지 않으면 실행을 실패시킵니다 — 커스텀 서버가 시작에 실패해도 모델이 단순히 도구가 없다고 보고하기 때문에 유창한 답변이 여전히 생성됩니다. 모든 이벤트는 scripts/last_e2e_trace.jsonl에 기록되어 실행을 신뢰에 맡기는 대신 사후에 검사할 수 있습니다. 전체 실행은 약 10분, 20턴, 약 $0.55입니다. 대체(fallback) 최신성 URL에서의 실패한 탐색(navigate)은 체인의 다른 페이지가 로드된 경우 허용됩니다 — 체인은 순서가 정해져 있고 에이전트는 답변하는 첫 페이지에서 멈춥니다 — 그러나 아무것도 로드되지 않은 체인과 커스텀 서버의 모든 오류는 여전히 실행을 실패시킵니다.

run_failure_demo.py는 나머지 절반입니다: 대체 경로 없이 브라우저를 해석 불가능한 호스트로 가리키고, 탐색이 오류로 보고되고 다른 어떤 것도 오류가 없으며, 실패한 검사가 명명된 권장 사항이 여전히 나올 때만 통과합니다. 요구 사항은 아무것도 실패하지 않는 것이 아니라 — 실패가 빈 답변과 구별 가능해야 한다는 것입니다.

오프라인 / 리플레이 모드

커스텀 서버는 세 개의 네트워크 API를 호출하므로, 실제 응답은 fixtures/ 아래에 기록되며 네트워크 접근 없이 리플레이할 수 있습니다:

# Offline
SOURCING_MODE=replay python -m mcp_server.server

# Re-record after changing a query
SOURCING_MODE=record python scripts/smoke_tools.py

대체는 전송 경계(mcp_server/sources/http.py)에서 발생합니다: 리플레이 는 네트워크가 반환한 것과 동일한 원시 JSON을 돌려주며, 그 위의 모든 파서, 중복 제거 단계 및 계산은 변경 없이 실행됩니다. 준비된 답변을 반환하는 코드 경로는 없습니다.

각 픽스처는 정확한 URL, 검색 타임스탬프 및 원문 응답 본문을 기록하는 봉투(envelope)입니다.

오프라인이 커버하는 것. 포트폴리오, 랜딩 화면에 표시되는 각 제품의 순위, 그리고 에이전트 흐름. 한 제품의 순위를 라이브와 리플레이로 각각 실행하고 모든 필드를 비교하여 검증했습니다: 소수점 마지막 자리까지 동일합니다. 이 검증은 유지할 가치가 있습니다 — 아래의 관세 버그가 발견된 방법이며, 순위 픽스처가 기록되기 전에는 오프라인 점수 붕괴가 발견된 방법이기도 합니다.

커버하지 않는 것. 참조 창은 하나만 기록되어 있으므로(2024년 10월 – 2025년 9월), 다른 후행 창에 대한 요청은 대체 없이 오프라인에서 실패합니다. 두 제품은 두 모드 모두에서 가격을 책정할 수 없는 후보를 보유합니다 — 아몬드의 USA와 NLD, 키위프루트의 AZE는 중량을 보고하지 않아 파생할 단위 가치가 없습니다. 해당 행은 화면에서 불완전으로 표시되고 주의 사항에 명명됩니다. 이는 기록의 공백이 아니라 소스의 공백입니다.

데이터 소스

검증된 엔드포인트 동작, 속도 제한 및 특이 사항은 docs/01-data-sources-verified.md에 문서화되어 있습니다.

저장소 구조

mcp_server/          Custom MCP server (separate process)
  server.py          Five tool registrations, stdio entry point
  models.py          Pydantic input/output contracts
  sources/           http (rate limit, cache, fixtures), comtrade, worldbank, wits, reference
  domain/            costing and analysis calculations
agent/               Claude Agent SDK wiring, two model tiers, trace events
web/                 FastAPI application, portfolio over MCP, single-page UI
  app.py             Endpoints: portfolio, commodity detail, agent run, chat
  portfolio.py       The tracked lines, queried over an MCP stdio session
  index.html         Portfolio screen, line detail, MCP trace, chat panel
data/reference/      Vendored HS2022 and country reference data
fixtures/            Recorded genuine API responses for replay mode
scripts/             inspect_tools, smoke_tools, run_e2e
tests/               Unit tests
docs/                Requirements digest, verified sources, contracts, rationale, demo script

문서

알려진 제한 사항

• 운임 비용은 견적이 아닌 모델링된 값입니다. 오픈 소스 중 운임 요금을 공개하는 곳은 없습니다. 모델링된 모든 수치는 도구 출력에서 estimated로 표시됩니다.

• 관세는 MFN 세율입니다. WITS는 특혜 관세율에 대해 HTTP 404를 반환하므로 EU DCFTA와 같은 협정은 가능한 것으로 표시되지만 적용되지는 않습니다.

• 연간 시계열은 약 2년 정도 시차가 있습니다. 2026년 8월 기준으로 우크라이나는 2024년까지 보고했으며 2025년은 아직입니다. 월간 시계열은 2025년 9월까지이며, 작업 목록에서 사용하는 기준입니다. 관부가비용 및 순위 도구는 여전히 연간 기준으로 실행되며, 관세는 다시 이전 관측치에서 가져옵니다. 각 결과는 사용된 기준을 명시합니다.

• 단위 가치는 가격이 아닙니다. Comtrade 단위 가치는 총중량 대비 총가치이지 견적이 아닙니다.

• 물류 성과 지수는 연간 시계열이 아닙니다. 2022년이 최신 관측치입니다.

• 세관 페이지는 자동화된 클라이언트를 차단합니다. customs.gov.ua는 사람의 브라우저가 아닌 모든 요청에 대해 Akamai 엣지에서 HTTP 403을 반환하지만, 사람이 접속하면 정상적으로 열립니다. 따라서 최신성 단계는 중앙은행의 대외 부문 페이지로 대체되며, 에이전트는 실제로 읽은 페이지를 명시합니다. 이를 통해 게시 시점은 확인할 수 있지만 매출액 수치는 확인할 수 없으므로, 최신성 확인은 우연이 아닌 설계상 부분적으로만 수행됩니다.

• 포트폴리오는 신호를 위해 선택된 6개 품목입니다. 사과(HS 080810, $0.5M)와 호두(HS 080231, 거의 0)는 제외되었습니다. 우크라이나는 이 두 품목을 모두 재배하고 수출하므로 수입 품목으로는 노이즈에 불과하기 때문입니다.

• 이것은 스크리닝 도구입니다. 조사할 가치가 있는 국가 목록을 좁혀 주는 도구이지, 입찰을 대체하지는 않습니다.