inventory-mcp-server by omeletJK - MCP Server

🏭 재고 관리 최적화 MCP 서버

Model Context Protocol (MCP) 서버로 구현된 지능형 재고 관리 최적화 도구

🎯 개요

이 MCP 서버는 예측된 수요 데이터를 기반으로 재고 관리를 최적화합니다. 현재 재고 수준과 예측된 일별 수요를 입력받아 최적의 일별 주문 계획을 제공합니다.

🌟 주요 특징

✅ 안전 재고 기반 최적화: 품절 방지를 위한 지능형 계산
✅ 리드타임 고려: 주문-도착 지연시간 반영
✅ 수요 예측 기반: 미래 수요를 고려한 선제적 주문
✅ 제약 조건 적용: 현실적인 주문량 제한
✅ Claude Desktop 연동: 자연어로 쉬운 조작

🚀 빠른 시작

1. 설치

# Python 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

2. 서버 실행

# 개발 모드로 실행
python api.py

# 또는 uvicorn으로 직접 실행
uvicorn api:app --host 0.0.0.0 --port 8000 --reload

3. 브라우저에서 확인

API 문서: http://localhost:8000/docs
헬스체크: http://localhost:8000/health
예제 확인: http://localhost:8000/example

📊 사용법

API 호출 예시

curl -X POST "http://localhost:8000/optimize" \
     -H "Content-Type: application/json" \
     -d '{
       "inventory_level": 100,
       "forecasted_demand": [12, 10, 15, 18, 9, 11, 13, 14, 10, 12],
       "lead_time": 2
     }'

응답 예시

{
  "order_plan": [0, 10, 18, 0, 0, 5, 8, 0, 0, 7],
  "total_orders": 48,
  "max_daily_order": 18,
  "avg_daily_order": 4.8
}

🤖 Claude Desktop에서 사용하기

MCP 설정

Claude Desktop의 설정 파일에 다음을 추가:

{
  "mcpServers": {
    "inventory-optimization": {
      "command": "python",
      "args": ["/path/to/inventory-mcp-server/api.py"],
      "env": {}
    }
  }
}

자연어 프롬프트 예시

현재 재고가 100개이고, 향후 10일간 수요가 [12, 10, 15, 18, 9, 11, 13, 14, 10, 12]일 때 
최적의 주문 계획을 세워주세요. 주문 후 도착까지는 2일이 걸립니다.

🐳 Docker로 실행

# 이미지 빌드
docker build -t inventory-optimizer .

# 컨테이너 실행
docker run -p 8000:8000 inventory-optimizer

📁 프로젝트 구조

inventory-mcp-server/
├── main.py                 # 핵심 최적화 알고리즘
├── api.py                  # FastAPI 웹서버
├── mcp_config.json        # MCP 서버 설정
├── task_description.md    # 상세 사용법 가이드
├── sample_inputs/         # 예제 입력 파일들
│   ├── input1.json       # 기본 시나리오
│   ├── input2.json       # 높은 변동성
│   └── input3.json       # 계절성 패턴
├── requirements.txt       # Python 의존성
├── Dockerfile            # Docker 설정
├── start.sh              # 실행 스크립트
└── README.md            # 이 파일

🧮 알고리즘 상세

최적화 로직

안전 재고 계산: 평균 수요 × 3일
미래 재고 예측: 현재 재고 - 리드타임 기간 수요
주문 트리거: 예상 재고 < 안전 재고
주문량 계산: 안전재고 + 향후 수요 - 현재 재고

제약 조건

최대 주문량: 평균 수요의 7일치
최소 주문량: 0 (음수 방지)
예측 기간: 최대 365일

🔧 고급 설정

파라미터 조정

알고리즘의 안전 재고 배수나 최대 주문량 제한을 조정하려면 main.py의 다음 부분을 수정:

# 안전 재고 수준 (평균 수요의 3일치)
safety_stock = math.ceil(avg_demand * 3)  # 3을 다른 값으로 변경

# 최대 주문량 제한 (평균 수요의 7일치)
max_order = math.ceil(avg_demand * 7)     # 7을 다른 값으로 변경

📈 예제 시나리오

시나리오 1: 안정적 수요

현재 재고: 100개
일별 수요: 10-18개 (안정적)
리드타임: 2일
결과: 효율적인 주문 계획

시나리오 2: 변동성 높은 수요

현재 재고: 50개
일별 수요: 5-45개 (높은 변동)
리드타임: 3일
결과: 안전 재고 강화된 계획

시나리오 3: 계절성 패턴

현재 재고: 200개
수요 패턴: 점진적 증가 후 감소
리드타임: 1일
결과: 피크 대비 선제적 주문

🤝 기여하기

Fork 이 저장소
Feature 브랜치 생성 (git checkout -b feature/AmazingFeature)
변경사항 커밋 (git commit -m 'Add some AmazingFeature')
브랜치에 Push (git push origin feature/AmazingFeature)
Pull Request 오픈

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 파일을 참조하세요.

🔗 관련 링크

📞 지원

질문이나 이슈가 있다면:

GitHub Issues에 등록
자세한 사용법은 참조

⭐ 이 프로젝트가 도움이 되었다면 스타를 눌러주세요!