rogertheunissenmerge-oss

@sommelierx/mcp-server

为 AI 助手提供葡萄酒搭配智能。将 Claude、Cursor、Windsurf 或任何兼容 MCP 的客户端连接到侍酒师级别的搭配算法，为食材、菜肴和食谱匹配葡萄酒。

快速开始

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"]
    }
  }
}

就这么简单。向 Claude 提问 “烤鲑鱼搭配什么葡萄酒？”，它就会使用 SommelierX 给出答案。

使用 Pro API 密钥

用于提取食谱、进行多人菜品搭配以及查看评分明细：

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": {
        "SOMMELIERX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / 其他 MCP 客户端

相同的配置也适用。将 command 和 args 添加到客户端的 MCP 设置中。

可用工具

工具	功能	级别
pair_wine_with_ingredients	为食材列表推荐葡萄酒（例如“鲑鱼、柠檬、莳萝”）	免费
pair_wine_with_meal	为菜名推荐葡萄酒（例如“蘑菇烩饭”）	免费
find_meals_for_wine	查找适合某种葡萄酒风格的菜肴（例如“Barolo”）	免费
search_ingredients	搜索食材数据库	免费
search_meals	搜索菜肴数据库	免费
pair_wine_with_recipe_url	从食谱 URL 提取食材并搭配葡萄酒	Pro
group_pairing	为多道菜寻找最合适的葡萄酒（例如三道菜晚餐）	Pro

身份验证

SommelierX 支持两种身份验证方式。可以任选其一，无需同时配置。

选项 1：API 密钥（订阅）

在 MCP 客户端配置中设置 SOMMELIERX_API_KEY 环境变量。密钥格式为 sk_live_...。根据所属级别（Free / Pro / Enterprise），你将获得每月调用额度。

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": {
        "SOMMELIERX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

在 api.sommelierx.com 获取 API 密钥。

选项 2：x402 支付（按次付费）

无需 API 密钥。你的 AI Agent 通过 Coinbase x402 协议，使用 Base 网络上的 USDC 按次付费。如果请求中没有 API 密钥，服务会返回带有支付载荷的 402 Payment Required 响应。兼容 x402 的 Agent 会自动处理。

以下场景尤其适用：

• 自行管理钱包的 AI Agent
• 无需订阅、按需付费
• Agent 间交易（无需人工介入）

定价（每次调用）

工具	价格	级别
pair_wine_with_meal	$0.01	免费
find_meals_for_wine	$0.01	免费
search_ingredients	$0.005	免费
search_meals	$0.005	免费
pair_wine_with_ingredients	$0.02	Pro
pair_wine_with_recipe_url	$0.02	Pro
group_pairing	$0.03	Pro

使用 API 密钥时，调用次数会从所属级别的额度中扣除。使用 x402 时，每次调用按所列价格收费。

对话示例

基础搭配：

“鲑鱼、芦笋和荷兰酱适合搭配什么葡萄酒？”

反向搭配：

“我有一瓶 Barolo。应该做什么菜？”

食谱 URL：

“这道食谱搭配什么葡萄酒？https://www.allrecipes.com/recipe/...”

晚宴：

“我计划安排一顿三道菜的晚餐：凯撒沙拉、羊排和巧克力慕斯。哪种葡萄酒适合搭配所有菜？”

工作原理

1. 你向 AI 助手询问葡萄酒相关问题
2. 助手调用相应的 SommelierX 工具
3. MCP 服务将你的输入转换为结构化 API 调用
4. SommelierX 的搭配算法（17 个食物 DNA 维度 × 19 个葡萄酒 DNA 维度）计算匹配结果
5. 根据真实侍酒师专业知识，为你提供带评分的葡萄酒推荐

食材解析

使用 pair_wine_with_ingredients 时，服务会自动将自然语言食材名称解析为数据库条目。AI 助手无需了解数据库 ID，可直接传入食材名称。

配置

环境变量	必需	默认值	说明
SOMMELIERX_API_KEY	否	--	用于 Pro/Enterprise 访问的 API 密钥。不提供密钥时，使用免费套餐（每天 50 次调用）。
SOMMELIERX_API_URL	否	https://api.sommelierx.com	API 基础 URL。
SOMMELIERX_LANGUAGE	否	en	结果的默认语言（en、nl、fr、de、es、it）。

API 套餐

套餐	每日限额	每分钟限额	功能
Free	50 次调用	2 次/分钟	基础搭配、搜索、食材/餐食查询
Pro（$49/mo）	500 次调用	20 次/分钟	+ 食谱 URL 提取、分组搭配、评分细分
Enterprise	10,000 次调用	100 次/分钟	+ 自定义限额、SLA

前往 api.sommelierx.com 获取 API 密钥。

API 文档

完整的 API 文档请见 docs.sommelierx.com。

OpenAPI 规范位于 https://api.sommelierx.com/api/v1/openapi.json。

开发

npm install
npm run build
npm run dev       # development mode with hot reload
npm run typecheck # type checking without emit

要求

• Node.js >= 18.0.0

许可证

MIT