Servicio de Big Data de Productos

Este servicio MCP ofrece capacidades de búsqueda por palabras clave de empresas, búsqueda de productos, productos de empresa, productos de tiendas en el extranjero, marcas y canales de comercio electrónico, para ayudar a los usuarios en la selección de productos, investigación de competencia, verificación de calificaciones de productos y análisis de canales.

Funciones principales

• 🏢 Búsqueda por nombre abreviado de empresa y palabras clave

• 🔍 Búsqueda de productos minoristas y tiendas en línea en el extranjero

• 🧾 Consulta de productos minoristas y de comercio electrónico de empresas

• 🌍 Consulta de catálogo de productos de tiendas en el extranjero

• 🏷️ Análisis de marcas y eficacia de productos de empresas de belleza

• 🛒 Análisis de canales de tiendas en línea nacionales y globales

Related MCP server: Enterprise Operation Insight MCP Server

Notas de diseño del servicio

• El servicio ofrece 6 herramientas según el objeto de uso real, sin desplegar herramientas por número de API upstream.

• Cuando el usuario solo proporciona el nombre abreviado de la empresa, use primero goods_enterprise_search para obtener el nombre completo o un ID estable de la empresa.

• Los productos de empresa y los productos de tiendas en el extranjero se ofrecen como herramientas independientes para evitar que el mismo parámetro exprese objetos diferentes en distintas fuentes.

• goods_enterprise_products permite elegir entre productos minoristas o de comercio electrónico, pero cada llamada accede a un solo Product ID.

• Los productos minoristas de empresa tienen un máximo de 10 por página; el resto de consultas paginadas tienen un máximo de 50 por página.

• La capa externa de negocio de los resultados paginados se unifica en total y resultList.

• Se han eliminado las capacidades de productos más vendidos, ventas mensuales y ventas acumuladas de tiendas que dependían de productos de terceros; ya no se registran herramientas de precios ni tendencias de ventas.

• Cuando la herramienta tiene éxito, devuelve el data de negocio extraído por HandaaS Integrator Gateway.

Requisitos del entorno

• Python 3.10+

• Paquetes de dependencias: python-dotenv, requests, mcp

Inicio rápido local

1. Entrar en el directorio del proyecto

cd goods-mcp-server

2. Crear un entorno virtual e instalar dependencias

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

3. Configurar las variables de entorno

cp .env.example .env

Edite .env:

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

HANDAAS_REQUEST_TIMEOUT es una configuración opcional, en segundos, con un valor predeterminado de 30.

4. Iniciar el servicio

python server/mcp_server.py streamable-http

La dirección predeterminada del servicio es http://localhost:8000/mcp.

También puede usar:

./start_mcp_server.sh streamable-http

Se admiten tres modos de inicio: stdio, sse y streamable-http.

5. Configuración de Cursor / Cherry Studio

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

Instalación e implementación de la versión STDIO

Reemplace {workdir} por la ruta absoluta del proyecto:

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

INTEGRATOR_ID, SECRET_ID y SECRET_KEY se obtienen tras iniciar sesión en HandaaS, registrarse y activar el integrador. Las credenciales reales solo deben guardarse en el .env local o en secretos de implementación.

Herramientas disponibles y Product ID

1. goods_enterprise_search

Función: Busca empresas candidatas por nombre abreviado, marca, producto u otras palabras clave.

Parámetros principales:

• matchKeyword (obligatorio): nombre abreviado de la empresa o palabra clave relacionada.

• pageIndex (opcional): número de página, comenzando en 1.

• pageSize (opcional): valor predeterminado 10, máximo 50.

Devuelve: total/resultList de empresas candidatas. Tras confirmar la empresa, priorice pasar el nombre completo, el ID de empresa o el código de crédito social unificado a las herramientas de productos, marcas y canales de la empresa.

2. goods_search

Función: Busca productos minoristas o tiendas en línea en el extranjero para selección de productos, descubrimiento de productos y filtrado de canales transfronterizos.

Parámetros principales:

• matchKeyword (opcional): nombre del producto, nombre de la tienda en línea o palabra clave de producto.

• source (opcional): retail para productos minoristas; overseas para tiendas en línea en el extranjero. Valor predeterminado: retail.

• pageIndex (opcional): número de página, comenzando en 1.

• pageSize (opcional): máximo 50; la búsqueda minorista usa 10 por defecto y la búsqueda en el extranjero usa 50 por defecto.

• eshopSource, eshopCategories, eshopSalesLevel (opcionales): solo se usan en la búsqueda de tiendas en línea en el extranjero.

• operationStatus, hasAssociateEnterprise (opcionales): filtros por estado de la tienda en línea en el extranjero y empresa asociada.

Devuelve: total y resultList.

3. goods_enterprise_products

Función: Consulta productos minoristas o de comercio electrónico por empresa, adecuado para verificación de calificaciones de productos, inventario de productos de empresa e investigación de competencia.

Parámetros principales:

• matchKeyword (obligatorio): nombre de la empresa, ID de empresa, número de registro o código de crédito social unificado.

• productType (opcional): retail para productos minoristas de empresa; ecommerce para productos de comercio electrónico de empresa. Valor predeterminado: retail.

• keywordType (opcional): name, nameId, regNumber o socialCreditCode.

• pageIndex (opcional): número de página, comenzando en 1.

• pageSize (opcional): productos minoristas máximo 10, predeterminado 10; productos de comercio electrónico máximo 50, predeterminado 50.

Campos devueltos para productos minoristas:

• Nombre del producto, código de barras del producto, fecha de publicación

• Nombre de la empresa, ID de empresa

• Nombre de la marca, clasificación GPC

Campos devueltos para productos de comercio electrónico:

• Nombre del producto, enlace de imagen, precio, origen del producto

4. goods_overseas_store_products

Función: Consulta el catálogo de productos de una tienda por ID de tienda en línea en el extranjero.

Parámetros principales:

• storeId (obligatorio): el _id de la tienda en línea devuelto por goods_search(source=overseas).

• pageIndex, pageSize (opcionales): paginación local de MCP, pageSize máximo 50.

Devuelve: información como cantidad de productos, comentarios, BSR, categoría, nombre y enlace del producto, unificada en total/resultList.

5. goods_brand

Función: Consulta el detalle de marca de una empresa de belleza o el resumen de eficacia de los productos de la marca.

Parámetros principales:

• matchKeyword (obligatorio): identificador de la empresa.

• view (opcional): brand_detail para detalle de marca; product_overview para resumen de eficacia de productos.

• keywordType (opcional): tipo de identificador de empresa.

6. goods_channel

Función: Consulta la lista de tiendas de comercio electrónico nacionales de la empresa o el detalle global de tiendas en línea nacionales y extranjeras.

Parámetros principales:

• matchKeyword (obligatorio): identificador de la empresa.

• source (opcional): domestic_store para tiendas de comercio electrónico nacionales; global_store para tiendas en línea nacionales y extranjeras.

• keywordType (opcional): tipo de identificador de empresa.

• pageIndex, pageSize (opcionales): solo para tiendas nacionales, pageSize máximo 50.

Casos de uso

1. Localización de empresas: encuentre empresas candidatas e identificadores estables mediante nombre abreviado, marca o palabras clave de producto.

2. Descubrimiento de productos: descubra productos minoristas por palabra clave de producto o filtre tiendas en línea en el extranjero por producto y plataforma.

3. Inventario de productos de empresa: consulte códigos de barras, marcas, clasificación GPC de productos minoristas y precios de productos de comercio electrónico de la empresa.

4. Verificación de calificaciones de productos: use el identificador de la empresa para localizar el titular del producto y verifique el nombre, el código de barras y la información de publicación.

5. Investigación de competencia transfronteriza: desde la búsqueda de tiendas en línea en el extranjero, acceda al catálogo de productos de una tienda específica y analice categorías y BSR.

6. Análisis de marcas: conozca las marcas de empresas de belleza, sus productos principales y la distribución de eficacia de productos.

7. Análisis de canales: compare las tiendas de comercio electrónico nacionales y la distribución de tiendas en línea nacionales y extranjeras de la empresa.

Notas de uso

1. Llamada de una sola fuente de datos: cada llamada accede a un solo Product ID seleccionado mediante source, productType o view.

2. Límites de paginación: pageSize máximo 10 para productos minoristas de empresa; máximo 50 para el resto de herramientas paginadas.

3. Manejo de nombres abreviados: si el nombre abreviado de la empresa no se puede consultar directamente, llame primero a goods_enterprise_search.

4. Prioridad de identificadores: tras confirmar el candidato, priorice el uso del ID de empresa o el código de crédito social unificado.

5. ID de tienda en el extranjero: storeId debe provenir de los resultados de búsqueda de tiendas en línea en el extranjero; no se puede sustituir por el nombre de la empresa.

6. Resultados vacíos: total=0 y resultList=[] son resultados comerciales válidos.

7. Alcance de capacidades: este servicio ya no ofrece consultas de productos más vendidos, ventas mensuales, ventas acumuladas ni tendencias de ventas de tiendas.

Ejemplos de preguntas de uso

goods_enterprise_search

1. ¿Qué empresas corresponden a "小米"?

2. Ayúdame a encontrar el nombre exacto de la empresa y su ID mediante "格力".

goods_search

1. Ayúdame a buscar productos de café en el mercado minorista, muestra primero 10 resultados.

2. Busca tiendas en línea en el extranjero de 亚马逊 que vendan coffee.

goods_enterprise_products

1. Consulta el nombre, el código de barras y la marca de los productos minoristas de 小米科技有限责任公司.

2. Consulta el nombre, el precio y el origen de los productos publicados por una empresa en plataformas de comercio electrónico.

goods_overseas_store_products

1. Consulta el catálogo de productos y el BSR de esta tienda en línea en el extranjero.

2. Enumera por páginas los productos y el número de comentarios de la tienda en el extranjero especificada.

goods_brand

1. Consulta el detalle de marca de 上海家化联合股份有限公司.

2. Analiza el resumen de eficacia de los productos de marca de 欧莱雅（中国）有限公司.

goods_channel

1. ¿Qué tiendas de comercio electrónico nacionales tiene 珠海格力电器股份有限公司?

2. ¿Qué canales de tiendas en línea, nacionales y extranjeros, tiene 北京京东世纪贸易有限公司?

Pruebas y verificación

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

Las pruebas unitarias utilizan respuestas HTTP simuladas (Mock) y no llaman a la interfaz real de productos de HandaaS.