shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

alko-mcp

一个生产级的MCP服务器，为AI助手提供芬兰Alko酒精产品目录的访问功能，包括产品搜索、库存查询、店铺信息和个性化推荐。

article

README

🚀 Alko MCP 服务器

Alko MCP 服务器是一个生产级的 模型上下文协议 (MCP) 服务器，它能让 AI 助手访问 Alko.fi 的酒精产品目录。

🚀 快速开始

前提条件

  • Node.js 24+
  • Google Cloud Firestore（本地开发可使用模拟器）
  • Playwright（用于网页抓取，会自动安装）

安装步骤

# 克隆仓库
git clone https://github.com/yourusername/alko-mcp.git
cd alko-mcp

# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium

# 构建项目
npm run build

使用 Firestore 模拟器进行本地开发

步骤 1：启动 Firestore 模拟器（保持在后台运行）

gcloud emulators firestore start --host-port=localhost:8081

步骤 2：启动 Claude Desktop（或其他 AI 助手）

如果模拟器为空，MCP 服务器会在首次查询时自动加载捆绑的种子数据（约 12,000 种产品，约 360 家商店），无需手动同步！

注意：模拟器不会持久保存数据。重启模拟器后，首次使用时会再次自动加载种子数据。

可选：同步最新数据

如果需要从 Alko.fi 获取最新的产品数据：

export FIRESTORE_EMULATOR_HOST=localhost:8081

# 从 Excel 同步最新产品数据（约 30 秒）
npm run sync-data

# 从网站同步最新商店数据（约 2 分钟）
npm run sync-stores

# 导出到种子文件（用于与团队共享）
npm run export-seed

✨ 主要特性

  • 产品搜索：可按名称、类型、国家、价格范围、酒精含量等搜索 11,900 多种产品。
  • 产品详情：获取详细信息，包括丰富的数据（口味特征、食物搭配、证书、饮用建议）。
  • Vivino 评分：通过名称或 URL 获取 Vivino.com 上的葡萄酒评分。
  • 商店营业时间：通过“现在营业”筛选查看商店营业时间。
  • 商店库存情况：通过网页抓取检查 Alko 商店的实时库存情况。
  • 产品推荐：根据食物搭配、场合和偏好获取产品推荐。
  • 商店列表：按城市浏览 360 多家 Alko 商店。

所有工具都返回紧凑的 JSON 数据，以高效使用大语言模型（LLM）的令牌。

💻 使用示例

基本搜索

> **为我寻找价格低于 20 欧元的优质意大利红葡萄酒**
> *搜索价格低于 20 欧元的意大利红葡萄酒*

葡萄酒推荐

> **为烤三文鱼推荐一款葡萄酒，预算约 15 - 25 欧元。**
> *在预算范围内为烤三文鱼推荐葡萄酒*

香槟和起泡酒

> **Alko 有哪些香槟可供选择？请展示 5 个最佳选项。**
> *列出香槟选项*

精酿啤酒搜索

> **搜索来自芬兰或其他北欧国家的印度淡色艾尔（IPA）啤酒**
> *搜索北欧的 IPA 啤酒*

产品详情

> **提供编号为 906458 的产品的更多信息**
> *获取带有口味特征的详细产品信息*

商店营业时间

> **赫尔辛基现在有哪些 Alko 商店正在营业？**
> *列出赫尔辛基现在正在营业的商店*

商店库存情况

> **赫尔辛基的商店是否有巴罗洛葡萄酒？**
> *检查赫尔辛基商店中产品的库存情况*

礼品推荐

> **为葡萄酒爱好者寻找礼品创意，预算 50 - 100 欧元。**
> *为葡萄酒爱好者提供高级礼品创意*

食物搭配（使用 Alko 的官方搭配数据）

> **为海鲜推荐一款葡萄酒**
> *使用 Alko 的食物符号搜索，查找官方标记为适合与海鲜搭配的产品*

> **我需要一款适合奶酪拼盘的葡萄酒。奶酪有：布里干酪、曼彻格干酪和蓝纹奶酪。**
> *为奶酪拼盘搭配葡萄酒 - 匹配“温和奶酪”和“浓郁奶酪”*

特定地区搜索

> **搜索来自里奥哈地区的西班牙红葡萄酒**
> *搜索里奥哈地区的西班牙葡萄酒*

预算购物

> **寻找价格低于 10 欧元的适合工作日晚餐的最佳葡萄酒**
> *为工作日晚餐寻找最佳预算葡萄酒*

特殊场合

> **为 20 人的新年派对推荐一款起泡酒**
> *为新年派对推荐起泡酒*

Vivino 评分

> **搜索价格在 15 - 25 欧元之间的红葡萄酒，并查看它们的 Vivino 评分**
> *搜索红葡萄酒并查看它们的 Vivino 评分*

评分最高的葡萄酒

> **Alko 中在 Vivino 上评分最高的巴罗洛葡萄酒是哪一款？**
> *查找巴罗洛葡萄酒并比较它们的 Vivino 评分*

葡萄酒比较

> **比较这些葡萄酒的 Vivino 评分：阿玛罗尼、蒙塔希诺布鲁奈罗**
> *比较优质意大利葡萄酒的 Vivino 评分*

📚 详细文档

MCP 工具

| 工具 | 描述 | |------|-------------| | search_products | 按名称、类型、国家、价格范围、酒精含量搜索产品 | | get_product | 获取产品详情。设置 includeEnrichedData=true 可获取口味、食物搭配、饮用提示 | | get_store_hours | 获取商店营业时间。可按城市、名称或 openNow=true 进行过滤。如果数据过时会自动刷新 | | get_availability | 检查产品在商店的库存情况（通过抓取 alko.fi） | | list_stores | 按城市列出 Alko 商店 | | get_recommendations | 获取个性化产品推荐 | | get_vivino_rating | 通过名称或 URL 获取 Vivino 葡萄酒评分（通过抓取 vivino.com） | | sync_products | 使数据库与最新的 Alko 价格列表同步 | | get_sync_status | 检查同步状态和产品数量 |

AI 助手配置

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 本地开发：

{
  "mcpServers": {
    "alko": {
      "command": "node",
      "args": ["/absolute/path/to/alko-mcp/dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

生产环境（Cloud Run）：

{
  "mcpServers": {
    "alko": {
      "url": "https://YOUR-CLOUD-RUN-URL.run.app/mcp",
      "transport": "streamable-http"
    }
  }
}

ChatGPT Desktop

配置文件：~/.config/chatgpt/mcp.json（macOS/Linux）或 %APPDATA%\chatgpt\mcp.json（Windows） 本地开发：

{
  "servers": {
    "alko": {
      "command": "node",
      "args": ["/absolute/path/to/alko-mcp/dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

生产环境（Cloud Run）：

{
  "servers": {
    "alko": {
      "url": "https://YOUR-CLOUD-RUN-URL.run.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Google Gemini（AI Studio）

对于 Gemini，使用 HTTP 传输。使用以下命令启动服务器：

MCP_TRANSPORT=http PORT=3000 node dist/server.js

然后在 AI Studio 中使用 MCP 端点 URL 进行配置：

http://localhost:3000/mcp

在生产环境中，部署到 Cloud Run 并使用 API 令牌进行身份验证（见下文）。

Claude Code CLI

添加到项目的 .mcp.json 文件中：

{
  "mcpServers": {
    "alko": {
      "command": "node",
      "args": ["./dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

数据来源

产品目录

  • 来源：Alko 的公开 Excel 价格列表
  • URL：https://www.alko.fi/INTERSHOP/static/WFS/Alko-OnlineShop-Site/-/Alko-OnlineShop/fi_FI/Alkon%20Hinnasto%20Tekstitiedostona/alkon-hinnasto-tekstitiedostona.xlsx
  • 产品数量：约 11,900 种
  • 更新方式：运行 npm run sync-data

商店数据

  • 来源：从 alko.fi 商店查找器抓取
  • 商店数量：约 360 家
  • 包含信息：名称、地址、营业时间（今天/明天）
  • 更新方式：运行 npm run sync-stores

丰富的产品数据

  • 来源：从单个产品页面抓取
  • 包含信息：口味特征、使用提示、饮用建议、食物搭配、证书、成分
  • 缓存方式：首次抓取后持久保存到 Firestore

产品字段

| 字段 | 描述 | |-------|-------------| | id | 产品 ID（例如，"004246"） | | name | 产品名称 | | producer | 生产商/制造商 | | price | 价格（欧元） | | pricePerLiter | 每升价格 | | bottleSize | 容量（例如，"0.75 l"） | | type | 类别（红葡萄酒、白葡萄酒、啤酒等） | | subtype | 风味特征（例如，"醇厚 & 清爽"） | | country | 原产国 | | region | 葡萄酒产区 | | alcoholPercentage | 酒精含量 | | description | 来自 Excel 的口味描述 | | tasteProfile | 详细口味（丰富数据，抓取而来） | | usageTips | 使用建议（丰富数据） | | servingSuggestion | 饮用温度（丰富数据） | | foodPairings | 食物搭配符号（丰富数据） | | certificates | 认证标签：有机、素食等（丰富数据） | | ingredients | 生产商声明的成分（丰富数据） | | assortment | 常规产品、订购产品等 |

🔧 技术细节

开发命令

npm run build        # 编译 TypeScript
npm run dev          # 在 tsx 监视模式下运行
npm run test         # 在监视模式下运行测试
npm run test:run     # 运行一次测试（232 个测试）
npm run typecheck    # 类型检查
npm run sync-data    # 从 Excel 同步产品数据
npm run sync-stores  # 从网站抓取商店数据
npm run export-seed  # 将数据导出到种子文件（包含差异）

日志查看

tail -f /tmp/alko-mcp.log

部署到 Google Cloud Run

服务器可以部署到 Cloud Run 并提供公共访问（无需身份验证），以与 ChatGPT 和其他 MCP 客户端兼容。

# 启用 API
gcloud services enable run.googleapis.com firestore.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

# 创建 Firestore 数据库
gcloud firestore databases create --location=europe-north1

# 使用 Cloud Build 进行部署
gcloud builds submit --config=cloudbuild.yaml

# 或者直接从源代码部署
gcloud run deploy alko-mcp \
  --source . \
  --region europe-north1 \
  --memory 2Gi \
  --cpu 2 \
  --execution-environment gen2 \
  --set-env-vars="MCP_TRANSPORT=http" \
  --allow-unauthenticated

测试端点：

curl -X POST https://alko-mcp-xxx.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

有关 API 令牌身份验证和其他选项，请参阅 DEPLOYMENT.md。

📄 许可证

本项目采用 MIT 许可证。

法律声明

  • Alko 价格列表是公开可用的数据。
  • 网页抓取遵守速率限制（请求间隔 2 秒）。
  • 这是一个非官方项目，与 Alko Oy 没有关联。
  • 在芬兰，只有 18 岁以上的人才能购买酒精产品。
help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client