Commerce-MCP

자연어로 커머스 운영을 지시하면 상품, 주문, 재고, CS, 콘텐츠, 광고, 브리핑까지 로컬에서 이어서 처리하는 AI 기반 Commerce MCP 서버다.

Commerce-MCP is a local-first AI commerce MCP server that turns natural-language instructions into product, order, inventory, CS, content, ad, and daily-briefing workflows.

Structure

입력부터 운영 브리핑까지 흐름을 로컬 수직 슬라이스로 묶었다.

The current implementation is a local-first vertical slice that stretches from product input to daily operations.

Seller Prompt
  -> commerce_parse_product
    -> StandardProduct
      -> Commerce Tools
        -> ChannelTransformer / Builtin Logic
          -> Mock Channel Adapters
            -> SQLite

What It Does

현재 저장소는 아래 15개 MCP 도구를 로컬 내장형으로 제공한다.

This repository currently exposes the following 15 MCP tools in a local-first builtin form.

ID	Tool	Role
1	commerce_parse_product	자연어/JSON-like 상품 입력 파싱
2	commerce_register_product	채널별 상품 등록 mock
3	commerce_sync_product	가격/재고/상품 상태 동기화
4	commerce_collect_orders	주문 수집 및 정규화
5	commerce_process_orders	송장 반영 및 출고 처리
6	commerce_manage_inventory	재고 경고 및 발주 추천
7	commerce_generate_po	발주서용 CSV/Markdown 생성
8	commerce_collect_cs	CS 수집 및 자동 분류
9	commerce_respond_cs	CS 답변 초안 생성
10	commerce_generate_listing	상품 상세 HTML 생성
11	commerce_generate_image	SVG 기반 상품 비주얼 생성
12	commerce_create_ad	광고 소재/캠페인 초안 생성
13	commerce_report_ad	광고 성과 리포트
14	commerce_analytics	주문/채널/매출 분석
15	commerce_daily_briefing	일일 운영 브리핑 생성

Current Mode

현재 구현 범위는 아래와 같다.

The current implementation includes the following:

Area	Status
Product	파싱, 등록, 동기화 지원 / parse, register, sync
Orders	수집, 출고 처리, 일매출 집계 / collect, process, aggregate daily sales
Inventory	저재고 경고, 발주서 생성 / low-stock alerts and purchase-order generation
CS	문의 분류와 답변 초안 생성 / inquiry classification and draft response
Content	HTML 상세페이지와 SVG 비주얼 생성 / HTML listing and SVG visual generation
Ads & Analytics	광고 초안, 광고 리포트, 분석, 브리핑 / ad draft, ad report, analytics, briefing
MCP Server	FastMCP 기반 15개 도구 노출 / FastMCP exposure for all 15 tools
Tests	핵심 운영 흐름 검증 / coverage for core operating flows

Quick Start

로컬에서 바로 실행하려면 아래 순서로 진행하면 된다.

Use the following steps to run the project locally.

python -m pip install -e .[dev]
pytest -q
python server.py

환경변수는 선택 사항이며 지정하지 않으면 프로젝트 루트의 commerce.db를 사용한다.

Environment variables are optional. If unset, the server uses commerce.db in the project root.

COMMERCE_MCP_DB_PATH=./commerce.db

Example Flow

보스가 실제로 쓰게 될 기본 흐름은 아래와 같다.

Here is the core operating flow the boss would actually use.

1. commerce_parse_product로 상품 입력 정규화
2. commerce_register_product로 채널 mock 등록
3. commerce_collect_orders로 주문 적재
4. commerce_process_orders로 송장 반영 및 재고 차감
5. commerce_manage_inventory와 commerce_generate_po로 부족 재고 점검
6. commerce_collect_cs와 commerce_respond_cs로 문의 대응
7. commerce_create_ad, commerce_report_ad, commerce_analytics, commerce_daily_briefing으로 운영 요약

Key Files

처음 들어왔을 때 보면 좋은 파일들이다.

These are the most useful entry points when you first open the project.

Path	Purpose
server.py	실행 진입점 / runtime entrypoint
core/server.py	FastMCP app과 도구 등록 / FastMCP app and tool registration
tools/product_parse.py	상품 입력 파서 / product input parser
tools/product_register.py	등록 흐름과 DB 저장 / registration flow and persistence
tools/order_collect.py	주문 수집 / order collection
tools/order_process.py	주문 처리와 재고 반영 / order processing and inventory update
tools/daily_briefing.py	운영 브리핑 생성 / operations briefing
core/db.py	SQLite bootstrap과 저장소 / SQLite bootstrap and repository
tests/	Phase 0 검증 세트 / Phase 0 verification suite

Notes

현재 채널 연동은 mock/builtin 중심이다. 실제 쿠팡/네이버/11번가 API를 붙일 때는 ModuleAdapter와 채널 어댑터를 교체하면 된다.

Current channel integrations are mock-first. When real Coupang, Naver, or 11st APIs are ready, replace the builtin adapter path behind ModuleAdapter.