@junis/wms-junis-mcp

Wishcompany WMS (난소프트 EMP) MCP server for Junis B2B.

npm 패키지명: @junis/wms-junis-mcp (npm scope: junis) bin 명령어: junis-mcp-wms (또는 wms-junis-mcp)

설치 / 실행

npx 로컬 실행 (개발)

npm install
npm run build
WMS_BASE_URL=<your-wms-url> WMS_API_KEY=<your-api-key> npx tsx src/index.ts

Claude Code / MCP 클라이언트 설정 예시

~/.claude.json 또는 클라이언트별 MCP 설정에 인증값을 환경변수로 주입:

{
  "mcpServers": {
    "junis-wms": {
      "command": "npx",
      "args": ["-y", "@junis/wms-junis-mcp"],
      "env": {
        "WMS_BASE_URL": "<your-wms-url>",
        "WMS_API_KEY": "<your-api-key>",
        "WMS_DEFAULT_WAREHOUSE_CODE": "B2B-WH"
      }
    }
  }
}

⚠️ 인증값(WMS_API_KEY)은 연결하는 측이 환경변수로 주입합니다. 본 레포 코드에는 어떤 인증값도 포함되어 있지 않습니다. 운영 환경에서는 secret manager / 환경별 설정을 통해 주입하세요.

환경변수

| 변수 | 필수 | 기본값 | 설명 | |---|---|---|---| | WMS_BASE_URL | ✅ | — | WMS 서버 base URL (예: https://api.empsystem.co.kr) | | WMS_API_KEY | ✅ | — | WMS ApiKey 헤더값 | | WMS_DEFAULT_WAREHOUSE_CODES | | B2B-WH,B2C-WH,B2B-MO | 도구 input 에 warehouseCodes 미명시 시 사용 (콤마 구분 · default 3 창고 병렬 합산) | | WMS_BULK_CONCURRENCY | | 5 | 다수 SKU 조회 시 병렬 호출 수 | | WMS_REQUEST_TIMEOUT_MS | | 30000 | 단일 호출 타임아웃 |

도구

wms_get_stock_for_skus

WMS 가용 재고 조회 (GetStockInformation).

Input: | 필드 | 타입 | 필수 | 설명 | |---|---|---|---| | itemNos | string[] | ✅ | ItemNo / productCode 리스트 (1개 이상) | | warehouseCodes | string[] | | 창고 코드 배열. 미명시 시 [WMS_DEFAULT_WAREHOUSE_CODE] 사용 (default ["B2B-WH"]). 미국 거래처: ["B2B-WH","B2B-MO"] (회의 §D.Q5) | | asOfDate | YYYYMMDD | | 조회 기준일 (default: 오늘) |

Output:

{
  warehouseCodes: string[],   // 조회한 창고 리스트
  asOfDate,
  requestedCount, foundCount,
  notFound: string[],         // 모든 창고에서 0건인 ItemNo
  errors: [{ itemNo, warehouseCode, error }],
  bySku: {
    "DK10003": {
      totalQty, deliveryWaitQty, availableQty,    // 모든 창고 합산
      warehouseCodesQueried: ["B2B-WH","B2B-MO"],
      lots: [
        {
          lotNo, productCode, productName,
          expirationDate,                          // YYYY-MM-DD or null
          qty, qtyWaiting, qtyAvailable,
          warehousePCode, warehousePName           // ← LOT 별 출처 창고 보존
        }
      ]
    }
  }
}

창고 코드 가이드 (회의 합의 반영):

| 창고 코드 | 용도 | 카탈로그 노출 | |---|---|---| | B2B-WH | B2B물류센터 — 카탈로그 default · 65% 이상 잔량 보장 | ✅ | | B2B-MO | MoCRA물류센터 — 미국 거래처 전용 (B2B-WH 와 합산) | ✅ (US only) | | B2C-WH | B2C 정상창고 (이커머스용) | ❌ | | B2B-GMG, B2B-JMG, B2B-APMG, B2B-DMG, B2B-NAMG | 랩 — 별도 목적성 | ❌ | | DOLPHIN-IN | 돌핀입고대기 | ❌ |

Use case 별 응답 활용: | Use case | 활용 필드 | |---|---| | 카탈로그 신호등 (3단계) | bySku[sku].availableQty | | 상품 상세 화면 (LOT 표시) | bySku[sku].lots | | Validation Agent (거래처 한계 > 65%) | bySku[sku].lots + ERP MCP mfgDate join (lotNo 매칭) |

회의 합의 반영

| 합의 | 적용 | |---|---| | B2B-WH 가 65% 이상 잔량 보장 | WMS_DEFAULT_WAREHOUSE_CODE=B2B-WH | | 재고 신호등만 노출, 숫자 직접 X | composite output 의 availableQty 를 호출자가 신호등으로 변환 | | LOT 별 expirationDate 분리 | lots[] 에 LOT 단위 row N개 | | 가용 재고 = 합으로 봐도 됨 | availableQty (합산) + lots[] (필요 시 분해) 둘 다 제공 |

회의 합의 적용 매트릭스

| 회의 합의 | 출처 | 적용 | |---|---|---| | 재고 시트 안 보고 WMS API 만 활용 | 아젠다 §3.Q1 / 미팅메모 | composite 가 WMS API 직접 호출 | | B2B-WH default · 65% 이상 잔량 보장 | 아젠다 §3.Q1 / 사용자 확인 | WMS_DEFAULT_WAREHOUSE_CODE=B2B-WH | | 미국 거래처: B2B-WH + B2B-MO 합산 | 아젠다 §D.Q5 | warehouseCodes: ["B2B-WH","B2B-MO"] 배열 input | | 랩별 창고 (GMG/DMG 등) 카탈로그 X | 아젠다 §3.Q1 / 정리액션 | description 가이드. 호출자 책임 | | FOC 전용 창고 없음 — B2B 기준 | 아젠다 §3.Q5 | 별도 처리 안 함. 호출자가 동일 도구 사용 | | expirationDate = 유통기한 | 아젠다 §3.Q3 | lots[].expirationDate 그대로 | | LOT 합으로 봐도 됨 + 인폼 시 LOT 정보 | 아젠다 §3.Q4 | availableQty (합산) + lots[] (분해) 둘 다 | | 입고 예정 안 보여줌 (Lv.1) | 아젠다 §D.Q7 | 도구 미포함 | | 가용 재고 자동 차감 불가 (read-only) | 아젠다 §B.Q3·Q4 | read-only 도구 | | 거래처 한계 > 65% Validation 시 mfgDate join | 사용자 확인 | lots[].lotNo ↔ ERP MCP erp_get_lot_manufacturing_dates 의 lot 매칭 |

개발

npm install
npm run typecheck
npm run dev
npm run build

라이선스

UNLICENSED — Junis 내부용.