Cafe Shop MCP Agent - 詳細ドキュメント

システム概要

Cafe Shop MCP Agent（"Bean & Brew"）は、Model Context Protocol (MCP) エコシステムの高度な実装です。MCP の streamable-http トランスポートプロトコルを使用して安全に通信する2つのスタンドアロンサービスで構成されています。

このシステムは、AWS Bedrock 上で動作する LangChain ベースの ReAct エージェントを使用して、自然言語のコーヒーショップリクエストを処理し、MCP サーバーを介して PostgreSQL データベースに対してライブ在庫の照会と注文の実行を行います。

Related MCP server: @striderlabs/mcp-starbucks

1. アーキテクチャ詳細

1.1 クライアントインターフェース（client/）

クライアントは、ユーザー向け API および LangChain エージェントの実行環境として機能します。

• フレームワーク: FastAPI

• エージェントオーケストレーター: LangGraph + LangChain（create_agent）

• LLM エンジン: AWS Bedrock（ChatBedrock）

• 永続化: スレッドレベルのメモリのための LangGraph AsyncPostgresSaver（チェックポインター）。

• ミドルウェア統合:

  • SummarizationMiddleware: 2000トークンまたは10メッセージを超える履歴を圧縮します。

  • PIIMiddleware: Bedrock に送信する前に、メールアドレスを編集し、クレジットカードをマスクし、電話番号を編集します。

  • HumanInTheLoopMiddleware: 実行前に明示的な人間の承認を得るために、add_order ツール呼び出しをインターセプトします。

1.2 MCP サーバー（mcp_server/）

サーバーは、ドメインロジックとデータ境界を安全に公開します。

• フレームワーク: FastMCP（mcp.server.fastmcp）

• データベース: PostgreSQL（SQLAlchemy ORM 経由で管理）。

• トランスポート: HTTP SSE（streamable-http）。

2. API 契約とデータフロー

2.1 チャットエンドポイント（クライアント）

POST /api/v1/chat

リクエストペイロード（ChatRequest）:

{
  "message": "I'd like to order 2 Cappuccinos please.",
  "mode": "normal", 
  "stream": false,
  "thread_id": "user-session-id"
}

注: mode は normal、structured、または空のままにできます。stream は、レスポンスが SSE か同期 JSON かを決定します。

レスポンスペイロード（ChatResponse - ノーマルモード）:

{
  "message": "I have set up your order for 2 Cappuccinos. Before I finalize it, do you approve?",
  "structured_output": null,
  "stream_chunks": null,
  "pending_approval": {
    "tool": "add_order",
    "args": {"customer_name": "Guest", "items": [{"item_name": "Cappuccino", "quantity": 2}]},
    "description": "Tool add_order requires approval."
  }
}

（pending_approval が存在する場合、次のリクエストの message は同じ thread_id で正確に "approve" または "reject" である必要があります）。

2.2 データベーススキーマ（MCP サーバー）

PostgreSQL データベースは、4つの主要テーブルで構成されています:

1. menu_items: menu_item_id（PK）、name（一意）、price（Numeric）、stock_quantity（int）、is_active（bool）。

2. orders: order_id（UUID PK）、order_sequence_id（BigInt シーケンス）、customer_name（str）、status（str）。

3. order_items: orders と menu_items を quantity 列でリンクするジャンクションテーブル。

4. error_logs: log_id、error_code、message、source。

3. Model Context Protocol (MCP) バインディング

FastMCP サーバーは、以下のコンポーネントを明示的に登録します。クライアントは、セッション初期化中（load_session_context）にこれらを無条件にロードします。

3.1 ツール（@mcp.tool()）

3.2 プロンプト（@mcp.prompt()）

• brew_buddy_system: 役割、目的、制約、出力形式をフォーマットする主要な ReAct エージェントの指示（XML タグ <role>、<instructions> を使用）。

• order_confirmation(customer_name, items): 温かみのあるフォーマット済みの確認レシートを生成します。

3.3 リソース（@mcp.resource()）

• menu://items: ライブメニューと価格の読み取り専用テキストダンプ。

• store://info: 営業時間、所在地、連絡先ポリシーを含む静的文字列。

4. セットアップと実行手順

4.1 前提条件

• PostgreSQL がローカルまたは Docker 経由で実行されていること。

• AWS Bedrock へのアクセス（AWS 認証情報が設定されていること）。

• Python 3.11+ と uv パッケージマネージャー。

4.2 MCP サーバーを起動する

mcp_server/ に移動し、.env を DB_HOST、DB_USER、DB_PASS などで更新して、以下を実行します:

uv sync
python main.py

これにより、データベースマイグレーション（create_tables.py）が自動的にトリガーされ、デフォルトのコーヒーメニューがシードされ、FastMCP がポート 8000 で起動します。

4.3 クライアント API を起動する

client/ に移動し、.env を AWS と MCP サーバーの認証情報（MCP_SERVER_URL=http://localhost:8000）で更新して、以下を実行します:

uv sync
python main.py

これにより、ユーザー向け FastAPI アプリケーションがポート 8080 で起動します。

4.4 ワークフロー例

1. ユーザーがメニューを尋ねる: POST /api/v1/chat -> エージェントが menu://items リソースを読み取ります。

2. ユーザーが注文する: POST /api/v1/chat -> エージェントが add_order を呼び出します。HITL ミドルウェアがインターセプトして pending_approval を返します。

3. ユーザーが承認する: POST /api/v1/chat（message: "approve"、同じ thread_id）-> クライアントが LangGraph チェックポインターの状態を再開 -> ツールが MCP サーバー上で実行 -> DB の在庫が減少します。