Cafe Shop MCP Agent — исчерпывающая документация

Обзор системы

Cafe Shop MCP Agent («Bean & Brew») — это продвинутая реализация экосистемы Model Context Protocol (MCP). Система состоит из двух независимых сервисов, которые безопасно взаимодействуют друг с другом по транспортному протоколу MCP streamable-http.

Система использует ReAct-агента на базе LangChain, работающего на AWS Bedrock, для обработки запросов на естественном языке, связанных с кофейней: агент запрашивает актуальные данные об остатках и оформляет заказы в базе данных PostgreSQL через MCP-сервер.

Related MCP server: @striderlabs/mcp-starbucks

1. Подробный разбор архитектуры

1.1 Клиентский интерфейс (client/)

Клиент выступает в роли пользовательского API и среды выполнения LangChain-агента.

• Фреймворк: FastAPI

• Оркестратор агента: LangGraph + LangChain (create_agent)

• Механизм LLM: AWS Bedrock (ChatBedrock)

• Постоянное хранение: LangGraph AsyncPostgresSaver (Checkpointer) для памяти на уровне потоков.

• Интеграция промежуточного ПО:

  • SummarizationMiddleware: сжимает историю, превышающую 2000 токенов или 10 сообщений.

  • PIIMiddleware: удаляет адреса электронной почты, маскирует номера кредитных карт и удаляет номера телефонов перед отправкой в Bedrock.

  • HumanInTheLoopMiddleware: перехватывает вызов инструмента add_order для явного подтверждения человеком перед выполнением.

1.2 MCP-сервер (mcp_server/)

Сервер безопасно предоставляет доменную логику и границы данных.

• Фреймворк: FastMCP (mcp.server.fastmcp)

• База данных: PostgreSQL (управляется через ORM SQLAlchemy).

• Транспорт: 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 Предварительные требования

• 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 (сообщение: «approve», тот же thread_id) -> клиент возобновляет состояние чекпойнтера LangGraph -> инструмент выполняется на MCP-сервере -> остатки в БД уменьшаются.