清酒風味感受器 (Sakenowa MCP)

幫你裝上數位味覺 🍶

English

Overview

A Model Context Protocol (MCP) server that transforms the Sakenowa Open Dataset into a flavor-space search engine for Japanese sake. Query by name, explore six-axis flavor profiles, discover similar bottles, and compare sake side-by-side—all powered by vector mathematics in taste space.

Key Features

🍶 500+ Japanese Sake Brands — Comprehensive coverage with flavor profiles
📊 6-Axis Flavor Profiles — Floral, Mellow, Rich, Calm, Light, Dry dimensions
🔍 Fuzzy Search — Find sake by brand name or brewery (supports kanji & kana)
🎯 Smart Similarity Matching — Discover taste-alikes or deliberate contrasts
📈 Directional Flavor Exploration — Find sake that is "like this, but drier/richer/lighter"
🔄 Auto-Refresh Cache — Weekly TTL with stale-serve fallback
🔒 Multi-Process Safe — Atomic snapshot-based caching with cross-process isolation

Installation

git clone https://github.com/mame0001/sakenowa-mcp.git
cd sakenowa-mcp
uv sync
uv run sakenowa-mcp

5 Core Tools

Tool	Purpose
`sync_sakenowa_data(force=False)`	Fetch/refresh dataset; report scale & freshness
`search_sake(query, limit=10, area="")`	Find sake by name or brewery
`get_sake_profile(brand_id)`	ASCII radar, flavor tags, 4-type estimate, ranks
`find_similar_sake(brand_id, mode, limit=5)`	★ Find taste-alikes by flavor vector (7 directional modes)
`compare_sake(brand_ids=[...])`	Side-by-side comparison (2–5 sake, 6 axes)

Testing

uv run pytest -xvs
# Expected: 11/11 tests pass

Contributing

See CONTRIBUTING.md for development setup and code standards.

Architecture

See ARCHITECTURE.md for system design, data flow, and scalability.

Data Source & License

Sakenowa Data Project — https://sakenowa.com (© Sakenowa, CC-BY 4.0)

MIT License. See LICENSE.

Note: Dataset excludes rice polishing ratio, variety, SMV, ABV, price, grade, vintage. Never invent these fields.

正體中文版本

清酒風味搜尋引擎（第一個清酒 MCP）

輸入一支喝過的酒，找「像這支，但更乾爽」或「完全相反」的酒款。不用記牌子，用味覺找。

5 大功能

🍶 500+ 清酒品牌 — 涵蓋完整風味檔案
🔍 模糊搜尋 — 品牌名、釀造廠都能查（支援漢字、假名）
🎯 風味相似度 — 找「這支的姊妹酒」或「完全相反的選擇」
📈 風味探索 — 「像這支，但更乾／更濃／更輕」一句話找酒
📊 並排對比 — 2~5 支酒側邊欄比較，一眼看出差異

快速開始

git clone https://github.com/mame0001/sakenowa-mcp.git
cd sakenowa-mcp
uv sync
uv run sakenowa-mcp

5 個工具

工具	用途
`sync_sakenowa_data()`	更新清酒資料庫
`search_sake()`	查品牌名、釀造廠
`get_sake_profile()`	看風味輪廓、排名
`find_similar_sake()`	★ 根據風味找相似酒
`compare_sake()`	並排對比多支酒

驗證安裝

uv run pytest -xvs
# 預期：11/11 測試通過

開發 & 架構

CONTRIBUTING.md — 本地開發、提交 PR
ARCHITECTURE.md — 系統設計、風味向量數學

開源授權

MIT License（資料源於 Sakenowa 開放資料集，CC-BY 4.0）