Сервис больших данных о товарах

Этот MCP-сервис предоставляет возможности поиска по ключевым словам предприятий, поиска товаров, товаров предприятий, товаров зарубежных магазинов, брендов и каналов электронной коммерции, помогая пользователям проводить подбор товаров, исследование конкурентов, проверку соответствия товаров и анализ каналов.

Основные функции

• 🏢 Поиск по сокращённым наименованиям предприятий и ключевым словам

• 🔍 Поиск розничных товаров и зарубежных интернет-магазинов

• 🧾 Запрос розничных товаров предприятий и товаров электронной коммерции

• 🌍 Запрос каталога товаров зарубежных магазинов

• 🏷️ Анализ брендов и эффективности продуктов предприятий бьюти-индустрии

• 🛒 Анализ каналов отечественных и глобальных интернет-магазинов

Related MCP server: Enterprise Operation Insight MCP Server

Примечания по проектированию сервиса

• Сервис предоставляет 6 инструментов в соответствии с реальными сценариями использования, а не раскладывает инструменты по количеству вышестоящих API.

• Если пользователь указывает только сокращённое наименование предприятия, сначала используйте goods_enterprise_search, чтобы получить полное наименование или стабильный ID.

• Товары предприятия и товары зарубежных магазинов предоставляются отдельными инструментами, чтобы один и тот же параметр не выражал разные объекты в разных источниках.

• goods_enterprise_products позволяет выбрать розничные товары или товары электронной коммерции, но за один вызов обращается только к одному Product ID.

• Для розничных товаров предприятия — максимум 10 записей на страницу; для остальных постраничных запросов — максимум 50 записей на страницу.

• Внешний слой бизнес-результатов постраничных запросов единообразно представлен полями total и resultList.

• Удалена возможность получения хитов магазина, месячных продаж и накопленных продаж, зависящая от сторонних товаров; инструменты для цен и трендов продаж больше не регистрируются.

• При успешном выполнении инструмент возвращает бизнес-data, извлечённую через HandaaS Integrator Gateway.

Требования к окружению

• 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 и активации интегратора. Реальные учётные данные следует хранить только в локальном .env или в секретах развёртывания.

Доступные инструменты и Product ID

1. goods_enterprise_search

Функция: поиск предприятий-кандидатов по сокращённому наименованию, бренду, товару или другим ключевым словам.

Основные параметры:

• matchKeyword (обязательный): сокращённое наименование предприятия или связанное ключевое слово.

• pageIndex (необязательный): номер страницы, начиная с 1.

• pageSize (необязательный): по умолчанию 10, максимум 50.

Возвращает: total/resultList предприятий-кандидатов. После подтверждения предприятия предпочтительно передавать полное наименование, ID предприятия или единый код социального кредита в инструменты товаров, брендов и каналов.

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 (обязательный): _id интернет-магазина, возвращённый goods_search(source=overseas).

• 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. Один источник данных за вызов: один вызов обращается только к одному Product ID, выбранному через source, productType или view.

2. Ограничения пагинации: для розничных товаров предприятия pageSize максимум 10; для остальных постраничных инструментов — максимум 50.

3. Обработка сокращённых наименований: если сокращённое наименование предприятия нельзя запросить напрямую, сначала вызовите goods_enterprise_search.

4. Приоритет идентификаторов: после подтверждения кандидата предпочтительно используйте ID предприятия или единый код социального кредита.

5. ID зарубежного магазина: storeId должен быть получен из результатов поиска зарубежных интернет-магазинов; его нельзя заменять наименованием предприятия.

6. Пустые результаты: total=0, resultList=[] — это допустимый бизнес-результат.

7. Границы возможностей: сервис больше не предоставляет запросы хитов магазина, месячного объёма продаж, накопленного объёма продаж или трендов продаж.

Примеры запросов

goods_enterprise_search

1. Каким предприятиям соответствует «Xiaomi»?

2. Помогите найти точное наименование предприятия и ID предприятия по запросу «Gree».

goods_search

1. Найдите розничные товары категории «кофе», покажите первые 10 записей.

2. Найдите зарубежные интернет-магазины Amazon, продающие coffee.

goods_enterprise_products

1. Запросите названия, штрих-коды и бренды розничных товаров Xiaomi Technology Co., Ltd.

2. Посмотрите названия, цены и источники товаров, опубликованных предприятием на платформах электронной коммерции.

goods_overseas_store_products

1. Посмотрите каталог товаров и BSR этого зарубежного интернет-магазина.

2. Выведите постранично товары и количество отзывов указанного зарубежного магазина.

goods_brand

1. Запросите детализацию бренда Shanghai Jahwa United Co., Ltd.

2. Проанализируйте обзор эффективности продуктов бренда L'Oréal (China) Co., Ltd.

goods_channel

1. Какие отечественные магазины электронной коммерции есть у Gree Electric Appliances, Inc. of Zhuhai?

2. Какие отечественные и зарубежные интернет-каналы есть у Beijing JD Century Trading Co., Ltd.?

Тестирование и проверка

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

Модульные тесты используют Mock HTTP-ответы и не вызывают реальный интерфейс товаров HandaaS.