MCP Agentic Commerce

🚀 智能商業MCP演示 (Goose + MCP UI)

本項目是一個小型的模型上下文協議（MCP）服務器，藉助 Goose 內的MCP UI模塊，展示了智能商業的用戶體驗。它能為 “查找餐廳 → 查看菜單 → 模擬下單 → 生成收據” 這一簡單流程返回豐富且交互式的HTML用戶界面。

🚀 快速開始

本項目旨在作為MCP擴展供Goose使用。以下是詳細的使用步驟：

前提條件

• Node.js 20+
• pnpm（與Node捆綁）或ppnpm/yarn

安裝依賴

pnpm install

生成演示數據（可選；倉庫中包含預構建的JSON）

# 重新生成合成餐廳數據（5MB以上的文件）
# 你可以控制數據密度：
#   GEN_MIN_PER_CATEGORY=3 GEN_MAX_PER_CATEGORY=5 pnpm run generate:data
pnpm run generate:data

# 按類別重新生成通用菜單
pnpm run generate:menus

運行MCP服務器（開發模式）

# 在127.0.0.1:8000/mcp啟動一個HTTP（可流式傳輸）MCP服務器
pnpm run dev
# 或者
pnpm run dev:mcp

你可以設置以下環境變量：

• MCP_HOST（默認值：127.0.0.1）
• MCP_PORT（默認值：8000）
• MCP_GEOCODE_USERAGENT（默認值："mcp-agentic-commerce/1.0 (+https://squareup.com)"）

在瀏覽器中嘗試本地UI預覽

• http://127.0.0.1:8000/dev
• 示例：http://127.0.0.1:8000/dev/restaurants?city=Austin&state=TX&query=bbq

與Goose配合使用

選項A — 在Goose設置中手動添加：

• 打開Goose桌面版 → 設置 → 擴展 → 添加MCP服務器
• 類型：HTTP（可流式傳輸）
• URL：http://127.0.0.1:8000/mcp
• 名稱：智能商業MCP演示
• 保存。開始新的聊天並詢問類似如下問題：
  • “查找奧斯汀附近的咖啡店”
  • “顯示多倫多附近的披薩店”
  • “在9:15為山姆從市中心豆咖啡館訂購兩杯拿鐵”

選項B — 使用MCP檢查器（便於測試工具和UI）：

# 針對此服務器運行檢查器
pnpm run dev:inspector
# 然後打開打印出的檢查器URL；嘗試直接執行工具

💡 使用建議：如果你的模型/智能體支持MCP UI，它將內聯渲染HTML卡片、菜單和收據，並在點擊按鈕時調度工具調用。

✨ 主要特性

• 支持多種工具的可流式傳輸HTTP MCP服務器：
  • find_restaurants – 按城市/州和查詢條件搜索附近的合成餐廳
  • view_restaurant – 餐廳詳情卡片
  • view_menu – 帶有圖片和價格的菜單（如果檢測到 “Square”，則使用模擬目錄；否則使用通用菜單）
  • order_takeout – 交互式訂單頁面（可編輯數量、移除商品）
  • view_receipt – 有趣的模擬收據
• 點擊優先的MCP UI：用戶操作時，UI會將工具調用發送回智能體。
• 用於本地測試的開發HTML預覽，地址為 http://127.0.0.1:8000/dev
• 可通過腳本重新生成的大型合成數據集

📚 詳細文檔

這不是什麼

• 沒有即時的Square API調用，沒有資金流動，沒有真實賣家或個人身份信息
• 沒有持久存儲；沒有身份驗證；沒有進行生產環境加固

倉庫佈局

• src/server.ts – 帶有渲染UI工具的MCP服務器
• src/ui/* – HTML外殼、樣式和視圖構建器
• src/lib/restaurants.ts – 通過OpenStreetMap Nominatim對合成賣家進行本地搜索和地理編碼
• src/lib/square.ts – 用於 “Square檢測” 和示例目錄的小型模擬
• src/data/* – 生成的餐廳和分類菜單的JSON數據
• src/scripts/* – 上述數據的生成器
• scenarios.md – 示例對話流程和用戶體驗說明

工具參考

數據說明

• 餐廳數據是合成的，基於美國/加拿大多個城市的種子生成器。你可以通過生成器腳本上的環境變量重新生成或降低數據集密度。
• 菜單圖片是從Unsplash熱鏈接的，僅用於本演示的說明目的。

安全與免責聲明

• 僅用於演示；請勿將任何信息視為事實。
• 沒有資金流動。“下單” 流程僅渲染確認UI。

部署

部署到Netlify

本項目配置為在Netlify上作為無服務器函數部署：

1. 連接到Netlify：
   • 訪問 Netlify
   • 點擊 “添加新站點” → “導入現有項目”
   • 連接你的GitHub倉庫
2. 構建設置（從netlify.toml自動檢測）：
   • 構建命令：pnpm run build
   • 發佈目錄：dist
3. 部署：
   • Netlify將在推送到主分支時自動部署
   • 你的MCP服務器將在以下地址可用：https://your-site-name.netlify.app/mcp
   • 開發預覽地址：https://your-site-name.netlify.app/dev
4. 與Goose配合使用（生產環境）：
   • 部署完成後，在Goose設置中使用你的Netlify URL
   • 類型：HTTP（可流式傳輸）
   • URL：https://your-site-name.netlify.app/mcp

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。