FastMCP Orders Server

Ein Server für das Model Context Protocol (MCP), erstellt mit FastMCP, der ein Tool zur Abfrage von Kundenbestellungen aus einer PostgreSQL-Datenbank bereitstellt.

Projektstruktur

├── mcp_server.py        # FastMCP server — stdio transport (default), HTTP optional
├── mcp_client.py        # Demo client — connects via stdio, calls the tool
├── .env.example         # Template for DB credentials
├── requirements.txt     # Python dependencies
├── schema.sql           # DDL to create customers + orders tables
├── seed.sql             # Sample data for local testing
└── README.md            # This file

Related MCP server: Mock Store MCP Server

Voraussetzungen

• Python ≥ 3.10

• PostgreSQL-Instanz mit einer Datenbank, die das unten beschriebene Schema enthält

Datenbankschema

Der Server erwartet zwei Tabellen:

Führen Sie die bereitgestellten SQL-Dateien aus, um diese zu erstellen:

psql -d orders_db -f schema.sql
psql -d orders_db -f seed.sql

Einrichtung

1. Abhängigkeiten installieren

pip install -r requirements.txt

2. Datenbank-Zugangsdaten konfigurieren

Kopieren Sie die Umgebungsvariablen-Vorlage und füllen Sie Ihre Verbindungsdetails aus:

cp .env.example .env
nano .env   # edit values to match your PostgreSQL instance

Server ausführen

Stdio-Transport (Standard)

python mcp_server.py

Dies ist der Standardmodus für lokale MCP-Server und funktioniert mit Claude Desktop, dem MCP Inspector und jedem stdio-kompatiblen Client.

HTTP-Transport (optional – entfernte Clients)

python mcp_server.py --transport http --port 9000

Nützlich, wenn Clients einen entfernten HTTP-Endpunkt anstelle eines lokalen Prozesses benötigen.

Demo-Client ausführen

Der gebündelte Client verbindet sich über stdio mit dem Server und führt drei Testszenarien aus:

python mcp_client.py

Erwartete Ausgabe (mit geladenen Beispieldaten):

[TEST 1] Orders for customer_id=1 with min_amount=100.0
  Order ID   Date          Amount (€)     Status
  --------------------------------------------------------
  5          2025-06-15    180.75 €       completed
  3          2025-03-01    520.00 €       shipped
  1          2025-01-10    250.00 €       completed

  → 3 order(s) found

[TEST 2] Orders for 'carlos@example.com' with min_amount=300.0
  Order ID   Date          Amount (€)     Status
  --------------------------------------------------------
  8          2025-05-10    890.00 €       shipped
  6          2025-02-01    340.00 €       completed

  → 2 order(s) found

[TEST 3] Lookup nonexistent email (expecting error)
  ⚠ Customer not found (nobody@nowhere.com)

Testen mit dem MCP Inspector

Der MCP Inspector ist ein interaktives Werkzeug zur Erkundung von MCP-Servern.

npx @modelcontextprotocol/inspector node mcp_server.js

Für Python-Server:

npx @modelcontextprotocol/inspector python mcp_server.py

1. Der Inspector öffnet ein Browserfenster unter http://localhost:6287.

2. Suchen Sie in der Benutzeroberfläche unter Tools nach get_customer_orders_above_amount.

3. Geben Sie Parameter ein (z. B. {"customer_id": 1, "min_amount": 100}) und klicken Sie auf Call.

4. Untersuchen Sie die strukturierte JSON-Antwort.

Tool-Spezifikation

get_customer_orders_above_amount

Ruft die Bestellungen eines Kunden ab, deren Gesamtsumme einen Mindestbetrag in Euro überschreitet.

Mindestens einer der Parameter customer_id oder customer_email muss angegeben werden.

Rückgabe: list[dict] – jedes dict enthält die Schlüssel order_id, order_date, total_amount, status. Die Ergebnisse sind absteigend nach order_date sortiert.

Fehlerantworten werden als Liste mit einem einzigen dict zurückgegeben, das einen "error"-Schlüssel enthält (keine rohen Stack-Traces gelangen zum Client).

Sicherheitshinweise

• Keine fest codierten Zugangsdaten – alle DB-Parameter stammen aus Umgebungsvariablen, die über python-dotenv geladen werden.

• Nur parametrisierte Abfragen – SQL-Injection wird durch die durchgängige Verwendung von $1, $2-Platzhaltern verhindert.

• Verbindungspooling – ein asyncpg-Pool (2–10 Verbindungen) wird einmalig beim Serverstart erstellt und beim Herunterfahren geschlossen.