Shop MCP Server

Lokaler MCP-Server für die Analyse der SQLite-Datenbank eines Online-Shops. Der KI-Agent ruft ein MCP-Tool auf, der Server wandelt die Anfrage in ein sicheres SQL SELECT um, liest direkt shop.db und gibt ein strukturiertes Ergebnis zurück.

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

Funktionen

• direkte Verbindung zu SQLite ohne HTTP und separaten DB-Server;

• MCP-Transport stdio;

• Erkennung von query_shop und inspect_database über tools/list;

• acht Beispielaufgaben in der Beschreibung und im JSON-Schema des Tools;

• Klartext, JSON-Intent oder fertiges sicheres SELECT;

• Ausschluss von Bestellungen mit Status cancelled aus der gesamten Analyse;

• Paginierung und Begrenzung des Ergebnisses;

• mehrstufiger Read-only-Schutz.

Related MCP server: Shop Analytics MCP Server

Installation

Erforderlich ist Python 3.11 oder neuer.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Die vorbereitete Datenbank befindet sich bereits in data/shop.db. Sie enthält 150 Kunden, das Feld customers.country ist bei allen Kunden ausgefüllt, und 45 Kunden gehören zu Germany.

Erneute Vorbereitung der Datenbank

Die ursprüngliche Datenbank wird nicht verändert. Der Befehl erstellt eine neue Arbeitskopie und fügt country TEXT NOT NULL mit reproduzierbaren synthetischen Werten hinzu:

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

Die Verteilung hängt nur von customers.id ab, daher liefert die erneute Vorbereitung dieselben Werte. Die Länder sind Testdaten und beschreiben nicht den tatsächlichen Standort der Kunden.

Pfadkonfiguration

Der Pfad wird in folgender Reihenfolge bestimmt:

1. SHOP_DB_PATH;

2. JSON-Datei aus SHOP_MCP_CONFIG oder config/shop_mcp.json;

3. data/shop.db relativ zum Arbeitsverzeichnis.

Ein Beispiel für die Umgebungsvariable befindet sich in .env.example, und die MCP-Client-Konfiguration in config/mcp.example.json. Ersetzen Sie /absolute/path/to/MCPDeveloper durch den absoluten Pfad zum Projekt.

Start

Normalerweise startet der MCP-Client den Server aus seiner Konfiguration. Für den manuellen Start des Prozesses:

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout ist für MCP JSON-RPC reserviert. Die Diagnose wird nicht in den Protokollstrom ausgegeben.

Werkzeuge

inspect_database

Argumente:

{"action": "list_tables"}

oder:

{"action": "describe_table", "table": "customers"}

query_shop

Argumente:

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

Beispiele, die über tools/list deklariert werden:

1. Welche Tabellen gibt es in der Datenbank und welche Felder enthalten sie?

2. Wie viele Kunden kommen aus Deutschland?

3. In welchem Land gibt es die meisten Kunden?

4. Welcher Kunde hat am meisten ausgegeben? Gib Name, E-Mail und Gesamtsumme zurück.

5. Zeige die Top-5-Produkte nach verkaufter Menge und Umsatz.

6. Zeige die Top-3-Kategorien nach Umsatz.

7. Wie hoch war der Umsatz im Jahr 2025?

8. Welcher Kunde hat die meisten Bestellungen aufgegeben?

Ein strukturierter Intent kann übergeben werden:

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

Oder eine fertige Abfrage:

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

Geschäftsregeln

• orders.status = 'cancelled' fließt nicht in die Kennzahlen ein.

• Kundenausgaben und Jahresumsatz werden anhand von orders.total_amount berechnet.

• Der Umsatz von Produkten und Kategorien wird als quantity * unit_price berechnet.

• Das Jahresintervall ist halboffen: vom 1. Januar einschließlich bis zum 1. Januar des Folgejahres ausschließlich.

• In der mitgelieferten Datenbank gehören alle Bestellungen zum Jahr 2026, daher beträgt der Umsatz für 2025 0.

Sicherheit

Der Server öffnet SQLite über mode=ro, aktiviert query_only, richtet einen SQLite-Authorizer ein, verbietet mehrere Anweisungen, DML, DDL, ATTACH, verändernde PRAGMA, das Laden von Erweiterungen und begrenzt die Ausführungszeit.

Jeder Versuch, eine andere Operation als SELECT auszuführen, gibt eine präzise Antwort zurück:

Не доступный вариант запроса

Interne SQLite-Fehler, Stack-Traces und lokale Pfade werden nicht an den Client zurückgegeben.

Prüfung

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

Die Tests umfassen den realen Start des MCP-Servers als Subprozess, die Verbindung von ClientSession über stdio, tools/list, den Aufruf beider Tools, analytische Szenarien und Versuche, die Datenbank zu verändern.

Die vollständige genehmigte Spezifikation befindet sich in docs/specification.md.