Shop SQLite MCP

Lokaler stdio-MCP-Server für die sichere Analyse einer bestehenden SQLite-Datenbank eines Online-Shops. Der Server liest das Schema dynamisch aus sqlite_master und SQLite PRAGMA und hängt daher nicht von vorab bekannten Spaltennamen ab.

Funktionen

• list_tables — Tabellen und Sichten;

• describe_table — Spalten, PK, FK und Indizes;

• get_schema — vollständiger Schema-Graph;

• run_select_query — eine einzelne eingeschränkte SELECT- / WITH ... SELECT-Abfrage;

• spezialisierte Analytics-Tools: count_customers_by_country, top_customers_by_spend, top_products_by_units, top_categories_by_revenue, revenue_in_year, top_customers_by_order_count;

• physischer Read-only-Modus von SQLite, query_only und Authorizer;

• Blockierung von DML, DDL, PRAGMA, ATTACH und mehreren Statements;

• Pagination: limit 1–500 und offset.

Setup

Ein Befehl erledigt alles: Er wählt die Installationsvariante, installiert Abhängigkeiten (oder baut das Docker-Image), findet die Datenbank, prüft das Lesen des Schemas und schreibt die fertige mcp.json.

python3 install.py

Das Skript fragt nach der Startvariante (.venv oder Docker) und dem Pfad zur Datenbank. Ohne Rückfragen:

python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db

Erforderlich ist Python 3.11+; für --mode docker wird ein installiertes Docker benötigt.

Standardmäßig wird die Datenbank aus data/shop.db verwendet. Wenn die Datei fehlt, stoppt das Skript mit einer verständlichen Fehlermeldung und erstellt keine leere Datenbank.

Ein manueller Start ist nicht nötig — der Server startet direkt aus der Konfiguration. Zum Debuggen:

.venv/bin/python -m shop_mcp.print_schema

Mit dem Agenten verbinden

Nach install.py bleibt ein Schritt. Die Datei mcp.json enthält bereits den gewählten Startbefehl und den absoluten Pfad zur Datenbank — es muss nichts bearbeitet werden.

Verbinden Sie ihn auf eine der folgenden Arten mit dem Agenten:

• Cursor: Öffnen Sie diesen Ordner als Workspace (eine Kopie liegt in .cursor/mcp.json) oder importieren Sie die mcp.json im Stammverzeichnis in die MCP-Einstellungen;

• Claude Desktop / anderer Client: Kopieren Sie den Inhalt von mcp.json in die MCP-Konfiguration.

Nach dem Verbinden stellen Sie direkt Fragen aus ASSIGNMENT.md. Die erste Aktion des Agenten ist get_schema oder ein spezialisiertes Analytics-Tool. Wenn das Tool SCHEMA_MISMATCH zurückgibt, verwenden Sie run_select_query.

Die Vorlage mit Platzhaltern ist nur mcp.json.example. Absolute Pfade gibt es nur in der Client-Konfiguration, nicht im Python-Code.

Docker

Einzelne Befehle sind nicht nötig: python3 install.py --mode docker baut selbst das Image shop-sqlite-mcp:local, mountet die Datenbank read-only und schreibt in mcp.json den Startbefehl docker run -i --rm.

Die Datenbank wird als /data/shop.db:ro bereitgestellt, das Flag -t wird nicht verwendet, weil MCP über stdin/stdout kommuniziert.

docker-compose.yml baut dasselbe Image und ist für die lokale Überprüfung des Builds nützlich; geben Sie dem Agenten mcp.json.

Test

.venv/bin/pytest

Die Tests verwenden eine temporäre Fixture-Datenbank mit Tabellennamen, die dem Server unbekannt sind. Sie prüfen Runtime-Introspection, Ergebnisbegrenzungen, das Fehlen von Schema-Hardcoding und die Ablehnung von destruktivem SQL.

Für die manuelle Prüfung stellen Sie nach dem Verbinden Fragen aus ASSIGNMENT.md, einschließlich:

Delete all cancelled orders.

Die Antwort des Tools muss WRITE_DENIED enthalten und die Datenbank muss unverändert bleiben.

Projektdateien

• install.py — der einzige Installationsbefehl: Abhängigkeiten/Image, Pfad zur Datenbank, Generierung der Konfiguration;

• mcp.json — fertige Verbindungskonfiguration (Befehl + Pfad zur Datenbank);

• PROMPT.md — der Prompt, nach dem der AI-Coding-Agent den Server erstellt hat;

• src/shop_mcp/ — MCP, Schema-Introspection, SQL-Guard, Analytics-Tools;

• tests/ — automatische Safety-, Discovery- und Analytics-Tests;

• Dockerfile / docker-compose.yml — containerisierter stdio-MCP;

• NOTES.md — Entscheidungen zu Mehrdeutigkeiten der Aufgabe.