Alko MCP

🚀 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 工具

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

產品字段

🔧 技術細節

開發命令

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 歲以上的人才能購買酒精產品。