上九 · 国威知识库 MCP —— 使用指南（详细路径）

面向国产威士忌的 MCP 工具：国威品鉴 · 选酒导购 · 产区图谱 · 内容生成 让 AI 讲中国威士忌时，说的都是真话。

目录

1. 它是什么 / 解决什么问题
2. 快速开始（3 种接入路径）
3. 9 个工具详解（参数 + 示例）
4. 典型使用路径（按场景）
5. 数据层与可信度规则
6. 共建路径（品鉴漏斗 + 复核管线）
7. 项目结构 & 命令速查
8. 常见问题排查

1. 它是什么 / 解决什么问题

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

它是国威知识中枢对外的蒸馏出口 + 品鉴数据漏斗。核心设计：

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

一句话：意义不是「更聪明的 AI」，而是让 AI 在讲中国威士忌时，说的都是真话。

2. 快速开始（3 种接入路径）

路径 A：任意支持 MCP 的客户端（通用 stdio 配置）

在宿主的 MCP 配置里加：

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

若宿主里「裸 node 找不到」，把 command 换成项目自带的启动脚本： "command": "<项目绝对路径>/run-mcp.sh"，args 留空 []。

路径 B：Cursor

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

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

路径 C：Claude Desktop（一键接入）

bash scripts/install-claude-config.sh

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

本地启动 / 免宿主验证

cd 上九国威知识库-mcp
npm install          # 或 pnpm install

npm start            # 启动 MCP 服务器（Node 原生直跑 src/index.ts）
npm run dev          # --watch 开发模式
npm run demo         # 免 npm 演示全部工具输出（含品鉴漏斗落盘）
npm run review       # 品鉴数据复核管线
npm run typecheck    # tsc --noEmit 类型检查

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

3. 9 个工具详解

3.1 list_regions —— 产区图谱

参数：无

返回中国威士忌产区的萌芽体系（当前 10 个）：

3.2 list_distilleries —— 酒厂列表

参数：region（可选，产区 code，如 qionglai）

返回酒厂精简列表（id / 名称 / 产区 / 地点 / 背景 / 定位 / 可信度 / 来源）。 不传 region 则返回全部（当前 14 家）。

3.3 get_distillery —— 酒厂完整档案

参数：id（必填，酒厂 id）

返回完整档案：产区、工艺（process）、风土（terroir）、风味（flavor）、产品线、可信度，并附诚实声明。

当前可用的 14 个酒厂 id：

示例：get_distillery(id: "daqin")

3.4 get_flavor_profile —— 风味图谱

参数：distilleryId（必填）

返回主导风味词 + 官方/社区来源 + 工艺。主导风味词来自真人盲品聚合；未聚合前标注「待聚合」，不得当作权威结论。

3.5 list_products —— 产品线与价格带

参数：distilleryId（必填）

返回产品列表（名称 / 桶型 / 档位 / 价格带 / 可信度），并附行业价格锚点：

崃州主力 100–400 元（口粮档）；叠川 888 元（高端锚点）。

价格未核实的会标为「待确认」。

3.6 search_whisky —— 全库检索

参数：query（必填，检索词）

在库内匹配 酒厂名 / 产区 / 风格 / 主导风味词 / 故事。

常用检索词：东方、茶、青稞、橡木、米酿、草本、高海拔、烟熏、果香、风味桶

示例：search_whisky(query: "东方") → 返回所有走东方风味路线的厂。

3.7 recommend_whisky —— 选酒导购

参数（均可选）：

• budget：价格偏好，如 "100-300"、"口粮"、"高端"、"500 以内"
• taste：风味偏好，如 "果香"、"茶韵"、"甜"、"烟熏"、"清爽"
• occasion：场景，如 "日常口粮"、"送礼"、"品鉴/尝东方特色"

打分逻辑（代码内的真实算法）：

总分 = 预算分 × 2 + 口味分 + 场景分

• 预算分：预算能覆盖价格带低点 → 3；略超 150 元内 → 2；否则 1
• 口味分：命中风味词组（果香/甜/茶/烟/木/花香/草本/黄酒/风味桶/清爽/浓郁/高海拔）→ 每组 +3
• 场景分：送礼/招待 → 高端档 +3、已核实 +1；品鉴/东方 → 有特色桶型 +3；日常/口粮 → 口粮档 +3、已核实 +1

返回 Top 5 排序结果，每条含：酒厂、产品、产区、档位、价格带、可信度、风味、推荐理由、分数，并附 honesty_notice。

示例：recommend_whisky(budget: "200", taste: "果香", occasion: "日常口粮")

3.8 generate_content —— 内容生成

参数：

• topic（必填）：主题，如 "东方风味国产威士忌"
• format（必填，枚举）：长文 | 小红书 | 短视频 | 选题
• focus（可选）：酒厂 / 产区 / 风味关键词

从知识库取真实数据填充内容骨架，并返回：

• knowledge：命中的酒厂 / 产区
• title / content / cta
• facts_used：用到的真实事实
• todo：待核 / 待采集清单
• honesty_notice：诚实声明

四种格式的差异：

示例：generate_content(topic: "东方风味", format: "小红书")

3.9 submit_tasting_note —— 品鉴笔记漏斗

参数：

行为：校验酒厂存在 → 生成 note_xxx 记录（状态一律 pending_review）→ 追加写入 data/tasting-input.jsonl。

明确边界：本工具不据此给出任何权威评分或结论；仅采信真人来源；可信数据经真人复核后，才可能进入知识库。

4. 典型使用路径（按场景）

场景 1：我做内容，想找「东方风味」的厂和选题

① search_whisky(query: "东方")        → 找出走东方风味路线的厂
② generate_content(topic: "东方风味国产威士忌", format: "选题")
   → 拿到 5 条标题 + facts_used + todo（待核清单）
③ generate_content(topic: "东方风味", format: "小红书")
   → 拿到可直接改写的短文案骨架

场景 2：有人问我「200 元内、果香、日常喝的国产威士忌」

① recommend_whisky(budget: "200", taste: "果香", occasion: "日常口粮")
   → Top 5 打分推荐 + 推荐理由 + 诚实声明
② list_products(distilleryId: "<推荐第一名 id>")
   → 看该厂完整产品线与价格带（含行业锚点）

场景 3：我要写某家厂的深度稿

① get_distillery(id: "laizhou")        → 完整档案（工艺/风土/产品/可信度）
② get_flavor_profile(distilleryId: "laizhou")  → 风味图谱（主导词 + 来源）
③ list_products(distilleryId: "laizhou")       → 产品线与价格带
④ generate_content(topic: "崃州", format: "长文", focus: "邛崃")
   → 用真实数据生成长文骨架

场景 4：我想了解整个国产威士忌版图

① list_regions()                        → 10 个产区萌芽体系
② list_distilleries()                   → 全部 14 家酒厂
③ list_distilleries(region: "dianxi")   → 只看滇西（东方风味最密集）

场景 5：我喝了一支，想贡献数据（共建）

① submit_tasting_note(
     distilleryId: "daqin",
     product: "大芹双桶",
     score: 90,
     nose: "果香浓郁",
     palate: "…",
     finish: "余韵悠长",
     taster: "你的名字",
     source: "个人"
   )
   → 返回 accepted: true + reference: "note_xxx"（状态 pending_review）

② 终端走复核管线：
   node scripts/review.mjs list
   node scripts/review.mjs approve <id> <reviewer>

5. 数据层与可信度规则

数据模型

产区(Region) → 酒厂(Distillery) → 产品(Product)

每个字段带 source（来源）与 confidence（可信度）。

可信度三档

诚实守则（必须遵守）

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

6. 共建路径

数据流（真实数据 → 才进知识库）

真人品鉴 / 厂方一手信息
        │  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）

三种共建方式

提交流程

git clone https://github.com/1281227309-art/shangjiu.git
cd shangjiu
git checkout -b feat/your-change
# 改数据/代码（见 CONTRIBUTING.md）
node scripts/demo.mjs        # 跑业务层，看 9 工具输出是否正常
npm run typecheck            # tsc --noEmit，必须通过
git add -A
git commit -m "data: 新增 xx 酒厂（附来源）"
git push origin feat/your-change
# → 到 GitHub 提 Pull Request

7. 项目结构与命令速查

上九国威知识库-mcp/
├── package.json
├── tsconfig.json
├── LICENSE
├── README.md
├── CONTRIBUTING.md               # 贡献者发布指南
├── run-mcp.sh                    # 一键启动脚本（规避命令路径问题）
├── claude_desktop_config.example.json
├── landing.html / landing-single.html   # 落地页
├── 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  # 探针会话

命令速查

8. 常见问题排查

Q1：宿主报「找不到 node」或路径出错

把 command 换成项目自带的启动脚本 <项目绝对路径>/run-mcp.sh，args 留空。

Q2：服务器启动了但宿主没反应

• 确认走的是 stdio（不是 HTTP）；
• 确认日志在 stderr（不能污染 stdout 协议通道）；
• 用探针验证：node scripts/mcp-probe.mjs，或管道喂一组合法 JSON-RPC。

Q3：get_distillery 返回「未找到酒厂」

用返回体里的 available 字段列出的 id 之一（见本文 3.3 的 id 表）。

Q4：价格/风味是「待确认/待聚合」

这是设计如此，不是 bug。知识库坚持不编造——标 🟡/⬜ 的字段以官方渠道或厂方为准。

Q5：submit_tasting_note 返回落盘失败

记录已通过校验，但本地写入 data/tasting-input.jsonl 失败（如权限/路径问题）。不影响知识库本身，修好写权限后重试。

Q6：需要 Node 版本？

≥ 22。项目用 Node 原生类型剥离直接跑 .ts，无需构建步骤。

附：对话示例（真实宿主里的提问 → 工具调用）

已验证的返回效果（Trae 实测）：模型会先调用工具、返回知识库的真实数据，并诚实标注——

「数据来源：上九国威知识库 …价格带整体处于待采集状态，知识库目前的行业锚点是——崃州主力 100–400 元（口粮档）、叠川 888 元（高端锚点）。」

License

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

本文档由项目实际代码（src/index.ts、src/tools.ts、src/data.ts）核对生成，数据（10 产区 / 14 酒厂 / 9 工具）与代码一致。