<p align="center"><img src="assets/logo.jpg" width="120" alt="上九 · Shangjiu" /></p>

# 上九国威知识库 MCP

上九中国威士忌知识库 MCP · Shangjiu Chinese Whisky Knowledge Base MCP

> **让世界喝懂中国威士忌的开源 AI 插件**

**国威品鉴 · 选酒导购 · 产区图谱 · 内容生成 ｜ 面向国产威士忌的 MCP 工具**

<p align="center">
  <img alt="GitHub stars" src="https://img.shields.io/github/stars/1281227309-art/shangjiu?style=flat-square&logo=github" />
  <img alt="GitHub forks" src="https://img.shields.io/github/forks/1281227309-art/shangjiu?style=flat-square&logo=github" />
  <img alt="License" src="https://img.shields.io/github/license/1281227309-art/shangjiu?style=flat-square" />
  <img alt="npm version" src="https://img.shields.io/npm/v/shangjiu-guowei-knowledge-mcp?style=flat-square&logo=npm" />
  <img alt="GitHub Pages" src="https://img.shields.io/badge/live-在线-2ea44f?style=flat-square" />
</p>

## 🌏 在线体验

> **<https://1281227309-art.github.io/shangjiu/>** —— 一眼看懂「上九 · 国威知识库」是什么、能做什么，以及如何接入你的 AI 宿主。

<!-- Glama 元数据：以下信息供自动化索引（mcp / knowledge-base / license / homepage / code） -->
<table>
  <tr>
    <td><b>类型</b></td>
    <td>MCP Server（stdio · Node.js）</td>
    <td><b>License</b></td>
    <td>MIT</td>
  </tr>
  <tr>
    <td><b>领域</b></td>
    <td>中国威士忌 · 知识库</td>
    <td><b>落地页</b></td>
    <td><a href="https://1281227309-art.github.io/shangjiu/">1281227309-art.github.io/shangjiu</a></td>
  </tr>
  <tr>
    <td><b>关键词</b></td>
    <td colspan="3">`mcp` · `chinese-whisky` · `knowledge-base` · `data-funnel` · `选酒导购` · `品鉴`</td>
  </tr>
</table>

<p align="center">
  <a href="https://github.com/1281227309-art/shangjiu">⭐ GitHub</a> ·
  <a href="https://github.com/1281227309-art/shangjiu#readme">README</a> ·
  <a href="./LICENSE">License</a> ·
  <a href="https://github.com/1281227309-art/shangjiu/fork">Fork</a> ·
  <a href="https://1281227309-art.github.io/shangjiu/">🌏 在线落地页</a> ·
  <a href="./china_whisky_map.html">🗺️ 产区图谱</a> ·
  <a href="https://1281227309-art.github.io/shangjiu/guide.html">📖 使用指南</a> ·
  <a href="https://1281227309-art.github.io/shangjiu/contributors.html">🏆 贡献者榜</a>
</p>

---

## 这是什么

「上九蒸馏所」做的一件小事：把**中国威士忌**讲清楚，并让 AI 能讲真话。

它是**国威知识中枢对外的蒸馏出口 + 品鉴数据漏斗**。国威缺的不是酒，是一套"人人能读、人人能引用、经得起核查"的讲法。所以我们做了一个——

- **薄插件**：走标准 **MCP 协议**，接入任意 AI 宿主即用（Trae / Cursor / Claude Desktop…），不做独立 App。
- **诚实数据**：每个字段带可信度标注（✅已核实 / 🟡待厂方确认 / ⬜待采集），**不编造品鉴笔记与价格**。
- **数据漏斗**：`submit_tasting_note` 采集真人品鉴（AI 不判断），经复核后才可能进知识库——这是护城河的原材料。

> 一句话：这个工具的意义不是"更聪明的 AI"，而是**让 AI 在讲中国威士忌时，说的都是真话**。

---

## 功能亮点（五个标签）

| 标签 | 对应工具 | 价值 |
|---|---|---|
| **国威品鉴** | `get_flavor_profile` / `get_distillery` | 查酒厂档案、风味图谱，带可信度 |
| **选酒导购** | `recommend_whisky` / `list_products` | 预算+口味+场景 → 打分推荐 |
| **产区图谱** | `list_regions` / `search_whisky` | 产区萌芽体系 + 全库检索 |
| **产业与法规** | `get_industry_facts` | 产业大盘数据（64 家/7 万千升/份额）+ 新国标 GB/T 11856.1-2025 合规要点 |
| **内容生成** | `generate_content` / `submit_tasting_note` | 生成内容骨架（选题/长文/小红书/短视频）+ 采集真人品鉴 |

---

## 快速开始

需要 **Node ≥ 22**（可原生剥离类型直接跑 `.ts`，无需构建）。

```bash
cd 上九国威知识库-mcp
npm install          # 或 pnpm install（本项目含 pnpm-lock.yaml）

npm start            # 启动 MCP 服务器（Node 原生直跑 src/index.ts）
npm run dev          # --watch 开发模式

# 免 npm 也能直接用（纯业务层，不依赖 MCP SDK）：
npm run demo         # 演示全部工具输出（含品鉴漏斗落盘）
npm run review       # 品鉴数据复核管线
```

服务器走 **stdio**，启动后无界面，等 MCP 宿主调用。日志输出到 stderr，不污染协议通道。

> 结构：`src/data.ts`（知识数据）与 `src/tools.ts`（业务逻辑）均为**无依赖纯模块**，可脱离 MCP 单独复用——即"知识资产独立于协议"。`src/index.ts` 只做 MCP 薄封装。

---

## MCP 宿主配置

### 通用 stdio 配置（任何支持 MCP 的客户端）

```json
{
  "mcpServers": {
    "shangjiu-guowei": {
      "command": "node",
      "args": ["<项目绝对路径>/src/index.ts"]
    }
  }
}
```

> 若在某些宿主里"裸 `node` 找不到或路径出问题"，用项目自带的启动脚本：把 `command` 换成 `<项目绝对路径>/run-mcp.sh`，`args` 留空。

### Trae（推荐，国内可直接用）

Trae → 设置 → MCP → 添加，填：类型 `stdio`、命令 `<项目绝对路径>/run-mcp.sh`（或 node + src/index.ts）、参数留空。Trae 的模型支持工具调用，能真正调用本插件。

### Cursor

`~/.cursor/mcp.json`（或项目 `.mcp.json`）：

```json
{
  "mcpServers": {
    "shangjiu-guowei": {
      "command": "<项目绝对路径>/run-mcp.sh",
      "args": []
    }
  }
}
```

### Claude Desktop（一键接入）

```bash
bash scripts/install-claude-config.sh
```

脚本会把 `mcpServers.shangjiu-guowei` 合并进 `~/Library/Application Support/Claude/claude_desktop_config.json` 并填入项目绝对路径，之后**完全退出并重启 Claude Desktop** 即可调用。

---

## 对话示例

> 下面是无 GUI 的 stdio 管道验证命令（等价于宿主内部的调用序列）。

```bash
cat data/host-scenario.jsonl | node src/index.ts
```

真实宿主里的提问 → 工具调用效果：

| 你的提问 | 工具被调用 |
|---|---|
| "查一下国产威士忌有哪些东方风味的厂" | `search_whisky("东方")` |
| "帮我挑一支 200 元内、果香、日常喝的国产威士忌" | `recommend_whisky(budget:200, taste:果香, occasion:日常口粮)` |
| "写一篇**东方风味**主题的小红书" | `generate_content(topic:东方风味, format:小红书)` |
| "我喝了大芹双桶，记一条品鉴：果香浓郁、余韵悠长、90 分" | `submit_tasting_note(...)` → 落盘 `pending_review` |

**已验证的返回效果**（Trae 实测）：模型会先调用工具、返回知识库的真实数据，并诚实标注——
> "数据来源：上九国威知识库 …价格带整体处于待采集状态，知识库目前的行业锚点是——崃州主力 100–400 元（口粮档）、叠川 888 元（高端锚点）。"

---

## MCP 工具列表（9 个）

| 工具 | 作用 |
|---|---|
| `list_regions` | 中国威士忌产区萌芽体系（邛崃/峨眉山/千岛湖/大理/滇西/广东/胶东/亳州/青藏/浏阳/闽西） |
| `list_distilleries` | 酒厂列表（可按产区 code 过滤） |
| `get_distillery` | 酒厂完整档案（产区/工艺/风土/产品/可信度） |
| `get_flavor_profile` | 风味图谱（主导词 + 官方/社区来源） |
| `list_products` | 产品线与价格带（含行业价格锚点） |
| `search_whisky` | 全库检索（酒厂名/产区/风格/风味词/故事） |
| `recommend_whisky` | **选酒导购**：预算+口味+场景 → 打分推荐（含可信度与诚实声明） |
| `generate_content` | **内容生成**：选题/长文/小红书/短视频骨架（基于知识库真实信息 + 待核标注） |
| `submit_tasting_note` | **品鉴笔记漏斗**：采集真人数据，写入 `data/tasting-input.jsonl` |

---

## 数据层（社区共建）

知识库的数据模型：`产区(Region) → 酒厂(Distillery) → 产品(Product)`，每个字段带 `source`（来源）与 `confidence`（可信度）。

**可信度三档**：`✅ verified 已核实` / `🟡 pending 待厂方确认` / `⬜ unverified 待采集`。

### 共建机制（真实数据 → 才进知识库）

```
真人品鉴 / 厂方一手信息
        │  submit_tasting_note（AI 只收集，不判断）
        ▼
   品鉴数据池  data/tasting-input.jsonl   （状态: pending_review）
        │  scripts/review.mjs：list / approve / reject / report
        ▼
   curated  data/tasting-approved.json    （真人复核通过）
        │  人工判断
        ▼
   进入知识库  src/data.ts                 （带 source + confidence）
```

**社区怎样共建：**
1. **提交品鉴**：在宿主里调 `submit_tasting_note`，或直接用 `node scripts/review.mjs` 走复核。
2. **补充/更正数据**：给 `src/data.ts` 提 PR —— 新增酒厂/产区/产品、补核实价格、更正错误。**每条必须带来源**，`confidence` 如实标注。
3. **厂方共建**：面向新国威小厂——我们帮它们"把'你是谁'定义成标准 + 给声量"，换回它们的**一手数据与内容授权**（见策略定位）。

### 诚实守则（社区必须遵守）
- **不编造**：品鉴笔记、价格、工艺细节，凡无一手来源一律留空标注。
- **AI 只整理不判断**：AI 做归并、可视化、追踪；不做主观品鉴结论。
- **出处可查**：每个字段带 `source` 与 `confidence`。
- **待采即待采**：标注 `⬜ 待采集` 的，不等厂方确认不作结论。

---

## 贡献 (Contributing)

> **完整发布指南见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)**（含改哪个文件、走哪条管线、具体命令与数据规范）。

欢迎一切形式的共建：

| 贡献类型 | 怎么做 |
|---|---|
| **数据** | 给 `src/data.ts` 提 PR（酒厂/产区/产品/价格，带 `source` + `confidence`） |
| **品鉴** | 调用 `submit_tasting_note` 提交；走 `scripts/review.mjs` 复核 |
| **代码** | 改进 `src/tools.ts` / `src/index.ts`，提 PR |
| **内容** | 用 `generate_content` 生成平台内容，可回传修正 |
| **bug / 建议** | 开 Issue，说明复现步骤 |

**流程建议**：Fork → 修改 → 提 PR；数据类 PR 请附来源链接，并如实标 `confidence`。我们会用 `scripts/review.mjs` 对品鉴数据做复核；`tsc --noEmit` 通过后方可合入。

### 🏆 贡献者奖励机制

我们为「被复核进库」的贡献者准备了明确的奖励——**只奖励进库的贡献，不奖励提交动作**，这是保护「诚实数据」的前提。

- **[`CONTRIBUTORS.md`](./CONTRIBUTORS.md)** —— 贡献者荣誉榜（谁、贡献了什么）
- **[`docs/贡献者奖励规则.md`](./docs/贡献者奖励规则.md)** —— 积分、等级徽章、四级奖励（可执行规则）
- **[`docs/贡献者奖励机制方案.md`](./docs/贡献者奖励机制方案.md)** —— 完整方案（背景、飞轮、路线图、风险）
- **在线榜单**：[`contributors.html`](https://1281227309-art.github.io/shangjiu/contributors.html)（自动统计更新）

---

## 项目结构

```
上九国威知识库-mcp/
├── package.json
├── tsconfig.json
├── .gitignore
├── LICENSE
├── README.md
├── CONTRIBUTING.md               # 贡献者发布指南（具体路径/命令/规范）
├── run-mcp.sh                      # 一键启动脚本（规避命令路径问题）
├── claude_desktop_config.example.json
├── src/
│   ├── data.ts        # 国威知识库（纯数据 + 类型，无外部依赖）
│   ├── tools.ts       # 业务逻辑层（纯函数，无 MCP SDK）
│   └── index.ts       # MCP 服务器（薄封装，stdio）
├── scripts/
│   ├── demo.mjs        # 免 npm 演示所有工具
│   ├── review.mjs      # 品鉴数据复核管线
│   ├── host-demo.mjs   # 真实宿主演示（官方 SDK Client）
│   ├── install-claude-config.sh  # 一键接入 Claude Desktop
│   └── mcp-probe.mjs   # 端到端协议探针（标准机器）
└── data/
    ├── host-scenario.jsonl   # 管道演示会话
    └── probe-requests.jsonl  # 探针会话
```

---

## 路线图

- **v0.1**：骨架 + 可信度标注；品鉴漏斗本地落盘。
- **v0.2**：品鉴数据**复核管线**（真人复核→才进知识库）；业务层抽成 `tools.ts`；免 npm 演示。
- **v0.3**：真实接入 —— Claude Desktop 一键配置、SDK 宿主演示、管道演示。
- **v0.4（当前）**：**选酒导购** `recommend_whisky`；**内容生成** `generate_content`；扩充产区/酒厂档案（滇西茶威、胶东、亳州草本、西藏青稞等）。
- **🏷 2026-10-02 情报批次**：酒厂 **19 → 23 家**（新增隐象、万季、久溪、青岛牌）；补录 **觀橡 WWA 2026「世界最佳调和麦芽」**、**崃州 WWA 2026「中国最佳单一麦芽」**、叠川 2024 ISC 金奖、古奇蒙古栎桶 80 万元拍卖；3 项标准补齐官方编号（**T/CNLIC 0246-2026**、**T/HZAS 118—2026**、**税委会公告 2026 年第 1 号**）；修正「64 家」与进口份额口径、崃州泥煤波本规格。评估报告与取证档案见 [`docs/最新国产威士忌收录评估-2026-10-02.md`](./docs/最新国产威士忌收录评估-2026-10-02.md)。
- **🏷 2026-10-07 情报批次**：产区 **11 → 16 带**（新增 **什邡（四川）、内蒙古（库伦/太仆寺旗）、恩施（湖北）、永泰（福州）、普洱（滇南）**），酒厂 **23 → 30 家**（新增熊猫精酿·什邡、农湾双龙谷·库伦旗、农湾双龙谷·恩施、西鸽永泰酒庄、山河馏心·普洱、内蒙古克劳德、云凰）；**赛事奖项线升级为官方数据源**（WWA 2026 官网 ID 区间枚举得 39 条中国区记录：吉斯波尔「Symbol」单一麦芽·12 年及以下子类别冠军、太瓏釀「Best Chinese Grain」、青岛牌 Gold；ISC 2026 官方 JSON：崃州 1 金 7 银等）；新增 **T/TMAC 455-2026《威士忌 固态发酵法》** 标准对象、`WHISKY_STANDARD` 补 6 项硬指标（木桶≤700L、高级醇≤6.0 g/L、总醛≤0.5 g/L 等，来源为中酒协官方解读）；**纠正 3 处库内事实**（高桥「2026-05 试生产」→ 截至 2026-10-05 尚未出酒；叠川 ISC 年份写实 2024；千岛湖「已集聚 6 家」≠ 全部投产，并更正上轮归因）；崃州泥煤波本维持 46/50 双记、新增「雪莉醇境」。评估报告与取证档案见 [`docs/最新国产威士忌收录评估-2026-10-07.md`](./docs/最新国产威士忌收录评估-2026-10-07.md)。
- **🏷 2026-10-18 情报批次（快筛轮）**：窗口 10-07→10-18 **无新增酒厂/产区**（仍 **16 产区 / 30 家酒厂**）；可入库增量以「事件落地 + 口径纠正 + 遗留闭合」为主：**千岛湖威士忌产业学院 2026-10-16 揭牌开班**（88 人报名、首批 20 名学员）、**大理 2026 州级盘面**（10 项目 / 35 亿元 / 已建成 1690 千升 / 规划 1.21 万千升，与「2025 年 2300 千升」并列不覆盖）、**T/HZAS 118—2026 著录补强**（9 家具名起草单位 + 适用范围原文，10-19 实施）、**WWA 2026 补录**（山河馏心＝Shanhe Liuxin、千岛金久＝Faerieferry，两家此前零奖项）、**百润 10-16 定增问询函回复**（前次 15 万桶已建成、本次已获环评批复）、**淳之谷 10-12 拿地**、**高桥 10-09 现场**（乐山 232 亩 / 1000 万升＝高桥，遗留闭合）、**太瓏釀官网 HKD 1,098**；并纠正「规划产能远超进口量」（口径错位）与「大理＝首个高原核心产区」（规划目标）两处媒体表述。评估报告见 [`docs/最新国产威士忌收录评估-2026-10-18.md`](./docs/最新国产威士忌收录评估-2026-10-18.md)。
- **🏷 2026-10-20 情报批次**：窗口 10-18→10-20 新增酒厂 **30 → 31 家**（**鸿峪 / 烟台鸿裕酿酒**，山东烟台高新区，5 款 SKU、5 座熟成库 / 6108 只橡木桶、72 小时长时发酵；目前仅香港商报 2026-10-19 单一来源，待厂方官网或工商佐证）；新增赛事主体 **CIABC 2026 国际酒类（中国）大奖赛**（2026-08-25~27 烟台评审，463 款参评 / 186 款获奖 / 大金奖 10 款），**沃族（蓬莱）「海石双桶威士忌」为中国威士忌唯一大金奖**——并入既有 `yuzhijin` 条目、**不新建酒厂**（沃族与钰之锦是否同一法人待工商确认，用「厂方实体」措辞）；**千岛金久** 法兰克福国际大奖赛（2026）「双金一银」与既有 WWA 记录**并列**登记、未覆盖；里程碑 **16 → 17 条**。本轮产业大盘 / 价格 / 政策 / 标准对象**零新增**（中酒协 9-19 口径已于 10-18 轮吃干），另否决崃州「IWSC 98 分」单一自媒体来源项。评估报告见 [`docs/最新国产威士忌收录评估-2026-10-20.md`](./docs/最新国产威士忌收录评估-2026-10-20.md)。
- **🏷 2026-10-20 晚轮（补正轮）**：窗口 10-20 10:46→23:20 **零新增酒厂 / 产区 / 赛事**（仍 16 产区 / 31 家 / 17 条里程碑）；落库为两处既有条目的证据补正——**鸿峪**熟成库与桶储**双口径并列**（商报 5 库 / 6108 只 / 4 类桶型 vs 厂方供稿 截至 2025-03 4 库 / 6400 只 / 6 类桶型）+ 香港零售 定價 HK$868 / 售價 HK$799；**钰之锦 ↔ 沃族** 实体闭合（沃族（蓬莱）葡萄酒庄有限公司 成立 2010-11-09 / 注册资本 2660 万元 / 统一社会信用代码 91370600564056843E；法定代表人「张华岳 vs 仲崇沪」两说并列）。**海关 2026-09 数据已发布但 WAF 不可达**（正文页 412 / 504，媒体亦未跟进），缺口②状态更新为「已发布 · 待可达」；另否决 WBO「小厂转售」文（2025-12-16 旧文、匿名主体）。评估报告见 [`docs/最新国产威士忌收录评估-2026-10-20-晚轮.md`](./docs/最新国产威士忌收录评估-2026-10-20-晚轮.md)。
- **v0.5**：盲品会数据接入；面向小厂的"品牌定制风味库"接口；内容生成流程产品化。
- **v0.6**：社区共建引擎（贡献者激励 / 数据审核面板）；跨语言 SDK。

---

## License

MIT —— 见 [LICENSE](./LICENSE)。欢迎自由使用、修改、再分发；引用数据时请保持出处标注。