Agente MCP de Cafetería - Documentación Exhaustiva

Resumen del Sistema

El Agente MCP de Cafetería ("Bean & Brew") es una implementación avanzada del ecosistema del Model Context Protocol (MCP). Consta de dos servicios independientes que se comunican de forma segura mediante el protocolo de transporte MCP streamable-http.

El sistema utiliza un agente ReAct basado en LangChain que se ejecuta en AWS Bedrock para procesar solicitudes de cafetería en lenguaje natural, consultando el inventario en tiempo real y ejecutando pedidos contra una base de datos PostgreSQL a través del servidor MCP.

Related MCP server: @striderlabs/mcp-starbucks

1. Análisis Profundo de la Arquitectura

1.1 La Interfaz de Cliente (client/)

El Cliente actúa como la API orientada al usuario y el entorno de ejecución del Agente LangChain.

• Framework: FastAPI

• Orquestador de Agentes: LangGraph + LangChain (create_agent)

• Motor LLM: AWS Bedrock (ChatBedrock)

• Persistencia: LangGraph AsyncPostgresSaver (Checkpointer) para memoria a nivel de hilo.

• Integración de Middleware:

  • SummarizationMiddleware: Comprime el historial más allá de 2000 tokens o 10 mensajes.

  • PIIMiddleware: Redacta correos electrónicos, enmascara tarjetas de crédito y redacta números de teléfono antes de enviarlos a Bedrock.

  • HumanInTheLoopMiddleware: Intercepta la llamada a la herramienta add_order para obtener aprobación humana explícita antes de la ejecución.

1.2 El Servidor MCP (mcp_server/)

El Servidor expone la lógica de dominio y los límites de datos de forma segura.

• Framework: FastMCP (mcp.server.fastmcp)

• Base de datos: PostgreSQL (gestionada mediante ORM SQLAlchemy).

• Transporte: HTTP SSE (streamable-http).

2. Contrato de API y Flujo de Datos

2.1 Endpoint de Chat (Cliente)

POST /api/v1/chat

Carga útil de la solicitud (ChatRequest):

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

Nota: mode puede ser normal, structured o dejarse vacío. stream determina si la respuesta es SSE o JSON síncrono.

Carga útil de la respuesta (ChatResponse - Modo Normal):

{
  "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."
  }
}

(Si pending_approval está presente, el message de la siguiente solicitud debe ser exactamente "approve" o "reject" con el mismo thread_id).

2.2 Esquema de Base de Datos (Servidor MCP)

La base de datos PostgreSQL consta de 4 tablas principales:

1. menu_items: menu_item_id (PK), name (único), price (Numeric), stock_quantity (int), is_active (bool).

2. orders: order_id (UUID PK), order_sequence_id (BigInt Seq), customer_name (str), status (str).

3. order_items: Tabla de unión que vincula orders y menu_items con una columna quantity.

4. error_logs: log_id, error_code, message, source.

3. Enlaces del Model Context Protocol (MCP)

El servidor FastMCP registra explícitamente los siguientes componentes. El Cliente los carga incondicionalmente durante la inicialización de la sesión (load_session_context).

3.1 Herramientas (@mcp.tool())

3.2 Prompts (@mcp.prompt())

• brew_buddy_system: Las instrucciones principales del agente ReAct que dan formato al rol, los objetivos, las restricciones y el formato de salida (usando etiquetas XML <role>, <instructions>).

• order_confirmation(customer_name, items): Genera un recibo de confirmación cálido y con formato.

3.3 Recursos (@mcp.resource())

• menu://items: Volcado de texto de solo lectura del menú y los precios en vivo.

• store://info: Cadena estática que contiene el horario de la tienda, la ubicación y las políticas de contacto.

4. Pasos de Configuración y Ejecución

4.1 Requisitos Previos

• PostgreSQL ejecutándose localmente o mediante Docker.

• Acceso a AWS Bedrock (credenciales de AWS configuradas).

• Python 3.11+ y el gestor de paquetes uv.

4.2 Iniciar el Servidor MCP

Navegue a mcp_server/, actualice su .env con DB_HOST, DB_USER, DB_PASS, etc., y ejecute:

uv sync
python main.py

Esto activa automáticamente las migraciones de base de datos (create_tables.py) y siembra el menú de café predeterminado, iniciando FastMCP en el puerto 8000.

4.3 Iniciar la API del Cliente

Navegue a client/, actualice su .env con las credenciales de AWS y del Servidor MCP (MCP_SERVER_URL=http://localhost:8000), y ejecute:

uv sync
python main.py

Esto inicia la aplicación FastAPI orientada al usuario en el puerto 8080.

4.4 Ejemplo de Flujo de Trabajo

1. El usuario solicita el menú: POST /api/v1/chat -> El agente lee el recurso menu://items.

2. El usuario realiza un pedido: POST /api/v1/chat -> El agente llama a add_order. El middleware HITL interrumpe y devuelve pending_approval.

3. El usuario aprueba: POST /api/v1/chat (mensaje: "approve", mismo thread_id) -> El cliente reanuda el estado del checkpointer de LangGraph -> La herramienta se ejecuta en el Servidor MCP -> Se reduce el stock de la base de datos.