makeup.land

Revendedora profissional de cosméticos israelense — pesquisa semântica de catálogo multilíngue, correspondência de tons ranqueada por ΔE com enriquecimento de shade_match por produto, carteira do cliente, carrinho, pedidos e cartões-presente.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP makeup.land

Metadados públicos + guia do integrador para o servidor Model Context Protocol makeup.land.

A makeup.land é uma varejista israelense profissional de cosméticos. Nosso servidor MCP permite que agentes de IA (Claude Desktop, Cursor, navegação do ChatGPT, aplicativos LangGraph, integrações personalizadas) naveguem em nosso catálogo, consultem clientes, busquem carrinhos e verifiquem cartões-presente — tudo por meio da interface JSON-RPC padrão do Model Context Protocol.

O servidor MCP está hospedado em https://makeup.land/api/mcp como um endpoint Streamable-HTTP (versão do protocolo 2025-06-18, sem estado). As ferramentas de catálogo funcionam anonimamente; as ferramentas de dados do cliente exigem um token bearer emitido via shop@makeup.land.

Este repositório é a face pública da integração — o servidor é executado a partir do nosso código-fonte privado da loja, mas tudo o que um integrador precisa (inventário de ferramentas, modelo de autenticação, trechos de conexão, envelopes de erro) está aqui.

O que você pode fazer com ele

Ferramenta	O que retorna	Autenticação
`list_products`	Navegação no catálogo: pesquisa semântica multilíngue (`q`), correspondência de tons classificada por ΔE (`near_hex`, retorna `shade_match: {hex, delta_e}` por produto), filtros por marca / hebraico exato, ordenação por preço / popularidade / classificação com encolhimento bayesiano	Anônima
`validate_gift_card`	Saldo do cartão-presente	Pública (protegida pelo código do cartão-presente)
`list_brands`	Todas as marcas que vendemos — B Cosmic da Yossi Bitton, pincéis da Vinci (Defet), INGLOT, NYX e dezenas de outras	Bearer
`get_customer`	Perfil do cliente, carteira de créditos ℳ, nível do M Club	Bearer
`get_cart`	Carrinho mais recente do cliente com projeção de recompensa por item + total	Bearer + telefone
`list_orders`	Pedidos recentes do cliente com status em 6 eixos	Bearer + telefone
`list_payment_links`	Solicitações de pagamento pendentes em pedidos não pagos	Bearer + telefone
`get_customer_best_deals`	Projeções de ofertas personalizadas com base em tags + nível do M Club	Bearer + telefone

Início rápido

Pelo 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 }
    }
  }'

Pelo Claude Desktop

Use a ponte mcp-remote (o Claude Desktop lê MCP via stdio; isso faz a ponte para nosso endpoint HTTP):

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

Acesso anônimo somente ao catálogo (pule o bearer):

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

Pelo Cursor

O Cursor lê de ~/.cursor/mcp.json (ou .cursor/mcp.json por espaço de trabalho). Mesma estrutura do Claude Desktop acima.

Marcas que vendemos

O catálogo abrange cerca de 150 marcas. Alguns destaques:

Yossi Bitton (B Cosmic) — linha profissional israelense de maquiagem do estilista Yossi Bitton. A makeup.land é a loja online oficial.
da Vinci (Defet) — distribuidor autorizado em Israel dos pincéis profissionais de maquiagem da da Vinci, fabricados na Alemanha.
Yarin Shahaf — parceiro entre catálogos (yarin-shahaf.co.il/מייקאפלנד).
INGLOT, NYX, Bourjois, Maybelline, L'Oréal e mais de 140 outras.

Use list_brands para enumerar todas em tempo de execução.

Correspondência de tons ΔE

O recurso principal. Cada variante do nosso catálogo traz cores hexadecimais de amostra; o argumento near_hex da ferramenta list_products executa uma classificação por distância perceptual (CIE ΔE 2000), para que um agente possa responder "encontre um batom parecido com #C2185B" em uma única chamada. Combine com hue_family=warm|cool|neutral para refinar.

Cada produto retornado traz um campo shade_match: {hex, delta_e} que identifica a amostra da variante mais próxima e sua distância perceptual — assim, em uma paleta de 40 tons, você sabe qual tom específico foi a correspondência (e quão próxima ela é), não apenas qual paleta.

Essa é a superfície que torna o servidor MCP da makeup.land exclusivamente útil para agentes de compras — nenhum outro varejista israelense de cosméticos expõe correspondência de tons via MCP, e pouquíssimos varejistas no mundo expõem isso de alguma forma.

Pesquisa de catálogo multilíngue

Envie q (linguagem natural) em vez de tag para consultas por categoria. q é uma pesquisa semântica multilíngue — q="lipstick", q="שפתון" e q="lápiz labial" retornam batons com tags em hebraico. O conjunto de produtos exibido pode variar entre os idiomas da consulta (o sistema classifica por relevância semântica, não por canonicalização de idioma), mas cada um é uma página válida de batom. tag é um filtro literal de string apenas contra tags armazenadas em hebraico; palavras de categoria em inglês não corresponderão a ele.

Autenticação

Modo	Quando é necessário	Como
Anônimo	`list_products` (somente filtros de catálogo), `validate_gift_card`	Nada — basta chamar
Bearer	Todas as ferramentas de dados do cliente, `list_brands`	`Authorization: Bearer ml_<hex>`
Bearer + telefone	`get_cart`, `list_orders`, `list_payment_links`, `get_customer_best_deals`	O bearer autentica quem chama (integração de parceiro); o telefone (E.164) seleciona o cliente

A autenticação bearer NÃO é OAuth, apesar da autodetecção do Smithery — os tokens são emitidos fora de banda por e-mail. Solicite um escrevendo para shop@makeup.land com seu caso de uso de integração.

Por que bearer + telefone?

O identificador de telefone (?phone=+972...) seleciona de qual cliente os recursos serão retornados. O bearer autentica quem está chamando. Nenhum dos dois é suficiente sozinho — o bearer sozinho não pode enumerar registros de clientes, e um telefone sozinho retorna 401 Unauthorized. Esse é o contrato da API REST V1; o servidor MCP corresponde exatamente a ele.

Envelope de erro

Os erros de ferramenta são propagados do envelope de erro REST V1 como conteúdo de texto com isError: true:

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

Os valores estáveis de error_code estão documentados na especificação OpenAPI (components.schemas.Error). Códigos comuns:

unauthorized — bearer ausente ou inválido
scope_mismatch — token com escopo errado para a ferramenta
read_only_token — gravação tentada com token somente leitura
customer_not_found — telefone não corresponde a nenhum cliente
endpoint_not_found — erro de digitação ou caminho V1 removido
insufficient_stock — variante sem estoque (relevante quando ferramentas de mutação forem lançadas)
insufficient_credits — saldo da carteira não cobre uma compra com créditos

Limitações da v1

Somente leitura. Sem gravação de carrinho, sem resgate de cartão-presente, sem registro de cliente. A v2 adiciona esses recursos.
Sem estado. Cada solicitação inicializa uma nova sessão MCP.
Síncrona. tools/call bloqueia na busca interna V1. A maioria das chamadas retorna em <500ms; a pesquisa semântica pode levar até 2s.
Sem streaming SSE para resultados parciais.

Superfícies de descoberta

Superfície	URL
Manifesto de descoberta MCP	https://makeup.land/.well-known/mcp.json
Cartão de agente A2A	https://makeup.land/.well-known/agent-card.json
Especificação OpenAPI 3.1	https://makeup.land/openapi.json
Manifesto de habilidade de autenticação	https://makeup.land/auth.md
Manual completo	https://makeup.land/llms-full.txt
Metadados de recurso OAuth	https://makeup.land/.well-known/oauth-protected-resource
Metadados de servidor OAuth	https://makeup.land/.well-known/oauth-authorization-server

Listado em

Smithery
Registro oficial MCP (como land.makeup/v1)
Guia do integrador makeup.land

Contato

Solicitações de token: shop@makeup.land
Relatórios de bugs + solicitações de recursos: abra uma issue neste repositório
Dúvidas gerais: shop@makeup.land

Licença

Os metadados e a documentação deste repositório são distribuídos sob MIT para que possam ser redistribuídos por agregadores de catálogo MCP.

O servidor MCP subjacente, a loja makeup.land e nosso catálogo de produtos permanecem proprietários — consulte makeup.land/terms-of-service.