inventory-mcp

Demo-MCP-Server für Inventarabfragen, entwickelt in Python mit FastMCP. Das Projekt unterstützt das Studium der wichtigsten Konzepte des Model Context Protocol (MCP), mit Trennung zwischen Transport, MCP-Schnittstelle, Geschäftsregeln, Validierung und Daten.

Der aktuelle Umfang ist bewusst nur lesend: Der Server erlaubt das Abfragen von Produkten und Lagermengen, ohne Operationen zum Anlegen, Ändern oder Löschen.

Technologien

• Python 3.11+

• FastMCP

• Pydantic

• pytest

• Ruff

Related MCP server: vanam-erp-mcp

Architektur

• app/server.py: Erstellt den FastMCP-Server, registriert die Tools und startet den Transport stdio oder SSE.

• app/client.py: Demonstrationsclient, der die Tools über stdio oder SSE auflistet und aufruft.

• app/tools/: MCP-Schnittstelle; validiert Eingaben, delegiert an den Dienst und wandelt erwartete Fehler in stabile Antworten um.

• app/services/: Regeln für Abfrage und Laden des Inventars.

• app/schemas/: Pydantic-Modelle, die die Verträge für Produkt und Bestand definieren und validieren.

• app/data/: lokale Datenquelle, derzeit die Datei inventory.json.

• tests/: automatisierte Tests des Dienstes, der Tools und der Serverkonfiguration.

Client → MCP Server → Tool → InventoryService → inventory.json

Die Tools greifen nicht direkt auf die Datei zu. Sie delegieren die Geschäftsregeln an den InventoryService.

MCP-Tools

get_product

• Zweck: die vollständigen Daten eines Produkts anhand des Namens abfragen.

• Eingabe: name (nicht leerer string).

• Ausgabe bei Erfolg: Objekt mit name, quantity und price.

• Ausgabe bei nicht vorhandenem Produkt: Objekt mit error: "product_not_found" und einer beschreibenden message.

• MCP-Beschreibung: Use this tool to retrieve the complete data of a product by name, including its price and stock quantity.

• Klassifizierung: nur lesend.

{
  "name": "Mouse",
  "quantity": 25,
  "price": 89.9
}

get_stock

• Zweck: nur die aktuelle Lagermenge eines Produkts anhand des Namens abfragen.

• Eingabe: name (nicht leerer string).

• Ausgabe bei Erfolg: Objekt mit quantity.

• Ausgabe bei nicht vorhandenem Produkt: Objekt mit error: "product_not_found" und einer beschreibenden message.

• MCP-Beschreibung: Use this tool to retrieve only the current stock quantity of a product by name.

• Klassifizierung: nur lesend.

{
  "quantity": 25
}

Eingabevalidierung

Die Tools verlangen, dass name ein String mit Inhalt ist. Leere Namen oder Namen, die nur aus Leerzeichen bestehen, werden vor der Abfrage abgelehnt. Der Dienst wendet strip() an, um Leerzeichen an den Enden zu entfernen, und casefold(), um Namen ohne Unterscheidung zwischen Groß- und Kleinschreibung zu vergleichen.

Pydantic validiert die aus dem JSON geladenen Datensätze und die Ausgabemodelle. Ein Produkt muss einen nicht leeren Namen, eine nicht negative ganze Menge und einen nicht negativen numerischen Preis haben. Die Ablehnung leerer Abfragenamen erfolgt durch _validate_product_name(). Ungültige Datensätze brechen das Laden mit einem expliziten Fehler ab.

Fehlerbehandlung

Der InventoryService wirft ProductNotFoundError, wenn er das angeforderte Produkt nicht findet. Die Tools fangen diesen erwarteten Fehler ab und geben eine vorhersehbare Nutzlast zurück:

{
  "error": "product_not_found",
  "message": "Product not found: Monitor"
}

Eingabefehler wie ein leerer Name oder ein Wert, der kein String ist, werden nicht verborgen: Sie werden als Fehler des Tool-Aufrufs gemeldet.

MCP-Transporte

• stdio: Kommunikation über Standardeingabe und -ausgabe. In diesem Projekt startet der Client den FastMCP-Server als Unterprozess, führt die Aufrufe aus und beendet den Prozess am Ende.

• SSE: Kommunikation über einen HTTP-Endpunkt mit Server-Sent Events. Server und Client laufen in getrennten Prozessen; standardmäßig lauscht der Server auf http://127.0.0.1:8000/sse.

Ausführung

Die folgenden Befehle verwenden PowerShell und müssen im Projektstamm ausgeführt werden.

Virtuelle Umgebung erstellen und aktivieren

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Abhängigkeiten installieren

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Ausführen über stdio

Der Client verwendet standardmäßig stdio und startet den Server als Unterprozess:

.\.venv\Scripts\python.exe -m app.client

Um nur den Server direkt zu starten:

.\.venv\Scripts\python.exe -m app.server --transport stdio

Ausführen über SSE

Starten Sie den Server in einem Terminal (sse ist der Standardtransport des Servers):

.\.venv\Scripts\python.exe -m app.server

Der entsprechende explizite Befehl lautet python -m app.server --transport sse. Verbinden Sie in einem anderen Terminal den Client:

.\.venv\Scripts\python.exe -m app.client --transport sse

Der Client akzeptiert einen anderen Endpunkt über --url.

Tests ausführen

.\.venv\Scripts\pytest.exe

Ruff ausführen

.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\ruff.exe format --check .

Tool-Risikobewertung

Die aktuellen Tools sind nur lesend und können keine Daten erstellen, ändern oder löschen. Diese Entscheidung verringert die Risikofläche, beseitigt jedoch nicht mögliche Auswirkungen auf Vertraulichkeit und Verfügbarkeit.

Großvolumige Aufrufe können weiterhin Serverressourcen verbrauchen. Künftige Änderungen an den Tools oder den zurückgegebenen Daten sollten von einer neuen Risikobewertung begleitet werden.

Vertrauensgrenze

Die von einem MCP-Client empfangenen Argumente werden als nicht vertrauenswürdige Eingabe behandelt.

MCP Client
    ↓
MCP Server
    ↓
Tool
    ↓
InventoryService
    ↓
inventory.json

Die Validierung erfolgt, bevor die Argumente von der Dienstschicht verwendet werden. Der Server geht nicht davon aus, dass die vom Client gesendeten Daten allein deshalb gültig sind, weil sie über das MCP-Protokoll eingegangen sind. Die Datensätze aus inventory.json werden ebenfalls als externe Eingabe behandelt und beim Laden von Pydantic validiert.

MCP-Tool-Annotationen

Die Tools werden semantisch anhand ihres Verhaltens klassifiziert. Die beiden aktuellen Operationen deklarieren:

readOnlyHint=true
openWorldHint=false

readOnlyHint=true teilt dem MCP-Client mit, dass die Operation keinen Zustand ändern soll.

openWorldHint=false zeigt an, dass das Tool mit einer geschlossenen und bekannten Domäne arbeitet – in diesem Fall dem lokalen Inventar – statt externe Systeme oder offene Quellen abzufragen.

Diese Annotationen dienen als Metadaten und Hinweise für MCP-Clients, nicht als Sicherheitsmechanismen. Ein Client sollte sich nicht auf sie als Ersatz für Validierung, Autorisierung oder andere tatsächliche Kontrollen verlassen.

Risiko von Schreib-Tools

Eine zukünftige Operation wie:

update_stock(name, quantity)

hätte ein deutlich höheres Risiko, da sie den persistenten Zustand des Systems verändern würde.

Ein fehlerhafter oder böswilliger Aufruf könnte das falsche Produkt ändern, ungültige Werte erfassen oder unbefugte Änderungen ermöglichen. Ein zukünftiges Tool wie update_stock würde strenge Validierung, Authentifizierung, Autorisierung, Auditierung und Tracing erfordern. Destruktive Operationen würden außerdem, wo anwendbar, Bestätigung oder Genehmigung erfordern.

Risiko nach Transport

Bei stdio wird der Server lokal als Unterprozess des Clients gestartet, was die Netzwerkexposition verringert. Bei SSE sind Server und Client getrennte Prozesse, und die Kommunikation verwendet einen HTTP-Endpunkt. Eine eventuelle Veröffentlichung dieses Endpunkts außerhalb des lokalen Hosts würde zusätzliche Zugriffs- und Verfügbarkeitskontrollen erfordern.

Tests

Die aktuelle Testsuite validiert:

• Laden, Suchen, Normalisierung und Fehler des InventoryService;

• Rückgaben der Tools und Umwandlung eines nicht vorhandenen Produkts in einen vorhersehbaren Fehler;

• Ablehnung leerer Namen und von Werten, die keine Strings sind;

• Ablehnung ungültiger Inventardatensätze durch Pydantic;

• Registrierung der Tools auf dem Server;

• Auswahl und Konfiguration der Transporte SSE und stdio;

• echte Integration über stdio, einschließlich list_tools(), Aufruf von get_stock und Lesen der MCP-Annotationen.

Die Szenarien umfassen vorhandene und nicht vorhandene Produkte, Leerzeichen an den Enden, Unterschiede zwischen Groß- und Kleinschreibung sowie ungültige Eingaben. Im End-to-End-Test startet ein echter FastMCP-Client den Server als Unterprozess, validiert readOnlyHint und openWorldHint, fragt den aus dem lokalen JSON geladenen Bestand ab und beendet die Verbindung über den Context Manager.

Codequalität

Das Projekt verwendet Typannotationen, trennt Zuständigkeiten zwischen MCP, Diensten, Schemas und Daten und hält die Abhängigkeiten minimal. pytest deckt die implementierten Verhaltensweisen ab, während Ruff Lint, Imports, Kompatibilität mit Python 3.11 und Formatierung prüft.

Aktuelle Einschränkungen

• Die Daten werden aus einer lokalen JSON-Datei geladen.

• Es gibt keine Datenbank.

• Es gibt keine Integration mit KI oder LLM.

• Es gibt keine Schreib-Tools.

• Es gibt keine Authentifizierung oder Autorisierung.

Mögliche Weiterentwicklungen

• Tracing und strukturiertes Logging, die außerhalb des aktuellen Umfangs gehalten werden, um den didaktischen Fokus des Projekts zu bewahren;

• Unterstützung für Streamable HTTP;

• Persistenz in einer Datenbank;

• Authentifizierung und Autorisierung;

• Schreib-Tools mit Schutzvorkehrungen;

• zukünftige Integration mit LLM.