Cafe Shop MCP Agent - 详尽文档

系统概述

Cafe Shop MCP Agent（"Bean & Brew"）是 Model Context Protocol (MCP) 生态系统的先进实现。它由两个独立服务组成，通过 MCP streamable-http 传输协议安全通信。

该系统使用基于 LangChain 的 ReAct 代理，运行在 AWS Bedrock 上，用于处理自然语言的咖啡店请求，查询实时库存，并通过 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 个 token 或 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 必须恰好为 "approve" 或 "reject"，并使用相同的 thread_id）。

2.2 数据库模式（MCP 服务器）

PostgreSQL 数据库由 4 个主要表组成：

1. menu_items：menu_item_id（主键）、name（唯一）、price（Numeric）、stock_quantity（int）、is_active（bool）。

2. orders：order_id（UUID 主键）、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 前提条件

• 本地或通过 Docker 运行 PostgreSQL。

• AWS Bedrock 访问权限（已配置 AWS 凭据）。

• Python 3.11+ 和 uv 包管理器。

4.2 启动 MCP 服务器

导航到 mcp_server/，使用 DB_HOST、DB_USER、DB_PASS 等更新您的 .env，然后运行：

uv sync
python main.py

这将自动触发数据库迁移（create_tables.py）并填充默认咖啡菜单，在端口 8000 上启动 FastMCP。

4.3 启动客户端 API

导航到 client/，使用 AWS 和 MCP 服务器凭据（MCP_SERVER_URL=http://localhost:8000）更新您的 .env，然后运行：

uv sync
python main.py

这将在端口 8080 上启动面向用户的 FastAPI 应用程序。

4.4 示例工作流

1. 用户请求菜单： POST /api/v1/chat -> 代理读取 menu://items 资源。

2. 用户下订单： POST /api/v1/chat -> 代理调用 add_order。HITL 中间件中断并返回 pending_approval。

3. 用户批准： POST /api/v1/chat（消息："approve"，相同的 thread_id）-> 客户端恢复 LangGraph 检查点状态 -> 工具在 MCP 服务器上执行 -> 数据库库存减少。