侘茶點餐系統 MCP Server

以台南侘茶飲料店真實菜單為基礎的教學用 MCP Server，透過 stdio 傳輸與 LLM Client（如 Claude Desktop）溝通，完整涵蓋 MCP 三大核心概念：Tools、Resources、Prompts，並以 get_menu Tool 示範 MCP Apps 的互動式 UI 擴充。

特色

• 86 款飲品、11 大分類、8 種加料，資料庫首次啟動自動 seed

• 6 個 Tools、5 個 Resources、2 個 Prompts，一站式體驗 MCP 全功能

• get_menu 內建互動式菜單 UI（MCP Apps），在支援的 Host 中會直接渲染 iframe

• SQLite（WAL 模式）本機持久化，免額外部署資料庫

Related MCP server: licha-order-mcp

技術棧

• TypeScript（ESM，NodeNext module resolution）

• @modelcontextprotocol/sdk v1.x — MCP Server SDK

• @modelcontextprotocol/ext-apps — MCP Apps 擴充（互動式 UI）

• better-sqlite3 — SQLite 嵌入式資料庫

• zod v4 — Tool 參數 schema 驗證

• vite + vite-plugin-singlefile — UI 打包為單一 HTML

• vitest + @vitest/coverage-v8 — 測試與覆蓋率

• pnpm 套件管理

環境需求

• Node.js 22（見 .node-version）

• pnpm

快速開始

# 安裝依賴
pnpm install

# 開發模式（tsx 直接執行，會自動建立並 seed data/cha-cha.db）
pnpm run dev

# 打包（先打包 UI 再編譯 TypeScript）
pnpm run build

# 執行編譯後的版本
pnpm run start

首次執行 pnpm run dev 或 pnpm run start 時，會自動在專案根目錄建立 data/cha-cha.db 並寫入完整菜單資料，無需手動初始化。

常用指令

接入 Client

• Claude Desktop：見 docs/claude-desktop-guide.md

• MCP Inspector（除錯用）：見 docs/inspector-guide.md

# 快速用 Inspector 測試
pnpm build
npx @modelcontextprotocol/inspector node dist/index.js

架構

進入點 src/index.ts 建立 McpServer 後，分別呼叫三個 register 函式注入功能：

src/
├── index.ts              進入點：建立 McpServer、註冊 Tools/Resources/Prompts、連接 stdio
├── db.ts                 SQLite 初始化、菜單 seed、共用查詢 helper
├── types.ts               共用型別（MenuItem、Topping、Order）與常數（甜度、冰量選項）
├── helpers.ts             菜單格式化函式
├── tools/                 6 個 Tool：查詢與操作
├── resources/              5 個 Resource：Client 端可主動讀取的資料
└── prompts/                2 個 Prompt：預定義提示模板

資料庫檔案存放於 data/cha-cha.db（不納入版控）。

MCP Apps UI

get_menu Tool 使用 registerAppTool 加掛互動式菜單 UI，支援 MCP Apps 的 Host（如 Claude Desktop）會自動渲染 iframe。UI 原始碼在 ui/，透過 Vite 打包為 dist/ui/menu-app.html 單一檔案。

提供的功能

Tools

Resources

Prompts

業務規則

• sugar_fixed = 1 的飲品忽略使用者甜度參數，強制設為「固定甜度」

• 單杯總價 = 飲品價格 + Σ(加料價格)；加料有免費項目（小珍珠、波霸、混珠，price = 0）

• 顧客常用口語簡稱點餐（如「波霸奶綠」其實是「茉香奶綠」加「波霸」加料），呼叫 create_order 前建議先用 get_menu 確認正確品名

• Tool 錯誤統一回傳 { content: [{ type: 'text', text }], isError: true }

測試

測試檔案放在 tests/ 目錄，使用 vitest。Tool handler 邏輯抽為獨立可匯出函式（如 handleGetOrders），與 registerXxx 註冊函式分離，方便直接測試 handler 而不需啟動 MCP Server。

覆蓋率設定於 vitest.config.ts，目前 coverage.include 限定在 src/tools/get-orders.ts，新增其他模組測試時需同步調整。

pnpm test

規格文件

• spec/spec.md — 完整技術規格書（SSOT：資料庫 schema、MCP 功能設計、菜單資料）

• spec/change/ — 變更請求（CR-001 ~ CR-004）及對應任務清單

授權

ISC