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 文件。