MCP Agentic Commerce

🚀 Agentic Commerce MCP Demo (Goose + MCP UI)

This is a small Model Context Protocol (MCP) server that showcases the agentic commerce user experience (UX) using MCP UI blocks within Goose. It provides rich and interactive HTML UI for a simple flow of “find restaurants → view menu → fake order → receipt”.

🚀 Quick Start

This project is designed to be used as an MCP extension by Goose. You can follow the steps below to set it up:

1. Prerequisites:
   • Node.js 20+
   • pnpm (bundled with Node) or ppnpm/yarn
2. Setup:
   • Install dependencies:

pnpm install

- Generate demo data (optional; the repo includes prebuilt JSON):

# Regenerate synthetic restaurants (5MB+ file)
# You can control density:
#   GEN_MIN_PER_CATEGORY=3 GEN_MAX_PER_CATEGORY=5 pnpm run generate:data
pnpm run generate:data

# Regenerate generic menus by category
pnpm run generate:menus

- Run the MCP server (dev):

# Starts an HTTP (streamable) MCP server on 127.0.0.1:8000/mcp
pnpm run dev
# or
pnpm run dev:mcp

- Environment variables you can set:
    - MCP_HOST (default: 127.0.0.1)
    - MCP_PORT (default: 8000)
    - MCP_GEOCODE_USERAGENT (default: "mcp-agentic-commerce/1.0 (+https://squareup.com)")

3. Try the local UI previews in a browser:
   • http://127.0.0.1:8000/dev
   • Example: http://127.0.0.1:8000/dev/restaurants?city=Austin&state=TX&query=bbq
4. Use with Goose:
   • Option A — Add manually in Goose settings:
     • Open Goose Desktop → Settings → Extensions → Add MCP server
     • Type: HTTP (streamable)
     • URL: http://127.0.0.1:8000/mcp
     • Name: Agentic Commerce MCP Demo
     • Save. Start a new chat and ask something like:
       • “Find coffee around Austin”
       • “Show pizza near Toronto”
       • “Order two lattes from Midtown Bean at 9:15 under Sam.”
   • Option B — Use the MCP Inspector (handy for testing tools and UI):

# Runs the Inspector against this server
pnpm run dev:inspector
# Then open the printed Inspector URL; try executing tools directly

✨ Features

• Streamable HTTP MCP server with multiple tools:
  • find_restaurants – Search nearby synthetic restaurants by city/state and query.
  • view_restaurant – Display a details card for a restaurant.
  • view_menu – Show a menu with images and pricing (mock catalog if “Square” is detected; otherwise a generic menu fallback).
  • order_takeout – Provide an interactive order page (edit quantities, remove items).
  • view_receipt – Present a playful, fake receipt.
• Click-first MCP UI: The UI dispatches tool calls back to the agent on user actions.
• Dev HTML previews for local testing: Available at http://127.0.0.1:8000/dev.
• Large, synthetic dataset: You can regenerate it via scripts.

📦 What this is not

• There are no live Square API calls, no money movement, no real sellers, or PII.
• There is no persistent storage, no authentication, and no production hardening.

📦 Repo layout

• src/server.ts: The MCP server with tools that render UI.
• src/ui/*: HTML shell, styles, and view builders.
• src/lib/restaurants.ts: Local search over synthetic sellers + geocoding via OpenStreetMap Nominatim.
• src/lib/square.ts: A tiny mock for “Square detection” and sample catalogs.
• src/data/*: Generated JSON for restaurants and category menus.
• src/scripts/*: Generators for the data above.
• scenarios.md: Example conversational flows and UX notes.

📚 Tool reference

• find_restaurants:
  • args: city (string, default "Austin"), state (optional), query (optional), limit (1..25, default 10).
  • returns: A UI list of nearby sellers with buttons to “Details” and “Order Now”.
• view_restaurant:
  • args: business_id (string).
  • returns: A UI card with address, hours, phone, website, and CTA buttons.
• view_menu:
  • args: business_id (string).
  • behavior: If mock "Square" is detected, use the mock catalog; otherwise, show a generic menu by the primary category.
• order_takeout:
  • args: business_id (string), items (array of { name, qty, price }).
  • returns: An interactive order table with totals and a Place Order button.
• view_receipt:
  • args: business_id (string), items (same as above).
  • returns: A playful demo receipt UI.

🔧 Data notes

• Restaurants are synthetic and based on seeded generators across many US/CA cities. You can regenerate or reduce the dataset density via environment variables on the generator script.
• Menu images are hotlinked from Unsplash and used only for illustrative purposes in this demo.

🔧 Safety and disclaimers

• This is for demonstration only; do not treat any information as factual.
• No money movement occurs. The “Place order” flow only renders a confirmation UI.

🚀 Deployment

Deploy to Netlify

This project is configured to deploy as a serverless function on Netlify:

1. Connect to Netlify:
   • Go to Netlify.
   • Click "Add new site" → "Import an existing project".
   • Connect your GitHub repository.
2. Build Settings (auto-detected from netlify.toml):
   • Build command: pnpm run build.
   • Publish directory: dist.
3. Deploy:
   • Netlify will automatically deploy on push to main.
   • Your MCP server will be available at: https://your-site-name.netlify.app/mcp.
   • Dev preview available at: https://your-site-name.netlify.app/dev.
4. Use with Goose (Production):
   • Once deployed, use your Netlify URL in Goose settings.
   • Type: HTTP (streamable).
   • URL: https://your-site-name.netlify.app/mcp.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Important Note

This is just a demo. There are no real sellers, data, payments, or money movement. Everything is synthetic or mocked. It is not production code and exists to demonstrate how MCP UI can drive a click-first agent experience.

💡 Usage Tip

If your your If your model/agent supports MCP UI, it will render the HTML cards, menus, and receipts inline and dispatch tool calls on button clicks.