Cafe Shop MCP Agent - Ausführliche Dokumentation

Systemübersicht

Der Cafe Shop MCP Agent („Bean & Brew") ist eine fortschrittliche Implementierung des Model Context Protocol (MCP)-Ökosystems. Er besteht aus zwei eigenständigen Diensten, die sicher über das MCP-streamable-http-Transportprotokoll kommunizieren.

Das System verwendet einen auf LangChain basierenden ReAct-Agenten, der auf AWS Bedrock läuft, um natürliche Sprachbefehle für den Coffeeshop zu verarbeiten, Live-Bestände abzufragen und Bestellungen über den MCP-Server gegen eine PostgreSQL-Datenbank auszuführen.

Related MCP server: @striderlabs/mcp-starbucks

1. Architektur im Detail

1.1 Die Client-Schnittstelle (client/)

Der Client fungiert als benutzerorientierte API und als Ausführungsumgebung für den LangChain-Agenten.

• Framework: FastAPI

• Agent-Orchestrator: LangGraph + LangChain (create_agent)

• LLM-Engine: AWS Bedrock (ChatBedrock)

• Persistenz: LangGraph AsyncPostgresSaver (Checkpointer) für Thread-Level-Speicher.

• Middleware-Integration:

  • SummarizationMiddleware: Komprimiert den Verlauf über 2000 Tokens oder 10 Nachrichten hinaus.

  • PIIMiddleware: Schwärzt E-Mails, maskiert Kreditkarten und schwärzt Telefonnummern, bevor sie an Bedrock gesendet werden.

  • HumanInTheLoopMiddleware: Unterbricht den add_order-Toolaufruf zur expliziten menschlichen Genehmigung vor der Ausführung.

1.2 Der MCP-Server (mcp_server/)

Der Server stellt Domänenlogik und Datenbegrenzungen sicher bereit.

• Framework: FastMCP (mcp.server.fastmcp)

• Datenbank: PostgreSQL (verwaltet über SQLAlchemy ORM).

• Transport: HTTP SSE (streamable-http).

2. API-Vertrag und Datenfluss

2.1 Chat-Endpunkt (Client)

POST /api/v1/chat

Anfrage-Payload (ChatRequest):

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

Hinweis: mode kann normal, structured oder leer sein. stream bestimmt, ob die Antwort SSE oder synchrones JSON ist.

Antwort-Payload (ChatResponse - Normalmodus):

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

(Wenn pending_approval vorhanden ist, muss die message der nächsten Anfrage genau „approve" oder „reject" lauten, mit derselben thread_id).

2.2 Datenbankschema (MCP-Server)

Die PostgreSQL-Datenbank besteht aus 4 Haupttabellen:

1. menu_items: menu_item_id (PK), name (eindeutig), 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: Verknüpfungstabelle, die orders und menu_items mit einer quantity-Spalte verbindet.

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

3. Model Context Protocol (MCP)-Bindungen

Der FastMCP-Server registriert explizit die folgenden Komponenten. Der Client lädt diese bedingungslos während der Sitzungsinitialisierung (load_session_context).

3.1 Tools (@mcp.tool())

3.2 Prompts (@mcp.prompt())

• brew_buddy_system: Die primären ReAct-Agentenanweisungen formatieren Rolle, Ziele, Einschränkungen und Ausgabeformat (unter Verwendung von XML-Tags <role>, <instructions>).

• order_confirmation(customer_name, items): Generiert eine warme, formatierte Bestellbestätigung.

3.3 Ressourcen (@mcp.resource())

• menu://items: Schreibgeschützter Text-Dump des Live-Menüs und der Preise.

• store://info: Statischer String mit Öffnungszeiten, Standort und Kontaktrichtlinien.

4. Einrichtung und Ausführungsschritte

4.1 Voraussetzungen

• PostgreSQL, lokal oder über Docker ausgeführt.

• AWS-Bedrock-Zugriff (AWS-Anmeldeinformationen konfiguriert).

• Python 3.11+ und der Paketmanager uv.

4.2 MCP-Server starten

Navigieren Sie zu mcp_server/, aktualisieren Sie Ihre .env mit DB_HOST, DB_USER, DB_PASS usw. und führen Sie aus:

uv sync
python main.py

Dies löst automatisch Datenbankmigrationen (create_tables.py) aus und befüllt das Standard-Kaffeemenü, wobei FastMCP auf Port 8000 gestartet wird.

4.3 Client-API starten

Navigieren Sie zu client/, aktualisieren Sie Ihre .env mit AWS- und MCP-Server-Anmeldeinformationen (MCP_SERVER_URL=http://localhost:8000) und führen Sie aus:

uv sync
python main.py

Dies startet die benutzerorientierte FastAPI-Anwendung auf Port 8080.

4.4 Beispiel-Workflow

1. Benutzer fragt nach Menü: POST /api/v1/chat -> Agent liest Ressource menu://items.

2. Benutzer gibt Bestellung auf: POST /api/v1/chat -> Agent ruft add_order auf. HITL-Middleware unterbricht und gibt pending_approval zurück.

3. Benutzer genehmigt: POST /api/v1/chat (message: „approve", gleiche thread_id) -> Client setzt LangGraph-Checkpointer-Zustand fort -> Tool wird auf MCP-Server ausgeführt -> DB-Bestand reduziert.