상품 빅데이터 서비스

이 MCP 서비스는 기업 키워드 검색, 상품 검색, 기업 상품, 해외 스토어 상품, 브랜드 및 전자상거래 채널 조회 기능을 제공하여 사용자가 상품 선정, 경쟁사 조사, 상품 자격 검증 및 채널 분석을 수행할 수 있도록 돕습니다.

주요 기능

• 🏢 기업 약칭 및 키워드 검색

• 🔍 소매 상품 및 해외 온라인 스토어 검색

• 🧾 기업 소매 상품 및 전자상거래 상품 조회

• 🌍 해외 스토어 상품 카탈로그 조회

• 🏷️ 뷰티 산업 기업 브랜드 및 제품 효능 분석

• 🛒 국내 및 글로벌 온라인 스토어 채널 분석

Related MCP server: Enterprise Operation Insight MCP Server

서비스 설계 설명

• 서비스는 실제 사용 대상을 기준으로 6개의 Tool을 제공하며, 상위 API 수에 따라 도구를 나열하지 않습니다.

• 사용자가 기업 약칭만 제공하는 경우 먼저 goods_enterprise_search를 사용하여 기업 전체 이름 또는 안정적인 ID를 얻습니다.

• 기업 상품과 해외 스토어 상품은 각각 별도의 Tool을 제공하여 동일한 매개변수가 서로 다른 출처에서 다른 대상을 나타내지 않도록 합니다.

• goods_enterprise_products는 소매 상품 또는 전자상거래 상품을 선택할 수 있지만, 단일 호출에서는 하나의 Product ID만 접근합니다.

• 기업 소매 상품은 페이지당 최대 10건, 기타 페이지 조회는 페이지당 최대 50건입니다.

• 페이지 조회 결과의 비즈니스 외부 레이어는 total과 resultList로 통일됩니다.

• 제3자 상품에 의존하는 스토어 인기 상품, 월간 판매 및 누적 판매 기능은 제거되었으며, 가격 또는 판매 추이 Tool은 더 이상 등록하지 않습니다.

• Tool 성공 시 HandaaS Integrator Gateway에서 추출된 비즈니스 data를 반환합니다.

환경 요구 사항

• Python 3.10+

• 종속 패키지: python-dotenv, requests, mcp

로컬 빠른 시작

1. 프로젝트 디렉터리로 이동

cd goods-mcp-server

2. 가상 환경 생성 및 종속성 설치

python3 -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt

3. 환경 변수 구성

cp .env.example .env

.env 편집:

INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30

HANDAAS_REQUEST_TIMEOUT는 선택 구성이며 단위는 초이고 기본값은 30입니다.

4. 서비스 시작

python server/mcp_server.py streamable-http

서비스 기본 주소는 http://localhost:8000/mcp입니다.

다음도 사용할 수 있습니다:

./start_mcp_server.sh streamable-http

stdio, sse, streamable-http 세 가지 시작 방식을 지원합니다.

5. Cursor / Cherry Studio 구성

{
  "mcpServers": {
    "goods-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

STDIO 버전 설치 배포

{workdir}를 프로젝트 절대 경로로 바꿉니다:

{
  "mcpServers": {
    "goods-mcp-server": {
      "command": "{workdir}/mcp_env/bin/python",
      "args": [
        "{workdir}/server/mcp_server.py",
        "stdio"
      ]
    }
  }
}

INTEGRATOR_ID, SECRET_ID, SECRET_KEY는 HandaaS에 로그인하여 연동기(Integrator)를 등록하고 개통한 후에 얻을 수 있습니다. 실제 자격 증명은 로컬 .env 또는 배포 키에만 저장해야 합니다.

사용 가능한 Tool 및 Product ID

1. goods_enterprise_search

기능: 기업 약칭, 브랜드, 제품 또는 기타 키워드로 후보 기업을 검색합니다.

주요 매개변수:

• matchKeyword(필수): 기업 약칭 또는 관련 키워드.

• pageIndex(선택): 페이지 번호, 1부터 시작.

• pageSize(선택): 기본 10, 최대 50.

반환: 후보 기업 total/resultList. 기업을 확인한 후에는 기업 전체 이름, 기업 ID 또는 통합사회신용코드를 우선적으로 기업 상품, 브랜드 및 채널 Tool에 전달합니다.

2. goods_search

기능: 소매 상품 또는 해외 온라인 스토어를 검색하여 상품 선정, 상품 발견 및 해외 채널 필터링에 사용합니다.

주요 매개변수:

• matchKeyword(선택): 상품명, 스토어명 또는 상품 키워드.

• source(선택): retail 소매 상품; overseas 해외 온라인 스토어. 기본 retail.

• pageIndex(선택): 페이지 번호, 1부터 시작.

• pageSize(선택): 최대 50; 소매 검색 기본 10, 해외 검색 기본 50.

• eshopSource, eshopCategories, eshopSalesLevel(선택): 해외 온라인 스토어 검색에만 사용.

• operationStatus, hasAssociateEnterprise(선택): 해외 온라인 스토어 상태 및 연관 기업 필터링.

반환: total 및 resultList.

3. goods_enterprise_products

기능: 기업별 소매 상품 또는 전자상거래 상품을 조회하며, 상품 자격 검증, 기업 상품 목록 정리 및 경쟁사 조사에 적합합니다.

주요 매개변수:

• matchKeyword(필수): 기업 이름, 기업 ID, 등록번호 또는 통합사회신용코드.

• productType(선택): retail 기업 소매 상품; ecommerce 기업 전자상거래 상품. 기본 retail.

• keywordType(선택): name, nameId, regNumber 또는 socialCreditCode.

• pageIndex(선택): 페이지 번호, 1부터 시작.

• pageSize(선택): 소매 상품 최대 10, 기본 10; 전자상거래 상품 최대 50, 기본 50.

소매 상품 반환 필드:

• 상품명, 상품 바코드, 등록일

• 기업 이름, 기업 ID

• 브랜드 이름, GPC 분류

전자상거래 상품 반환 필드:

• 상품명, 이미지 링크, 가격, 상품 출처

4. goods_overseas_store_products

기능: 해외 온라인 스토어 ID로 스토어 상품 카탈로그를 조회합니다.

주요 매개변수:

• storeId(필수): goods_search(source=overseas)에서 반환된 스토어 _id.

• pageIndex, pageSize(선택): MCP 로컬 페이지네이션, pageSize 최대 50.

반환: 상품 수, 리뷰, BSR, 카테고리, 상품명 및 링크 등의 정보를 반환하며 total/resultList로 통일합니다.

5. goods_brand

기능: 뷰티 산업 기업 브랜드 상세 또는 브랜드 제품 효능 개요를 조회합니다.

주요 매개변수:

• matchKeyword(필수): 기업 식별자.

• view(선택): brand_detail 브랜드 상세; product_overview 제품 효능 개요.

• keywordType(선택): 기업 식별자 유형.

6. goods_channel

기능: 기업의 국내 전자상거래 스토어 목록 또는 국내외 온라인 스토어 전체 상세를 조회합니다.

주요 매개변수:

• matchKeyword(필수): 기업 식별자.

• source(선택): domestic_store 국내 전자상거래 스토어; global_store 국내외 온라인 스토어.

• keywordType(선택): 기업 식별자 유형.

• pageIndex, pageSize(선택): 국내 스토어에만 사용, pageSize 최대 50.

사용 시나리오

1. 기업 식별: 약칭, 브랜드 또는 제품 키워드로 후보 기업과 안정적인 식별자를 찾습니다.

2. 상품 발견: 상품 키워드로 소매 상품을 발견하거나, 상품 및 플랫폼으로 해외 온라인 스토어를 필터링합니다.

3. 기업 상품 목록 정리: 기업의 소매 상품 바코드, 브랜드, GPC 분류 및 전자상거래 상품 가격을 조회합니다.

4. 상품 자격 검증: 기업 식별자로 상품 주체를 찾아 상품명, 바코드 및 등록 정보를 확인합니다.

5. 해외 경쟁사 조사: 해외 온라인 스토어 검색에서 특정 스토어의 상품 카탈로그로 진입하여 카테고리와 BSR을 분석합니다.

6. 브랜드 분석: 뷰티 산업 기업의 브랜드, 주력 제품 및 제품 효능 구성을 파악합니다.

7. 채널 분석: 기업의 국내 전자상거래 스토어와 국내외 온라인 스토어 구성을 비교합니다.

사용 시 주의사항

1. 단일 데이터 소스 호출: 한 번의 호출은 source, productType 또는 view에서 선택한 하나의 Product ID만 접근합니다.

2. 페이지네이션 제한: 기업 소매 상품 pageSize 최대 10; 기타 페이지네이션 Tool 최대 50.

3. 약칭 처리: 기업 약칭으로 직접 조회할 수 없는 경우 먼저 goods_enterprise_search를 호출합니다.

4. 식별자 우선순위: 후보를 확인한 후에는 기업 ID 또는 통합사회신용코드를 우선 사용합니다.

5. 해외 스토어 ID: storeId는 반드시 해외 온라인 스토어 검색 결과에서 가져와야 하며, 기업 이름으로 대체할 수 없습니다.

6. 빈 결과: total=0, resultList=[]는 정상적인 비즈니스 결과입니다.

7. 기능 범위: 이 서비스는 더 이상 스토어 인기 상품, 월간 매출액, 누적 판매량 또는 판매 추이 조회를 제공하지 않습니다.

사용 질문 예시

goods_enterprise_search

1. "小米"에 해당하는 기업은 무엇인가요?

2. "格力"를 통해 정확한 기업 이름과 기업 ID를 찾아주세요.

goods_search

1. 소매 시장에서 커피 상품을 찾아주세요. 먼저 10건을 보여주세요.

2. coffee를 판매하는 亚马逊 해외 온라인 스토어를 검색하세요.

goods_enterprise_products

1. "小米科技有限责任公司"의 소매 상품 이름, 바코드 및 브랜드를 조회하세요.

2. 특정 기업이 전자상거래 플랫폼에 게시한 상품 이름, 가격 및 출처를 확인하세요.

goods_overseas_store_products

1. 이 해외 온라인 스토어의 상품 카탈로그와 BSR을 확인하세요.

2. 지정된 해외 스토어의 상품과 리뷰 수를 페이지별로 나열하세요.

goods_brand

1. "上海家化联合股份有限公司"의 브랜드 상세를 조회하세요.

2. "欧莱雅（中国）有限公司"의 브랜드 제품 효능 개요를 분석하세요.

goods_channel

1. "珠海格力电器股份有限公司"에는 어떤 국내 전자상거래 스토어가 있나요?

2. "北京京东世纪贸易有限公司"는 국내외에 어떤 온라인 스토어 채널이 있나요?

테스트 검증

python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -v

단위 테스트는 Mock HTTP 응답을 사용하며 실제 HandaaS 상품 인터페이스를 호출하지 않습니다.