makeup.land

makeup.land MCP 服务

makeup.land Model Context Protocol 服务的公开元数据与集成指南。

makeup.land 是一家以色列专业化妆品零售商。我们的 MCP 服务让 AI Agent（Claude Desktop、Cursor、ChatGPT 浏览、LangGraph 应用、自定义集成）能够浏览商品目录、查询客户、获取购物车并查看礼品卡，所有操作均通过 Model Context Protocol 的标准 JSON-RPC 接口完成。

MCP 服务托管在 https://makeup.land/api/mcp，作为 Streamable-HTTP 端点运行（协议版本 2025-06-18，无状态）。商品目录工具可匿名使用；客户数据工具需要通过 [email protected] 获取的 bearer token。

此仓库是集成的公开入口——服务运行于我们的私有店面代码库，但集成者所需的一切（工具清单、身份验证模式、连接代码片段、错误封装）都在这里。

可以用它做什么

工具	返回内容	身份验证
list_products	浏览商品目录：跨语言语义搜索（q）、按 ΔE 排序的色号匹配（near_hex，为每件商品返回 shade_match: {hex, delta_e}）、品牌／精确希伯来语标签筛选、按价格／人气／贝叶斯收缩评分排序	匿名
validate_gift_card	礼品卡余额	公开（需提供礼品卡代码）
list_brands	我们经营的所有品牌——Yossi Bitton 的 B Cosmic、da Vinci (Defet) 化妆刷、INGLOT、NYX 等数十个品牌	Bearer
get_customer	客户资料、ℳ-credit 钱包、M Club 等级	Bearer
get_cart	客户最近的购物车，包含每个商品行和总计的奖励预估	Bearer + phone
list_orders	客户近期订单及 6 轴状态	Bearer + phone
list_payment_links	未付款订单的待处理付款请求	Bearer + phone
get_customer_best_deals	根据标签和 M Club 等级生成的个性化优惠预估	Bearer + phone

快速入门

从终端开始

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

从 Claude Desktop 开始

使用 mcp-remote 桥接器（Claude Desktop 通过 stdio 读取 MCP；此桥接器会连接到我们的 HTTP 端点）：

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

仅匿名访问商品目录（跳过 bearer）：

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

从 Cursor 开始

Cursor 从 ~/.cursor/mcp.json（或工作区专属的 .cursor/mcp.json）读取配置。格式与上面的 Claude Desktop 相同。

我们经营的品牌

商品目录涵盖约 150 个品牌。以下是其中一些：

• Yossi Bitton (B Cosmic) — 由造型师 Yossi Bitton 创立的以色列专业化妆品系列。makeup.land 是其官方在线商店。
• da Vinci (Defet) — da Vinci 德国制造专业化妆刷的以色列授权经销商。
• Yarin Shahaf — 跨商品目录合作伙伴（yarin-shahaf.co.il/מייקאפלנד）。
• INGLOT、NYX、Bourjois、Maybelline、L'Oréal 等 140 多个品牌。

使用 list_brands 可在运行时列出所有品牌。

ΔE 色号匹配

这是我们的旗舰功能。商品目录中的每个款式都带有色样十六进制颜色；list_products 工具的 near_hex 参数会按感知距离（CIE ΔE 2000）排序，让 Agent 一次调用即可回答“找一支看起来像 #C2185B 的口红”。搭配 hue_family=warm|cool|neutral 可进一步缩小范围。

每件返回的商品都带有 shade_match: {hex, delta_e} 字段，用于标识最接近的款式色样及其感知距离——因此，对于含 40 种色号的调色盘，你不仅能知道匹配的是哪个调色盘，还能知道具体匹配了哪种色号以及相似程度。

正是这一特性让 makeup.land 的 MCP 服务对购物 Agent 独具价值——在以色列，没有其他化妆品零售商通过 MCP 提供色号匹配，而在全球范围内，提供此功能的零售商也寥寥无几。

跨语言目录搜索

分类查询时，请发送自然语言参数 q，而不是 tag。q 是跨语言语义搜索——q="lipstick"、q="שפתון" 和 q="lápiz labial" 都会返回带有希伯来语标签的口红。不同查询语言可能会显示不同的商品集合（系统按语义相关性排序，而非按语言规范化排序），但返回的每个页面都是有效的口红商品页。tag 仅对存储为希伯来语的标签进行字面字符串筛选；英文分类词不会匹配。

身份验证

模式	何时需要	方式
匿名	list_products（仅目录筛选）、validate_gift_card	无需任何操作，直接调用
Bearer	所有客户数据工具、list_brands	Authorization: Bearer ml_<hex>
Bearer + 电话号码	get_cart、list_orders、list_payment_links、get_customer_best_deals	Bearer 用于验证调用方身份（合作伙伴集成）；电话号码（E.164）用于选择客户

尽管 Smithery 自动检测为 OAuth，Bearer 身份验证并非 OAuth——令牌通过电子邮件在带外签发。请将你的集成用例发送至 [email protected] 申请令牌。

为什么需要 Bearer + 电话号码？

电话号码标识符（?phone=+972...）用于选择要返回哪位客户的资源。Bearer 用于验证谁在发起调用。两者缺一不可——仅凭 Bearer 无法枚举客户记录，仅凭电话号码则会返回 401 Unauthorized。这是 V1 REST API 的约定；MCP 服务完全遵循这一约定。

错误封装

工具错误会从我们的 V1 REST 错误封装中传递为文本内容，并设置 isError: true：

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

稳定的 error_code 值记录在 OpenAPI 规范的 components.schemas.Error 中。常见代码：

• unauthorized — 缺少 Bearer 或 Bearer 无效
• scope_mismatch — 令牌的作用域与工具不匹配
• read_only_token — 使用只读令牌尝试写入
• customer_not_found — 电话号码与任何客户都不匹配
• endpoint_not_found — V1 路径拼写错误或已移除
• insufficient_stock — 商品变体缺货（发布可变更数据的工具后适用）
• insufficient_credits — 钱包余额不足以支付使用积分结算的购买

v1 的限制

• 只读。 不支持写入购物车、兑换礼品卡或注册客户。v2 将添加这些功能。
• 无状态。 每个请求都会初始化一个全新的 MCP 会话。
• 同步。 tools/call 会等待 V1 内部请求完成后再返回。大多数调用耗时不到 500ms；语义搜索最长可能需要 2s。
• 不支持 SSE 流式传输部分结果。

发现入口

入口	URL
MCP 发现清单	https://makeup.land/.well-known/mcp.json
A2A Agent 卡片	https://makeup.land/.well-known/agent-card.json
OpenAPI 3.1 规范	https://makeup.land/openapi.json
身份验证技能清单	https://makeup.land/auth.md
完整手册	https://makeup.land/llms-full.txt
OAuth 资源元数据	https://makeup.land/.well-known/oauth-protected-resource
OAuth 服务元数据	https://makeup.land/.well-known/oauth-authorization-server

收录平台

• Smithery
• 官方 MCP Registry（名称为 land.makeup/v1）
• makeup.land 集成指南

联系方式

• 令牌申请： [email protected]
• 错误报告和功能请求： 在此仓库中提交 issue
• 一般咨询： [email protected]

许可证

此仓库中的元数据和文档采用 MIT 许可证发布，以便 MCP 目录聚合器重新分发。

底层 MCP 服务、makeup.land 店面和我们的商品目录仍为专有内容——请参阅 makeup.land/terms-of-service。