Openworker E-Commerce MCP Server

MCP (Model Context Protocol) Server는 Openworker와 함께 사용하여 Chrome 또는 Microsoft Edge를 제어하고, 주요 E-Commerce 플랫폼(Shopee, TikTok Shop 및 Lazada)의 상품을 관리하도록 설계되었습니다.

🚀 프로젝트 목적 (Project Overview)

이 시스템은 Seller Center 페이지에서 일반적인 봇의 자동 브라우저 제어 문제를 해결하기 위해 개발되었습니다.

1. 실제 Session 로그인: Remote Debugging Port (9222)를 통해 사용자가 이미 로그인되어 있는 Chrome/Edge에 연결합니다. 새로 로그인하거나 OTP/2FA 인증을 반복할 필요가 없습니다.

2. Internal API Interception을 통한 빠른 업데이트: 브라우저에서 Session 쿠키/토큰을 가져와 API를 통해 직접 업데이트 명령을 전송하므로 빠르고 정확하며, UI 클릭에만 의존하지 않습니다.

3. Safety Guard 및 Captcha Pause: Save 전에 가격 및 재고 경계를 확인하고, Captcha가 감지되면 작업을 일시 중지하여 사용자가 즉시 해제할 수 있도록 합니다.

Related MCP server: camoufox-mcp

👥 역할 및 개발 (Team & Development Roles)

• Jules (Google AI Agent): TypeScript를 작성하고, 카테고리별 Tools (Browser Attach, Session Interceptor, API Client, Safety Guard) 작성 및 Unit Tests 작성

• Controller Agent (Cowork / GitHub Controller): 프로젝트 구조를 관리하고, Code/PR 리뷰 및 Task Issues 설계, Tag Release 생성 및구성하는 Open 배포를 담당합니다.

🛠️ 프로젝트 구조 (Project Structure)

openworker-ecommerce-mcp/
├── src/
│   ├── index.ts                # Entry point หลักของ MCP Server
│   ├── types.ts                # Type Definitions & Schemas
│   ├── services/
│   │   ├── cdp-connection.ts   # ตัวจัดการเชื่อมต่อ Chrome/Edge CDP (Port 9222)
│   │   ├── session-extractor.ts# ตัวดึง Auth Cookies / Bearer Tokens จาก Tab
│   │   └── api-client.ts       # Internal API Wrapper สำหรับ Shopee/TikTok/Lazada
│   └── tools/
│       ├── browser-profile.ts  # Tool: browser_attach_existing
│       ├── ecommerce-search.ts # Tool: ecommerce_product_search
│       ├── ecommerce-update.ts # Tool: ecommerce_update_price_stock
│       └── safety-guard.ts     # Tool: ecommerce_safety_guard
├── docs/
│   ├── ARCHITECTURE.md         # สถาปัตยกรรมและรายละเอียด Tool Contracts
│   └── TASKS.md                # รายการงานสำหรับการพัฒนาราย Phase
├── JULES_PROMPT.md             # ข้อแนะนำการสั่งงาน Jules (Google AI Agent)
├── package.json
└── tsconfig.json

💻 연결을 위한 Chrome / Edge 실행

시작 환경 또는 사용 전에 Chrome 또는 Microsoft Edge를 Remote Debugging 명령어로 실행합니다.

Windows (Chrome):

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\ChromeAutomationProfile"

Windows (Edge):

"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="C:\EdgeAutomationProfile"

⚙️ 설치 및 사용 (Installation & Build)

# ติดตั้ง dependencies
npm install

# Build TypeScript
npm run build

# ทดสอบรัน MCP Server
npm start

📄 라이선스 (License)

MIT License - 개발자: tukimtk-design

🚀 Phase 7 Features

Auto-Launch on Windows

Windows에서 CDP 연결이 실패하면 시스템은 올바른 원격 디버깅 포트로 Chrome/Edge를 자동으로 실행하여 원활한 1-click 환경을 제공합니다.

Playwright E2E Mocks

Mock된 E2E 흐름을 다음 명령어로 실행할 수 있습니다:

npm test

Openworker Auto-Installer

PowerShell 스크립트를 실행하여 프로젝트를 빌드하고 MCP 구성을 생성합니다:

.\scripts\install-openworker-mcp.ps1

🚀 Phase 8 Features

Multi-Platform Stock Sync

Shopee, TikTok Shop, Lazada 쇼핑몰 간의 재고와 가격을 자동으로 동기화합니다. 시스템이 안전 경계를 오케스트레이션하고 작업을 기록합니다.

Fuzzy Variant Matching

시스템은 문자열 유사도(Levenshtein Distance)를 사용하여 플랫폼마다 이름이 다르게 지정된 상품 변형을 매칭하며, SQLite를 활용하여 성공한 매칭을 캐시해 다음에도 즉시 조회할 수 있습니다.

🚀 Phase 9 Features (Enterprise)

Docker & Headless Run

공식 Playwright Docker 이미지와 Xvfb를 사용하여 클라우드에서 24/7로 배포합니다:

docker-compose up -d

Visual DOM Self-Correction

예상치 못한 DOM 충돌 시 AI가 스스로 수정할 수 있도록 뷰 스크린샷과 bounding boxes를 캡처합니다.

Proxy Rotation

다중 ip계정 분리를 위해 순환식 프록시를 지원합니다.