# 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.

```text
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.

```bash
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.

```env
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`.