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.

commerce_parse_product로 상품 입력 정규화
commerce_register_product로 채널 mock 등록
commerce_collect_orders로 주문 적재
commerce_process_orders로 송장 반영 및 재고 차감
commerce_manage_inventory와 commerce_generate_po로 부족 재고 점검
commerce_collect_cs와 commerce_respond_cs로 문의 대응
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.

MCP Servers