Cafe Shop MCP Agent - 상세 문서

시스템 개요

Cafe Shop MCP Agent("Bean & Brew")는 Model Context Protocol(MCP) 생태계의 고급 구현체입니다. MCP streamable-http 전송 프로토콜을 사용하여 안전하게 통신하는 두 개의 독립 서비스로 구성됩니다.

이 시스템은 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: 역할, 목표, 제약 조건 및 출력 형식(XML 태그 <role>, <instructions> 사용)을 지정하는 기본 ReAct 에이전트 지침입니다.

• 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 서버에서 실행됩니다 -> DB 재고가 감소합니다.