Sakenowa

幫你裝上數位味覺 🍶

English | 正體中文

---

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）