Supply Chain Decision Intelligence MCP

로컬에서 동작하는 결정론적 MCP 연구 프로젝트로, 고신뢰성 하드웨어 공급망 분석을 위한 것입니다. 이 프로젝트는 LLM이 자연어로 공급망 질문을 할 수 있지만, 정량적 답은 모델이 아니라 SQL/Python 도구가 담당하는 방식을 보여줍니다.

이 프로젝트가 풀어내는 문제: 공급망 및 제조 램프(unsigned ramp) 결정(어떤 공급업체를 승인할지, 보충 재고가 도착하기 전에 부품이 소진될지, 최저가 단독 조달보다 듀얼 소싱 프리미엄이 가치 있는지)는 공급업체, 재고, 구매 주문, 품질 데이터를 조인하고 일관되고 감사 가능한 계산을 수행해야 합니다. 즉, LLM의 짐작이 아니라 정확한 수식이 필요합니다. 이 프로젝트는 합성 데이터셋에서 해당 패턴을 엔드투엔드로 보여줍니다. LLM은 어떤 통제된 계산을 실행할지만 선택하고 결과를 설명합니다.

합성 데이터만 사용합니다. 이 저장소에는 실제 Zipline 공급업체, 생산, 수요, 고객, 운영 데이터가 없습니다. 이 프로젝트는 공개된 공급망 문제 패턴에서 영감을 받은 방법론 데모입니다. 공급업체 성과, 램프 예측, MRP 부족 위험, 단일 소싱 집중도, 착지 비용, 플릿 용량 검토, 의료 재보충, 다년간 공급업체 역량을 다룹니다.

이 설계를 선택한 이유

flowchart LR
  Q["Natural-language research question"] --> L["LLM chooses a tool"]
  L --> M["MCP typed interface"]
  subgraph D["Deterministic analytics boundary"]
    M --> A["Governed SQL / Python"]
    A --> C["Checked-in synthetic CSVs"]
    A --> R["Structured result + trust block"]
  end
  R --> L2["LLM interprets the result"]

이 모델은 어떤 통제된 계산을 호출할지 선택하고 결과를 설명합니다. 이 모델은 MAPE, OTD, weeks of cover, 또는 용량 계산을 기억에서 재현하지 않습니다.

이 다이어그램의 완전한 라벨링 버전, 확률적 LLM 계층과 결정론적 통제 계층을 명시적으로 구별한 내용, 완전한 MCP 도구 맵(13개 도구 -> 각 도구가 읽는 데이터셋)이 있는 실전 예시 의사결정 흐름은 docs/ARCHITECTURE.md를 참조하세요. 개체-관계 다이어그램은 docs/DATA_MODEL.md를 참조하세요.

Related MCP server: Fabric MCP Agent

도구 표면

또한 research://catalog MCP 리소스와 supply_chain_investigation, supply_chain_question_generator 프롬프트가 제공됩니다.

로컬 우선(local-first): 이전 MCP 셋업 실패를 피한 정확한 방법

이 프로젝트는 의도적으로 이전 로컬 MCP 빌드에서 견고함이 입증된 런타임 패턴을 사용합니다:

• 시작 중에 데이터베이스 파일을 생성하지 않음

• .venv를 포함하지 않음

• .mcp.json을 포함하지 않음

• 모든 데이터 경로는 server.py의 __file__에서 파생됨

• DuckDB는 git에 커밋된 CSV 위에 새 in-memory 뷰를 생성함

• uv run --with ...을 사용하면 dev/stdio 실행이 editable-install 메타데이터와 독립적으로 시작됨

1. Preflight

cd <where-you-cloned-this-repo>
uv sync --extra dev
uv run python scripts/preflight.py

You want PREFLIGHT PASSED.

2. Launch MCP Inspector에서 구동

./scripts/run_mcp_dev.sh

uv가 묻는 경우 종속성 설치를 승인하세요. MCP Inspector가 13개 도구와 함께 열려야 합니다.

권장되는 첫 호출:

1. supplier_scorecard (인자: limit=5)

2. forecast_accuracy

3. parts_at_risk (인자: limit=10)

4. dual_source_risk

5. compare_landed_costs

6. dock_capacity

7. stockout_reduction

8. capacity_ramp

9. projected_shortage_risk (인자: horizon_weeks=8)

10. quality_gate_risk

11. quality_rush_signal

12. quality_trend

3. Claude 없이 분석 스모크 테스트

uv run python scripts/smoke_test.py

경영자용 웹 앱

"Production Ramp Intelligence"라는 이름의 이 로컬·정적 애플리케이션은 동일한 통제된 도구들을 기반으로합니다. 접근 준비의 관리도, 핵심 부품 리스크, 소스 집중도, 용량/적격성 의사결정 뷰를 제공합니다. 각 항목은 그 뒤에서 실행된 MCP 도구 호출까지 추적할 수 있습니다:

uv run python scripts/generate_executive_dataset.py
uv run python scripts/serve_executive_site.py

그런 다음 http://127.0.0.1:8765/ 를 엽니다. docs/EXECUTIVE_APP.md를 참조하세요.

테스트 실행

uv sync --extra dev
uv run pytest -q

이 절차는 데이터 무결성 검사, 도구 동작 확인, 런타임 계약 검사, JSON 안전성/패키징/preflight 회귀 테스트 스위트를 실행합니다. 각 테스트 파일이 구체적으로 검증하는 내용은 docs/CODE_WALKTHROUGH.md의 "Tests: what each file actually proves" 섹션을 참조하세요.

4. Inspector가 동작한 뒤에만 Claude Code에 등록

./scripts/register_claude.sh
claude

Claude Code에서 /mcp를 실행하세요. zipline-supply-chain이 13개 도구와 함께 연결된 것을 볼 수 있어야 합니다.

그런 다음 다음과 같은 프롬프트를 사용합니다:

공급망 분석가 역할을 수행하세요. list_research_questions로 시작하세요. 정량적 근거를 얻으려면 zipline-supply-chain MCP 도구만 사용하세요. 제조 램프에 가장 중요한 공급업체/부품 위험, 증거가 말하는 것, 해석의 여지가 무엇이고 합성 데이터가 입증할 수 없는 것이 무엇인지 알려주세요. 원시 CSV를 직접 검토하거나 메트릭을 스스로 재계산하지 마세요.

예시 연구 질문

이 데이터셋은 서로 얽힌 두 공급망을 분리합니다.

제조: 공급업체 성과, 예측 편향, MRP 부족, 듀얼 소싱 집중도, 착지 비용, 그리고 다년간 역량 허용.

운영물류: 최대 도크 플리트 처리량과 의료 재보충 재고 소진(임박) 감소.

이 구분은 도구와 프롬프트 규율에 설계로 들어가 있습니다.

DEMO_QUESTIONS.md와 PROMPTS.md를 참조하세요.

문서 지도

전체 파일 트리: docs/REPOSITORY_GUIDE.md.

이 프로젝트가 주장하지 않는 것

이 프로젝트는 운영용 ERP/MRP, 경로 최적화 도구, 우주 군용 자격 시스템, 인과적 영향 연구, 실제 회사 데이터 모델이 아닙니다. 요점은 LLM 기반 의사결정 지원을 위한 통치된 분석 경계(governed analytical boundaries) 를 마련함에 있습니다.

무결성 / 재현성 검사

합성 관계형 모델은 다음을 보장합니다. 입고 및 품질 팩트는 유효한 (part_id, supplier_id) 키를 가지며, 자격 승인 게이트는 실제 공급업체 마스터 ID를 사용하고, 모든 PO는 유효한 부품-공급업체 매핑을 사용하며, 재고는 부품당 정확히 하나의 행을 갖습니다. 현재 데이터셋 버전은 data/MANIFEST.json/DATASET_VERSION을 참조하세요.

MCP 실행 전에 실행하세요(scripts/preflight.py에서도 다루어짐):

uv run python scripts/audit_data_relationships.py
uv run python scripts/generate_synthetic_facts.py --check

첫 번째는 외래 키, 복합 관계, 고유성, 그리고 중요한 참조 앵커(이 데이터셋이 재현하도록 설계된 고정값)를 검사합니다. 두 번째는 고정된 시드와 마스터 픽스처에서 확률/보강 팩트 테이블을 재생성하고, 커밋된 출력과 바이트 단위로 비교합니다.

서버 자체에는 런타임 무작위성이 없습니다. 커밋된 CSV가 주어지면 도구 출력은 결정적입니다. 이것은 재현 가능한 합성 연구 데이터이며, 합성 분포가 통계적으로 Zipline을 대표한다는 주장은 아닙니다.

데이터셋 규모

12주 치 demand.csv는 참조 앵커 뒤에 있는 정확한 관리형 램프 케이스입니다. annual_demand.csv는 더 정확한 롤링 오차 분석을 위해 결정론적 주간 관측치 52개를 추가하며, forecast_accuracy(series="annual_52w")를 통해 조회되므로 12주 치 상세 예제를 조용히 바꾸지 않습니다.

합성 부품 유니버스는 14개 상품 계열에 걸쳐 60개 부품을 망라합니다. 이는 의도적으로 데모 수준의 규모로, 의미 있는 재고 및 소싱 순위를 도출할 만큼 충분하면서도, 라이브로 직접 확인하고 설명할 수 있을 만큼 작습니다.