makeup.land

Minorista profesional de cosméticos israelí: búsqueda semántica multilingüe en el catálogo, coincidencia de tonos clasificada por ΔE con enriquecimiento de shade_match por producto, billetera del cliente, carrito, pedidos y tarjetas de regalo.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de makeup.land

Metadatos públicos + guía para integradores del servidor makeup.land del Model Context Protocol.

makeup.land es un minorista profesional de cosméticos israelí. Nuestro servidor MCP permite a los agentes de IA (Claude Desktop, Cursor, navegación de ChatGPT, aplicaciones LangGraph, integraciones personalizadas) explorar nuestro catálogo, consultar clientes, obtener carritos y verificar tarjetas de regalo, todo a través de la interfaz JSON-RPC estándar del Model Context Protocol.

El servidor MCP está alojado en https://makeup.land/api/mcp como un endpoint Streamable-HTTP (versión de protocolo 2025-06-18, sin estado). Las herramientas de catálogo funcionan de forma anónima; las herramientas de datos de clientes requieren un token de portador emitido a través de shop@makeup.land.

Este repositorio es la cara pública de la integración: el servidor se ejecuta desde nuestro código de tienda privado, pero todo lo que un integrador necesita (inventario de herramientas, modelo de autenticación, fragmentos de conexión, envoltorios de error) vive aquí.

Qué puedes hacer con él

Herramienta	Qué devuelve	Autenticación
`list_products`	Exploración de catálogo: búsqueda semántica multilingüe (`q`), coincidencia de tonos clasificada por ΔE (`near_hex`, devuelve `shade_match: {hex, delta_e}` por producto), filtros por marca / etiqueta hebrea exacta, ordenar por precio / popularidad / calificación con contracción bayesiana	Anónimo
`validate_gift_card`	Saldo de tarjeta de regalo	Público (restringido por el código de la tarjeta de regalo)
`list_brands`	Todas las marcas que ofrecemos: B Cosmic de Yossi Bitton, pinceles da Vinci (Defet), INGLOT, NYX y docenas más	Portador
`get_customer`	Perfil del cliente, billetera de crédito ℳ, nivel M Club	Portador
`get_cart`	Carrito más reciente del cliente con proyección de recompensa por línea y total	Portador + teléfono
`list_orders`	Pedidos recientes del cliente con estado de 6 ejes	Portador + teléfono
`list_payment_links`	Solicitudes de pago pendientes en pedidos no pagados	Portador + teléfono
`get_customer_best_deals`	Proyecciones de ofertas personalizadas basadas en etiquetas + nivel M Club	Portador + teléfono

Inicio rápido

Desde la terminal

# Anonymous catalog browse — find lipsticks similar to a target shade
curl -X POST https://makeup.land/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": { "near_hex": "#C2185B", "q": "lipstick", "limit": 5 }
    }
  }'

# List all Yossi Bitton (B Cosmic) products — bearer required
curl -X POST https://makeup.land/api/mcp \
  -H 'Authorization: Bearer ml_<your-token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": { "brand": "yossi-bitton", "limit": 20 }
    }
  }'

Desde Claude Desktop

Usa el puente mcp-remote (Claude Desktop lee MCP a través de stdio; esto conecta con nuestro endpoint HTTP):

{
  "mcpServers": {
    "makeup.land": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://makeup.land/api/mcp",
        "--header", "Authorization:Bearer ml_<your-token>"
      ]
    }
  }
}

Acceso anónimo solo de catálogo (omite el portador):

{
  "mcpServers": {
    "makeup.land": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://makeup.land/api/mcp"]
    }
  }
}

Desde Cursor

Cursor lee desde ~/.cursor/mcp.json (o por espacio de trabajo .cursor/mcp.json). Misma forma que Claude Desktop arriba.

Marcas que ofrecemos

El catálogo abarca ~150 marcas. Algunos destacados:

Yossi Bitton (B Cosmic) — Línea de maquillaje profesional israelí del estilista Yossi Bitton. makeup.land es la tienda oficial en línea.
da Vinci (Defet) — Distribuidor israelí autorizado de los pinceles cosméticos profesionales de fabricación alemana de da Vinci.
Yarin Shahaf — Socio de catálogo cruzado (yarin-shahaf.co.il/מייקאפלנד).
INGLOT, NYX, Bourjois, Maybelline, L'Oréal y más de 140 más.

Usa list_brands para enumerarlos todos en tiempo de ejecución.

Coincidencia de tonos ΔE

La característica principal. Cada variante de nuestro catálogo tiene colores hex de muestra; el argumento near_hex de la herramienta list_products ejecuta una clasificación por distancia perceptual (CIE ΔE 2000) para que un agente pueda responder "encuentra un lápiz labial que se parezca a #C2185B" en una sola llamada. Combínalo con hue_family=warm|cool|neutral para refinar.

Cada producto devuelto lleva un campo shade_match: {hex, delta_e} que identifica la muestra de variante más cercana y su distancia perceptual, de modo que en una paleta de 40 tonos sabes qué tono específico fue la coincidencia (y qué tan cerca está), no solo qué paleta.

Esta es la superficie que hace que el servidor MCP de makeup.land sea especialmente útil para agentes de compras: ningún otro minorista de cosméticos israelí expone la coincidencia de tonos a través de MCP, y muy pocos minoristas a nivel mundial lo exponen en absoluto.

Búsqueda de catálogo multilingüe

Envía q (lenguaje natural) en lugar de tag para búsquedas por categoría. q es una búsqueda semántica multilingüe: q="lipstick", q="שפתון" y q="lápiz labial" devuelven cada uno lápices labiales etiquetados en hebreo. El conjunto de productos mostrados puede diferir entre idiomas de consulta (el sistema clasifica por relevancia semántica, no por canonización de idioma), pero cada uno es una página válida de lápiz labial. tag es un filtro de cadena literal solo contra etiquetas almacenadas en hebreo; las palabras de categoría en inglés no coincidirán.

Autenticación

Modo	Cuándo se requiere	Cómo
Anónimo	`list_products` (solo filtros de catálogo), `validate_gift_card`	Nada: solo llama
Portador	Todas las herramientas de datos de clientes, `list_brands`	`Authorization: Bearer ml_<hex>`
Portador + teléfono	`get_cart`, `list_orders`, `list_payment_links`, `get_customer_best_deals`	El portador autentica al llamante (integración de socio); el teléfono (E.164) selecciona al cliente

La autenticación de portador NO es OAuth a pesar de la autodetección de Smithery: los tokens se emiten fuera de banda por correo electrónico. Solicita uno escribiendo a shop@makeup.land con tu caso de uso de integración.

¿Por qué portador + teléfono?

El identificador de teléfono (?phone=+972...) selecciona de qué cliente se devuelven los recursos. El portador autentica quién llama. Ninguno por sí solo es suficiente: el portador solo no puede enumerar registros de clientes, y un teléfono solo devuelve 401 Unauthorized. Este es el contrato de la API REST V1; el servidor MCP lo cumple exactamente.

Envoltura de error

Los errores de las herramientas se propagan desde nuestra envoltura de error REST V1 como contenido de texto con isError: true:

{
  "content": [{
    "type": "text",
    "text": "{ \"error\": \"...\", \"error_code\": \"...\" }"
  }],
  "isError": true
}

Los valores estables de error_code están documentados en la especificación OpenAPI (components.schemas.Error). Códigos comunes:

unauthorized — portador faltante o inválido
scope_mismatch — el token tiene un alcance incorrecto para la herramienta
read_only_token — se intentó escribir con un token de solo lectura
customer_not_found — el teléfono no coincide con ningún cliente
endpoint_not_found — error tipográfico o ruta V1 eliminada
insufficient_stock — variante agotada (relevante una vez que se lancen herramientas de mutación)
insufficient_credits — el saldo de la billetera no puede cubrir una compra con créditos

Limitaciones de v1

Solo lectura. Sin escrituras de carrito, sin canje de tarjetas de regalo, sin registro de clientes. v2 agrega esto.
Sin estado. Cada solicitud inicializa una sesión MCP nueva.
Síncrono. tools/call se bloquea en la búsqueda interna V1. La mayoría de las llamadas devuelven <500ms; la búsqueda semántica puede tardar hasta 2s.
Sin transmisión SSE para resultados parciales.

Superficies de descubrimiento

Superficie	URL
Manifiesto de descubrimiento MCP	https://makeup.land/.well-known/mcp.json
Tarjeta de agente A2A	https://makeup.land/.well-known/agent-card.json
Especificación OpenAPI 3.1	https://makeup.land/openapi.json
Manifiesto de habilidad de autenticación	https://makeup.land/auth.md
Manual extenso	https://makeup.land/llms-full.txt
Metadatos de recurso OAuth	https://makeup.land/.well-known/oauth-protected-resource
Metadatos de servidor OAuth	https://makeup.land/.well-known/oauth-authorization-server

Listado en

Smithery
Registro oficial de MCP (como land.makeup/v1)
Guía de integración de makeup.land

Contacto

Solicitudes de token: shop@makeup.land
Informes de errores + solicitudes de funciones: abre un problema en este repositorio
Consultas generales: shop@makeup.land

Licencia

Los metadatos y la documentación de este repositorio se publican bajo MIT para que puedan ser redistribuidos por agregadores de catálogos MCP.

El servidor MCP subyacente, la tienda de makeup.land y nuestro catálogo de productos siguen siendo propietarios; consulta makeup.land/terms-of-service.