Scan to join WeChat grouparticle
README
🚀 智能商业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– 示例对话流程和用户体验说明
工具参考
| 工具名称 | 参数 | 返回值 |
| ---- | ---- | ---- |
| find_restaurants | city（字符串，默认 “Austin”），state（可选），query（可选），limit（1..25，默认10） | 附近卖家的UI列表；“详情” 和 “立即下单” 按钮 |
| view_restaurant | business_id（字符串） | 包含地址、营业时间、电话、网站的UI卡片；行动呼吁按钮 |
| view_menu | business_id（字符串） | 如果检测到模拟的 “Square”，则使用模拟目录；否则使用主要类别的通用菜单 |
| order_takeout | business_id（字符串），items（{ name, qty, price } 数组） | 带有总计和 “下单” 按钮的交互式订单表 |
| view_receipt | business_id（字符串），items（同上） | 有趣的演示收据UI |
数据说明
- 餐厅数据是合成的，基于美国/加拿大多个城市的种子生成器。你可以通过生成器脚本上的环境变量重新生成或降低数据集密度。
- 菜单图片是从Unsplash热链接的，仅用于本演示的说明目的。
安全与免责声明
- 仅用于演示；请勿将任何信息视为事实。
- 没有资金流动。“下单” 流程仅渲染确认UI。
部署
部署到Netlify
本项目配置为在Netlify上作为无服务器函数部署：
- 连接到Netlify：
- 访问 Netlify
- 点击 “添加新站点” → “导入现有项目”
- 连接你的GitHub仓库
- 构建设置（从netlify.toml自动检测）：
- 构建命令：
pnpm run build - 发布目录：
dist
- 构建命令：
- 部署：
- Netlify将在推送到主分支时自动部署
- 你的MCP服务器将在以下地址可用：
https://your-site-name.netlify.app/mcp - 开发预览地址：
https://your-site-name.netlify.app/dev
- 与Goose配合使用（生产环境）：
- 部署完成后，在Goose设置中使用你的Netlify URL
- 类型：HTTP（可流式传输）
- URL：
https://your-site-name.netlify.app/mcp
📄 许可证
本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。