MCP Agentic Commerce

🚀 Agentic Commerce MCP Demo (Goose + MCP UI)

このプロジェクトは、Goose 内で MCP UI ブロックを使用して、エージェント型コマースのユーザー体験を展示する小型の Model Context Protocol (MCP) サーバーです。「レストランを検索 → メニューを表示 → 仮注文 → レシートを表示」というシンプルなフローに対して、リッチでインタラクティブな HTML UI を返します。

🚀 クイックスタート

このサーバーを起動することで、エージェント型コマースのユーザー体験を体験できます。まずはセットアップを行いましょう。

✨ 主な機能

• 複数のツールを備えたストリーミング可能な HTTP MCP サーバー:
  • find_restaurants – 都市/州とクエリで近くの合成レストランを検索します。
  • view_restaurant – レストランの詳細カードを表示します。
  • view_menu – 画像と価格付きのメニューを表示します（「Square」が検出された場合はモックカタログ、それ以外は汎用メニューにフォールバックします）。
  • order_takeout – インタラクティブな注文ページ（数量の編集、アイテムの削除が可能）を表示します。
  • view_receipt – 面白い仮のレシートを表示します。
• クリックファーストの MCP UI: ユーザーアクションで UI がツール呼び出しをエージェントに送信します。
• ローカルテスト用の開発 HTML プレビュー: http://127.0.0.1:8000/dev で利用できます。
• スクリプトで再生成可能な大規模な合成データセット

📦 インストール

前提条件

• Node.js 20+
• pnpm (Node に同梱) または ppnpm/yarn

セットアップ手順

1. 依存関係をインストールします。

pnpm install

2. デモデータを生成します（オプション; リポジトリには事前にビルドされた JSON が含まれています）。

# 合成レストランを再生成します（5MB 以上のファイル）
# 密度を制御できます:
#   GEN_MIN_PER_CATEGORY=3 GEN_MAX_PER_CATEGORY=5 pnpm run generate:data
pnpm run generate:data

# カテゴリ別の汎用メニューを再生成します
pnpm run generate:menus

3. 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)")

4. ブラウザでローカル UI プレビューを試してみましょう。

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

💻 使用例

基本的な使用法

Goose でこのプロジェクトを使用するには、以下の 2 つのオプションがあります。

オプション A — Goose の設定で手動で追加する

• Goose Desktop を開き → 設定 → 拡張機能 → MCP サーバーを追加
• タイプ: HTTP (ストリーミング可能)
• URL: http://127.0.0.1:8000/mcp
• 名前: Agentic Commerce MCP Demo
• 保存します。新しいチャットを開始し、以下のような質問をしましょう。
  • “Find coffee around Austin”
  • “Show pizza near Toronto”
  • “Order two lattes from Midtown Bean at 9:15 under Sam.”

オプション B — MCP インスペクターを使用する（ツールと UI のテストに便利）

# このサーバーに対してインスペクターを実行します
pnpm run dev:inspector
# 次に印刷されたインスペクターの URL を開き、直接ツールを実行してみましょう

高度な使用法

モデル/エージェントが MCP UI をサポートしている場合、HTML カード、メニュー、レシートがインラインでレンダリングされ、ボタンクリックでツール呼び出しが送信されます。

📚 ドキュメント

このプロジェクトではないもの

• ライブな 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 – 会話フローの例と UX ノート

データに関する注意事項

• レストランは合成されたもので、多くの米国/カナダの都市にまたがるシードジェネレーターに基づいています。ジェネレータースクリプトの環境変数でデータセットの密度を再生成または減らすことができます。
• メニュー画像は Unsplash からホットリンクされており、このデモでの説明目的のみで使用されています。

安全性と免責事項

• このプロジェクトはデモ用であり、いかなる情報も事実として扱わないでください。
• 金銭の移動は行われません。「注文をする」フローでは確認用の UI のみがレンダリングされます。

デプロイメント

Netlify へのデプロイ

このプロジェクトは、Netlify 上でサーバーレス関数としてデプロイするように構成されています。

1. Netlify に接続する
   • Netlify にアクセスします。
   • 「新しいサイトを追加」→「既存のプロジェクトをインポート」をクリックします。
   • GitHub リポジトリを接続します。
2. ビルド設定（netlify.toml から自動検出）
   • ビルドコマンド: pnpm run build
   • 公開ディレクトリ: dist
3. デプロイ
   • Netlify は main ブランチへのプッシュ時に自動的にデプロイします。
   • 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

🔧 技術詳細

ツールリファレンス

• find_restaurants
  • 引数: city (文字列, デフォルト "Austin"), state (オプション), query (オプション), limit (1..25, デフォルト 10)
  • 戻り値: 近くの販売者の UI リスト; 「詳細」と「今すぐ注文」のボタン
• view_restaurant
  • 引数: business_id (文字列)
  • 戻り値: 住所、営業時間、電話番号、ウェブサイトが記載された UI カード; CTA ボタン
• view_menu
  • 引数: business_id (文字列)
  • 動作: モック "Square" が検出された場合 -> モックカタログを使用; それ以外は主要カテゴリによる汎用メニュー
• order_takeout
  • 引数: business_id (文字列), items ( { name, qty, price } の配列)
  • 戻り値: 合計と注文ボタンがあるインタラクティブな注文テーブル
• view_receipt
  • 引数: business_id (文字列), items (上記と同じ)
  • 戻り値: 面白いデモ用のレシート UI

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

重要な注意事項

⚠️ 重要提示

このプロジェクトはデモ用であり、いかなる情報も事実として扱わないでください。金銭の移動は行われません。「注文をする」フローでは確認用の UI のみがレンダリングされます。

💡 使用建议

モデル/エージェントが MCP UI をサポートしている場合、HTML カード、メニュー、レシートがインラインでレンダリングされ、ボタンクリックでツール呼び出しが送信されます。