load-planner-mcp

결정론적 화물 계획 솔버와, 이를 두 가지 도구로 노출하는 MCP stdio 서버입니다. 솔버는 주문 코호트의 운송 모드(전량 항공, 통합 해상 LCL, 또는 전체 컨테이너)를 결정하고, 각 옵션의 가격을 산정하며, 위험 판독값(ETA 백분위수, 마감일 미준수 확률, 지연 꼬리의 CVaR)을 첨부합니다.

여기에 포함된 것

두 하위 문제는 병합되지 않고 계층화되어 있습니다. MILP 내부에서 실제 3D 배치를 해결하면 조합적으로 폭발하므로, 패커가 먼저 실행되고 CP-SAT에 적재율과 가능성 플래그를 전달합니다.

Related MCP server: freight-pulse

두 도구 계약

solve(problem)은 솔버를 실행하고 그 출력을 그대로 반환합니다 — 재포맷, 반올림, 요약 없이 — 결과의 result_id 및 SHA-256 content_hash와 함께. 결과는 프로세스 내 저장소에 보관됩니다.

explain(result_id)는 고정 템플릿에서 작성된 설명을 반환하며, 해당 저장된 결과에서 슬롯이 채워집니다.

분할이 설계입니다. 이 서버를 호출하는 언어 모델은 무엇을 해결할지 선택하고 답을 말로 표현합니다; 어떤 수치도 생성하지 않습니다. 세 가지 속성이 이를 이상적이 아닌 구조적으로 만듭니다:

1. explain은 불투명한 ID 하나만 받고 그 외에는 아무것도 받지 않습니다. 입력 스키마에는 단일 속성만 있습니다. 요금, 무게 또는 마감일을 전달할 수 없으므로 이를 다시 말할 수 없습니다.

2. 저장된 레코드는 솔버 결과만 보유합니다. solve는 솔버가 실행된 후 문제 페이로드를 폐기합니다. 저장된 레코드에는 입력 값을 전달할 수 있는 필드가 없습니다.

3. explain 경로에는 산술이 없습니다. 값은 키로 조회되고 문자열로 렌더링됩니다. 권장 카드를 선택하는 것은 솔버가 이미 설정한 플래그를 읽는 것입니다; 비교하거나 계산하지 않습니다.

verify_narration(narration, stored)은 주장을 검사로 전환합니다. 텍스트에서 숫자 연속을 스캔하고 저장된 결과에 없는 토큰을 거부하므로, 11480.0을 "11500"으로 반올림하거나 0.1246을 "12.46%"로 변환하거나 두 저장된 비용을 더하는 설명은 실패합니다 — 각각은 솔버가 생성한 적이 없는 숫자입니다. 호스트는 표시 전에 어떤 설명에도 적용할 수 있으며, 모델이 explain이 반환한 것이 아니라 자신의 말로 작성한 설명도 포함됩니다. explain은 반환하기 전에 자체 출력에 대해 실행합니다.

가드가 의도적으로 허용하는 것은 더 강한 주장으로 오해되지 않도록: 저장된 문자열과 dict 키 내부의 숫자는 존재하는 것으로 간주됩니다. 설명이 해당 문자열을 그대로 인용할 수 있기 때문입니다. "ortools-cpsat+py3dbp"는 3을 허용하고, 필드 이름 eta_p90_days는 90을 허용합니다. 숫자 토큰에 대한 어휘 검사이지 의미적 정확성의 증명이 아닙니다: 올바른 숫자를 잘못된 레이블에 붙인 설명도 여전히 통과합니다.

설치

Python 3.10 이상.

python -m venv .venv
./.venv/bin/pip install ortools py3dbp pytest

또는 패키지 자체를 설치하면 두 가지 런타임 종속성이 함께 설치됩니다:

pip install -e .

ortools는 CP-SAT 엔진이고, py3dbp는 MIT 라이선스의 3D 패커입니다. MCP 서버는 표준 라이브러리 외에 아무것도 추가하지 않습니다 — stdio 프로토콜 표면이 충분히 작아 직접 구현할 수 있으므로 종속성 목록을 감사 가능하게 유지합니다.

실행

서버는 stdin/stdout에서 개행으로 구분된 JSON-RPC 2.0을 사용합니다:

python -m solver_mcp

솔버는 MCP 없이도 라이브러리 또는 자식 프로세스로 사용할 수 있습니다:

from load_planner import generate_scenarios
result = generate_scenarios(problem)

cat fixtures/cohort_urgent.json | python -m load_planner.cli

MCP 클라이언트에 연결

stdio 서버를 시작하는 모든 클라이언트는 명령과 인수를 받습니다. 일반적인 mcpServers 구성 형태를 사용하는 클라이언트의 경우:

{
  "mcpServers": {
    "load-planner": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "solver_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/load-planner-mcp" }
    }
  }
}

PYTHONPATH는 패키지가 인터프리터 환경에 설치되지 않은 경우에만 필요합니다; pip install -e . 후에는 env 블록을 제거할 수 있습니다.

핸드셰이크는 표준입니다: initialize, 그 다음 notifications/initialized 알림, 그 다음 tools/list. 서버는 프로토콜 버전 2025-06-18을 보고하고 2025-03-26 및 2024-11-05를 수락하며, 클라이언트가 요청한 것이 그 중 하나라면 해당 버전을 에코합니다.

테스트

python -m pytest tests/ -q

세 가지 스위트: 픽스처에 대한 솔버 자체 테스트; 프로세스 내 및 실제 stdio 하위 프로세스를 통해 실행되는 MCP 핸드셰이크와 두 도구; 그리고 저장된 결과에 없는 값을 포함하는 설명이 거부되는지 확인하는 변조 스위트.

제한 사항

• 단일 머신, 단일 프로세스. 결과 저장소는 메모리에 있으며 서버 프로세스 수명 동안 유지됩니다. 한 프로세스의 result_id가 다른 프로세스에서 해석되는 것은 ID가 콘텐츠 주소화되고 솔버가 결정론적이기 때문입니다 — 동일한 문제를 다시 해결하면 ID가 재현됩니다. 공유 저장소, 제거 정책, 보존 결과 수에 대한 제한이 없습니다.

• 솔버 런타임. CP-SAT는 열거된 모드 패턴당 한 번, solve당 최대 세 번 호출되며, 하나의 정수 변수와 두 개의 제약 조건이 있는 모델에서 밀리초 단위로 반환됩니다. 확장되는 비용은 3D 패커로, 팔레트당 하나의 항목을 배치합니다 — 수백 개의 팔레트는 괜찮지만 수만 개는 그렇지 않습니다. solve는 동기적으로 실행되며 내부 타임아웃이 없으므로 호스트가 자체 타임아웃을 부과해야 합니다.

• 전체 주문 할당만 가능. 하나의 주문을 두 모드로 분할하는 것(기본+서지 정책)은 모델링되지 않습니다; 각 주문은 하나의 모드에 완전히 할당됩니다.

• 시드된 위험 입력. risk.py의 지연 분포는 게시된 운송업체 신뢰성 시드이지 자체 레인 기록의 측정값이 아닙니다. 호출자가 이를 교체할 때까지 올바른 형태와 잘못된 정밀도를 가집니다.

• 가드는 어휘적입니다. 위의 메모를 참조하세요: verify_narration은 설명의 모든 숫자가 결과에 나타나는지 확인합니다. 숫자가 올바른 의미로 사용되었는지는 확인하지 않습니다.