内容
# SommelierX 中式葡萄酒搭配智能服务端
适用于 AI 助手的葡萄酒搭配智能。连接 Claude、Cursor、Windsurf 或任何兼容 MCP 的客户端到 SommelierX 级别的搭配算法，该算法可根据您的食材、菜肴和食谱匹配葡萄酒。
## 快速开始
### Claude 桌面版
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"sommelierx": {
"command": "npx",
"args": ["@sommelierx/mcp-server"]
}
}
}
```
就这样。询问 Claude _"什么葡萄酒适合烤鲑鱼？"_ 它将使用 SommelierX 来回答。
### 使用专业 API 密钥
对于食谱提取、分组配对和评分细目：
```json
{
"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` | 为葡萄酒风格（例如“巴罗洛”）找到搭配的菜肴 | 免费 |
| `search_ingredients` | 搜索食材数据库 | 免费 |
| `search_meals` | 搜索菜肴数据库 | 免费 |
| `pair_wine_with_recipe_url` | 从食谱 URL 中提取食材并搭配葡萄酒 | 专业 |
| `group_pairing` | 为多道菜（例如 3 道菜的晚餐）找到最佳葡萄酒 | 专业 |
## 身份验证
SommelierX 支持两种身份验证方法。您可以同时使用任意一种。
### 选项 1：API 密钥（订阅）
在 MCP 客户端配置中设置 `SOMMELIERX_API_KEY` 环境变量。密钥格式为 `sk_live_...`。根据您的等级（免费/专业/企业），您将获得每月的调用额度。
```json
{
"mcpServers": {
"sommelierx": {
"command": "npx",
"args": ["@sommelierx/mcp-server"],
"env": {
"SOMMELIERX_API_KEY": "sk_live_your_key_here"
}
}
}
}
```
在 [api.sommelierx.com](https://api.sommelierx.com) 获取您的 API 密钥。
### 选项 2：x402 支付（按次付费）
无需 API 密钥。您的 AI 代理使用 Base 网络上的 USDC 通过 [Coinbase x402 协议](https://www.x402.org/) 按次支付。当请求缺少 API 密钥时，服务器返回 `402 Payment Required` 响应，并附带支付负载。兼容 x402 的代理会自动处理此操作。
这适用于：
- 管理自己的钱包的 AI 代理
- 无订阅的按次使用
- 代理到代理的商务（无需人工介入）
### 定价（每次调用）
| 工具 | 价格 | 等级 |
|------|-------|------|
| `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 | 专业 |
| `pair_wine_with_recipe_url` | $0.02 | 专业 |
| `group_pairing` | $0.03 | 专业 |
使用 API 密钥时，调用次数将从您的等级额度中扣除。使用 x402 时，每次调用将按列出的价格收费。
## 示例对话
**基本搭配：**
> “什么葡萄酒适合鲑鱼、芦笋和荷兰酱？”
**反向搭配：**
> “我有一瓶巴罗洛葡萄酒。我应该做什么菜？”
**食谱 URL：**
> “这道食谱的葡萄酒搭配是什么？https://www.allrecipes.com/recipe/..."
**晚餐聚会：**
> “我正在计划一个 3 道菜的晚餐：凯撒沙拉、羔羊排和巧克力慕斯。所有课程都适用哪种葡萄酒？”
## 工作原理
1. 您向 AI 助手提出葡萄酒相关问题
2. 助手调用相应的 SommelierX 工具
3. MCP 服务器将您的输入转换为结构化的 API 调用
4. SommelierX 的搭配算法（17 种食物 DNA 维度 x 19 种葡萄酒 DNA 维度）计算匹配结果
5. 根据专业的侍酒师经验，您将获得评分的葡萄酒推荐
### 食材解析
当您使用 `pair_wine_with_ingredients` 时，服务器会自动将自然语言的食材名称解析为数据库条目。AI 助手不需要知道数据库 ID - 它可以直接传递食材名称。
## 配置
| 环境变量 | 是否必需 | 默认值 | 描述 |
|---------------------|----------|---------|-------------|
| `SOMMELIERX_API_KEY` | 否 | - | 专业/企业访问的 API 密钥。无密钥时使用免费等级（每天 50 次调用）。 |
| `SOMMELIERX_API_URL` | 否 | `https://api.sommelierx.com` | API 基本 URL。 |
| `SOMMELIERX_LANGUAGE` | 否 | `en` | 结果的默认语言（`en`、`nl`、`fr`、`de`、`es`、`it`）。 |
## API 等级
| 等级 | 每日限制 | 每分钟限制 | 功能 |
|------|------------|------------------|----------|
| **免费** | 50 次调用 | 2 次/分钟 | 基本搭配、搜索、食材/菜肴查找 |
| **专业**（$49/月） | 500 次调用 | 20 次/分钟 | + 食谱 URL 提取、分组搭配、评分细目 |
| **企业** | 10,000 次调用 | 100 次/分钟 | + 自定义限制、SLA |
在 [api.sommelierx.com](https://api.sommelierx.com) 获取您的 API 密钥
## API 文档
完整的 API 文档可在 [docs.sommelierx.com](https://docs.sommelierx.com) 获取。
OpenAPI 规范在 `https://api.sommelierx.com/api/v1/openapi.json` 处提供。
## 开发
```bash
npm install
npm run build
npm run dev # 开发模式，热重载
npm run typecheck # 类型检查，无输出
```
## 要求
- Node.js >= 18.0.0
## 许可证
MIT
