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.