shoplazza-mcp

Implementación en Python que envuelve Shoplazza OpenAPI（REST） como un servicio MCP (Model Context Protocol), permitiendo que clientes compatibles con MCP como Claude, Cursor, DSH, etc. puedan leer y escribir directamente datos de tiendas Shoplazza (productos, pedidos, clientes, inventario, descuentos, suscripción a webhooks, etc.).

El catálogo de endpoints (data/endpoints.json) se genera automáticamente desde la documentación oficial mediante tools/scrape_endpoints.py, cubriendo un total de 311 endpoints reales y 46 grupos de recursos de la versión 2026-01.

Características

Instalación

Requisitos: Python ≥ 3.10, uv (recomendado) o pip.

cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）

Si no usas uv:

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .

Configuración

Proporciona las credenciales mediante variables de entorno (no escribas las claves en el código ni las subas al repositorio):

# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token

* Basta con elegir una de estas dos opciones: la configuración de tienda única SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN, o la configuración multi-tienda SHOPLAZZA_STORES. Si se establecen ambas, SHOPLAZZA_SHOP_DOMAIN es la tienda predeterminada.

Consulta el ejemplo completo en .env.example.

Uso multi-tienda

Después de configurar varias tiendas, cada herramienta de API del servicio tendrá un parámetro opcional adicional shop_domain:

export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'

• Sin shop_domain → se usa la tienda predeterminada (SHOPLAZZA_SHOP_DOMAIN, o el primer elemento de STORES).

• Con shop_domain → se usa la tienda especificada (si la tienda es desconocida, se mostrará un error y se listarán las tiendas configuradas).

• shoplazza_list_shops → muestra todas las tiendas configuradas en el servicio y la tienda predeterminada.

• Cada tienda tiene su propio Access-Token y su propio bucket de limitación de velocidad (de acuerdo con la regla oficial de limitación por tienda), y las tiendas no se bloquean entre sí.

Ejemplo de conversación:

"Consulta el volumen de pedidos de hoy en la tienda US y luego mira los 5 productos más vendidos en la tienda DE" → El modelo llamará a shoplazza_orders / shoplazza_products con shop_domain=us.myshoplazza.com y shop_domain=de.myshoplazza.com respectivamente.

Ejemplo de configuración de Claude Desktop (multi-tienda):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}

Permisos de API necesarios (scope)

Al crear/instalar una aplicación en el Centro de socios o al autorizar una tienda, solicita solo los scopes que vayas a usar según el "principio del mínimo privilegio". Para consultar datos usa read_*; solo añade el write_* correspondiente si necesitas modificar:

Combinación recomendada para operaciones de solo lectura: read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data. Después de la autorización, puedes invocar la herramienta shoplazza_oauth_access_scopes para verificar los scopes realmente otorgados en esta instalación. Consulta la asignación completa oficial en Ámbitos de acceso.

Cómo obtener un Access Token

• Aplicaciones públicas: sigue el flujo de OAuth 2.0 Authorization Code, intercambia code por access_token (válido por 1 año; se puede renovar con refresh_token).

• Integración privada / interna: genera los tokens de acceso correspondientes para la aplicación y la tienda en el panel de administración de Shoplazza.

Ejecución

stdio (cliente MCP local, predeterminado)

uv run shoplazza-mcp

HTTP (servicio remoto)

uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765

La ruta del endpoint es /mcp por defecto; se puede cambiar con --http-path.

Conexión con clientes MCP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor: añade el servidor en Configuración → MCP; la configuración está en examples/mcp-cursor.json.

HTTP remoto (cualquier cliente): apunta url a http://host:8765/mcp.

También puedes ejecutarlo directamente (debug para ver la lista de herramientas y la interacción JSON-RPC):

uv run mcp dev shoplazza-mcp

Ejemplos de uso (conversaciones en Claude / Cursor, etc.)

• "Lista los 10 pedidos más recientes de la tienda".

• "Consulta el inventario del producto abcd-1234".

• "Cancela el pedido order-xxx con el motivo customer requested".

• "Crea un descuento de 20 sobre 100".

• "¿Qué API hay para hacer reembolsos? Busca endpoints" → El modelo llamará a shoplazza_search_endpoints("refund") y luego invocará automáticamente el endpoint correspondiente.

Todas las respuestas devuelven el paquete original de la API: {code, message, data, api_call_limit}; las respuestas de tipo lista incluyen cursor / pre_cursor en data, y se pueden paginar con los parámetros page_size / per_page.

Desarrollo y mantenimiento

• tools/scrape_endpoints.py: extrae de la página de documentación oficial de endpoints y genera data/endpoints.json (incluye method / path / parámetros / campos del cuerpo de la solicitud / estructura de la respuesta de cada endpoint).

• Mantenimiento ágil: para añadir o quitar "herramientas comunes", solo hay que modificar la lista CURATED_SLUGS en shoplazza_mcp/tools.py.

• scripts/smoke_test.py: prueba de humo sin conexión (stdio); scripts/http_smoke_test.py: prueba de humo HTTP.

Notas de seguridad

• Inyecta el Access Token solo mediante variables de entorno / configuración del cliente; no lo escribas en el repositorio de código.

• El servicio solo usa HTTPS (la normativa oficial exige que todos los endpoints se accedan únicamente por HTTPS).

• Si lo expones como servicio HTTP a Internet, colócalo en una red interna de confianza o añade tu propia autenticación (por ejemplo, pasarela o firewall).

Licencia

MIT