mcp-shop-server

MCP-Server, der einem KI-Agenten read-only Zugriff auf die SQLite-Datenbank eines Online-Shops gewährt (customers, products, orders, order_items). Über ihn beantwortet der Agent analytische Fragen zu den Daten: Datenbankstruktur, Aggregate nach Kunden, Produkten, Kategorien und Umsatz. Transport — stdio.

Schreiben in die Datenbank ist by design unmöglich: drei unabhängige Schutzschichten — Verbindung mode=ro, Validierung der Abfrage vor der Ausführung (nur SELECT / WITH ... SELECT) und sqlite3-authorizer.

Messungen, Nachweise und Abweichungen von der Spezifikation — REPORT.md.

Verwendung

1. Klonen

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

Im Repository liegt bereits shop.db (150 Kunden, 50 Produkte, 750 Bestellungen, 1900 Positionen).

2. Abhängigkeiten installieren

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

Ohne uv — dasselbe mit den Standardmitteln:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Erforderlich ist Python 3.11+. Abhängigkeiten: mcp (offizielles MCP SDK) und pytest für Tests; die Datenbankarbeit erfolgt über sqlite3 aus der Standardbibliothek.

3. In die Agentenkonfiguration eintragen

Minimale Konfigurationsform:

{
  "command": "python",
  "args": ["/absolute/path/to/mcp-shop-server/server.py"]
}

Funktionierendes Beispiel für einen Client mit mcpServers-Block (Claude Desktop, Cursor und kompatible):

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/mcp-shop-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-shop-server/server.py"],
      "env": {
        "MCP_SHOP_DB": "/absolute/path/to/mcp-shop-server/shop.db"
      }
    }
  }
}

Für Claude Code genügt ein einziger Befehl:

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DB ist optional: Wenn die Variable nicht gesetzt ist, nimmt der Server shop.db neben server.py. Geben Sie sie an, wenn die Datenbank woanders liegt. Den Interpreter sollte man aus .venv angeben — sonst findet der systemweite python das Paket mcp möglicherweise nicht.

4. Start

Der Server wird vom Agenten gestartet, von Hand ist das selten nötig:

.venv/bin/python server.py

Der Prozess wartet still auf JSON-RPC auf stdin; Diagnose geht nach stderr, stdout ist vom MCP-Protokoll belegt.

5. Prüfung und Fragen an den Agenten

.venv/bin/python -m pytest -q

Nach der Verbindung sieht der Agent drei Werkzeuge. Fragen werden in normaler Sprache gestellt.

Die acht Aufgaben aus dem Text der Hausaufgabe — genau diese sollte man zur Überprüfung durchlaufen lassen:

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ Die Aufgaben 2, 3 und 7 haben in der mitgelieferten Datenbank keine Lösung, und das ist erwartbar. In customers gibt es keine Spalte mit dem Land — alle 150 Kunden haben russische Telefonnummern; alle 750 Bestellungen sind auf 2026 datiert, für 2025 gibt es keine Daten.

Der Server erfindet in diesem Fall keine Daten: Er meldet, dass ein solches Feld im Schema nicht existiert, und listet die vorhandenen Spalten auf. Nichts ist im Code fest verdrahtet — das Schema wird aus der Datenbank gelesen, daher funktionieren dieselben Fragen auf einer anderen Datenbank, in der country vorhanden ist, normal.

Zusätzlich werden Fragen geprüft, die die Datenbank vollständig abdeckt: Top-5-Kunden nach Bestellsumme, Umsatz nach Kategorien, Verteilung der Bestellungen nach Status, durchschnittlicher Warenkorb, Lagerbestände.

Prüfung des Schreibschutzes. Auf „Delete all cancelled orders“ erhält der Agent eine verständliche Ablehnung, keinen Fehler: Der Server arbeitet nur lesend, 102 stornierte Bestellungen bleiben an Ort und Stelle.

Werkzeuge

Die Ausgabe ist begrenzt: standardmäßig 100 Zeilen, maximal 1000. Beim Abschneiden meldet die Antwort, wie viele Zeilen zurückgegeben wurden, wie viele insgesamt gefunden wurden und mit welchem offset weiter gelesen werden soll.

Wenn das angeforderte Feld in der Datenbank nicht existiert (z. B. das Land des Kunden), sagt der Server das ehrlich und listet die vorhandenen Spalten auf — nicht vorhandene Felder werden nicht erfunden.

Related MCP server: Shop Analytics MCP Server

Wie es gemacht wurde

Das Projekt wurde mit einem einzigen Prompt generiert — die Datei SPEC-mcp-shop.md, die dem Agenten vollständig übermittelt wurde, ohne spätere Präzisierungen.

Intern arbeitete der Agent in einer Schleife nach dem Skill repo-task-proof-loop (Denis Shiryaev, Apache-2.0): Spezifikation einfrieren → bauen → Beweise verpacken → Prüfung mit frischer Sitzung → minimale Korrektur → erneut prüfen, bis zum Urteil PASS.

Die Nachweise des Durchlaufs liegen im Repository unter .agent/tasks/mcp-shop-server/:

• spec.md — eingefrorene Spezifikation mit Abnahmekriterien AC1…AC17;

• evidence.md / evidence.json — für jedes Kriterium Urteil und konkreter Nachweis;

• verdict.json — Ergebnis der unabhängigen Prüfung mit frischer Sitzung;

• problems.md — vom Prüfer gefundene Abweichungen;

• raw/ — rohe Logs der Durchläufe: Tests, Live-MCP-Sitzung, Prüfung der stdout-Sauberkeit.

Geprüft wird nicht der Quellcode, sondern das Verhalten des Servers mit einem lebenden Agenten: Der Harness raw/mcp_session_check.py startet server.py über stdio mit einem echten MCP-Client, ruft alle Werkzeuge auf, führt die acht analytischen Aufgaben aus, erhält die Ablehnung auf Löschung und prüft, dass stdout nur JSON-RPC-Frames enthält.

Der Entwicklungsskill selbst liegt lokal in .claude/skills/ und wird nicht ins Repository committet — das ist fremder Code.

Getroffene Entscheidungen zu Unklarheiten der Spezifikation