Skip to main content
Glama

shop-mcp

Ein schreibgeschützter Model Context Protocol-Server, der Analysetools für die SQLite-Datenbank shop.db eines Online-Shops bereitstellt (Kunden, Produkte, Bestellungen, Bestellartikel). Er ist dafür ausgelegt, mit einem KI-Agenten verbunden zu werden, damit der Agent analytische Fragen zu den Daten beantworten kann, ohne sie jemals verändern zu können.

Der Server spricht MCP über stdio, öffnet die Datenbank im Nur-Lese-Modus und stellt eine kleine Menge spezialisierter, parametrisierter Tools bereit, deren Beschreibungen die Domänenregeln kodieren (welche Bestellstatus als Umsatz zählen, wie das Land eines Kunden abgeleitet wird, woher das Geld stammt). Es gibt kein generisches SQL-Tool und kein Schreib-Tool – ein destruktiver Prompt wie „Alle stornierten Bestellungen löschen“ kann nicht ausgeführt werden.

Der MCP-Servercode in diesem Repository wurde von einem KI-Codier-Agenten (Cursor) erstellt, gemäß der Hausaufgaben-Anforderung, dass der Server nicht von Hand geschrieben werden darf.

Voraussetzungen

  • Python 3.11 oder neuer

  • Die SQLite-Datenbank shop.db (versioniert unter database/shop.db)

  • uv (empfohlen) – führt den Server in einer isolierten Projektumgebung ohne globale Installation aus. Installation mit brew install uv (macOS) oder curl -LsSf https://astral.sh/uv/install.sh | sh.

Related MCP server: mcp-data-analyst

Install

Mit uv (empfohlen) – kein manuelles venv oder pip nötig; uv löst das Projekt und seine Abhängigkeiten beim ersten Lauf aus pyproject.toml auf:

uv sync          # create / refresh the project's .venv from pyproject.toml

Ohne uv – erstellen Sie ein Virtualenv und installieren Sie das Paket selbst:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

Dadurch werden das mcp-SDK und das Paket shop-mcp installiert (das den Einstiegspunkt python -m shop_mcp und das Konsolenskript shop-mcp bereitstellt).

Konfiguration

Der Server öffnet die Datenbank unter database/shop.db relativ zum Prozessarbeitsverzeichnis (ProjectRoot). Es sind keine Umgebungsvariablen erforderlich.

Wenn er über uv run --directory <project> gestartet wird (siehe Client-Konfigurationen unten), setzt uv das Arbeitsverzeichnis auf das Projektstammverzeichnis, sodass die versionierte Datenbank automatisch gefunden wird.

Fehlt database/shop.db, wird beim Start ein klarer Konfigurationsfehler ausgegeben, der das aktuelle Arbeitsverzeichnis enthält (kein Stacktrace, kein stiller Fallback). Stellen Sie sicher, dass die MCP-Client-Konfiguration cwd auf das Repository-Stammverzeichnis setzt.

Ausführen

uv run python -m shop_mcp

oder, mit dem in ein aktives venv installierten Paket:

python -m shop_mcp

oder äquivalent:

shop-mcp

Der Server liest JSON-RPC über stdin und schreibt auf stdout. Normalerweise führen Sie ihn nicht direkt aus – Ihr KI-Agent startet ihn für Sie (siehe unten).

Mit einem Agenten verbinden

Einsatzbereite MCP-Client-Konfigurationen sind unter examples/mcp/ versioniert und laufen ohne weitere Einrichtung, sobald uv installiert ist:

Client

Konfigurationsdatei

Cursor

examples/mcp/cursor.json

Claude Desktop

examples/mcp/claude_desktop.json

Generischer Stdio

examples/mcp/generic_stdio.json

Kanonisch/Standard

examples/mcp/shop.json

Docker

examples/mcp/docker.json

Jede Konfiguration sieht so aus (ersetzen Sie den --directory-Pfad durch den absoluten Pfad dieses Repository auf Ihrer Maschine):

{
  "mcpServers": {
    "shop": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/internet-shop-mcp", "python", "-m", "shop_mcp"]
    }
  }
}

uv run --directory <project> setzt das Arbeitsverzeichnis auf das Projektstammverzeichnis und verwendet das .venv des Projekts, sodass der Server database/shop.db automatisch findet. Dieselbe Konfiguration ist über Maschinen hinweg portabel (nur der --directory-Pfad ändert sich).

Wenn Sie uv nicht verwenden möchten, installieren Sie das Paket selbst in eine venv (siehe Installation), verwenden Sie command: "python" und setzen Sie in Ihrer MCP-Client-Konfiguration cwd auf das Repository-Stammverzeichnis.

  • Cursor: Öffnen Sie Settings → MCP → Add MCP Server und fügen Sie den Inhalt von examples/mcp/cursor.json ein (oder verwenden Sie den Bereich Project MCP und committen Sie ihn).

  • Claude Desktop: Kopieren Sie den Inhalt von examples/mcp/claude_desktop.json in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).

  • Generischer Stdio-Client: Verwenden Sie examples/mcp/generic_stdio.json mit jedem Client, der MCP über stdio spricht.

Nach der Verbindung sieht der Agent acht Tools: list_tables, describe_table, count_customers_by_country, rank_countries_by_customers, top_customers, top_products, revenue_by_category, revenue_by_year.

Tools

Tool

Antwortet auf

list_tables

Aufgabe 1 – Tabellen auflisten und was jede enthält

describe_table(table)

Schema einer Tabelle

count_customers_by_country(country?)

Aufgabe 2 – Kunden eines Landes

rank_countries_by_customers(limit)

Aufgabe 3 – Land mit den meisten Kunden

top_customers(by, limit, offset)

Aufgaben 4 und 8 – größter Ausgeber / meiste Bestellungen

top_products(limit, metric, offset)

Aufgabe 5 – Bestseller-Produkte

revenue_by_category(limit, offset)

Aufgabe 6 – Top-Kategorien nach Umsatz

revenue_by_year(year)

Aufgabe 7 – Umsatz für ein Jahr

In den Tool-Beschreibungen eingebaute Domänenregeln (vollständige Begründung siehe CONTEXT.md und docs/adr/):

  • Land wird aus der Telefonvorwahl (E.164) des Kunden abgeleitet. Es gibt keine Spalte country. +49 → Deutschland, +7 → Russland. Eine nicht erkannte Vorwahl wird auf unknown abgebildet. Das Tool akzeptiert einen vollständigen Namen („Germany“) oder einen ISO-Alpha-2-Code (DE) und gibt beides zurück.

  • Umsatz / Ausgaben zählen nur Bestellungen mit Status completed und shipped.

  • Meiste Bestellungen zählt jeden Bestellstatus außer cancelled.

  • Bestseller ordnet Produkte nach verkauften Einheiten; Umsatz ist ein sekundäres Feld.

  • Geld stammt aus orders.total_amount für Bestell-/Kunden-/Jahres-Aggregationen und aus SUM(order_items.quantity * order_items.unit_price) für Produkt-/Kategorie-Aggregationen (der tatsächliche Verkaufspreis, nicht der aktuelle products.price).

  • Limits sind standardmäßig 100 und werden auf maximal 1000 begrenzt; offset paginiert.

  • Fehler werden dem Agenten als kurze Klartextmeldungen zurückgegeben (z. B. Invalid year: must be a 4-digit integer); Stack-Traces gehen nur auf stderr.

Sicherheit

Die Datenbank ist konstruktionsbedingt schreibgeschützt:

  • SQLite wird mit file:<path>?mode=ro (uri=True) geöffnet, sodass jeder Schreibversuch sqlite3.OperationalError: attempt to write a readonly database auslöst.

  • PRAGMA query_only = 1 ist als zusätzliche Absicherung gesetzt.

  • Es ist kein Schreib- und kein generisches SQL-Tool vorhanden. Die einzigen Tools sind die acht oben genannten rein lesenden Analysetools.

Ein Test (tests/test_safety.py) stellt sicher, dass ein Schreibversuch eine Exception auslöst, dass kein Schreib-Tool beworben wird und dass die Datenbankdatei nach jedem Ausführen der Tools Byte-für-Byte unverändert bleibt.

End-to-End-Verifizierung

Die acht Hausaufgaben-Aufgaben wurden mit einem verbundenen KI-Agenten verifiziert. Erwartete Ergebnisse auf den versionierten Daten (150 Kunden, alle mit +7-Nummern; 750 Bestellungen, alle aus 2026):

  1. Alle Tabellen auflisten – list_tables gibt customers, products, orders, order_items jeweils mit einer Beschreibung zurück.

  2. Wie viele Kunden kommen aus Deutschland? – count_customers_by_country("Germany") → 0 (ehrliche Null; kein Kunde hat eine +49-Nummer).

  3. Welches Land hat die meisten Kunden? – rank_countries_by_customers → Russland (RU), 150 Kunden.

  4. Wer hat das meiste Geld ausgegeben? – top_customers(by="spend", limit=1) → Полина Козлов, polina.kozlov340@icloud.com, Gesamtausgaben 531810.0.

  5. Top 5 der meistverkauften Produkte – top_products(limit=5) → nach verkauften Einheiten geordnet (Эспандер плечевой, Планшет Tab 10, …) mit Umsatz daneben.

  6. Top 3 der umsatzstärksten Kategorien – revenue_by_category(limit=3) → Электроника, Бытовая техника, Одежда и обувь.

  7. Umsatz im Jahr 2025 – revenue_by_year(2025) → 0 mit dem Hinweis no orders in 2025 (keine Jahres-Ersetzung; alle Bestellungen sind 2026).

  8. Meiste Bestellungen – top_customers(by="order_count", limit=1) → София Яковлев, sofiya.yakovlev284@yandex.ru, 15 Bestellungen.

Der destruktive Prompt „Alle stornierten Bestellungen löschen“ wird abgelehnt: Es gibt kein Tool, das ihn akzeptiert, und die schreibgeschützte Verbindung weist jeden Schreibversuch auf SQLite-Ebene zurück.

Tests

uv run --extra dev pytest
# or, with the package installed in an active venv:
pip install -e ".[dev]"
python -m pytest

Die Suite deckt ab: den Smoke-Test (Server startet über stdio und beantwortet Handshake/list_tools), den Happy Path jedes Tools, die Domänenregeln (Ausgaben schließen nicht umsatzrelevante Status aus, Bestellanzahl schließt stornierte aus, Produkte ordnen nach Einheiten), Randfälle (Deutschland → 0, 2025 → 0 mit Hinweis, unbekanntes Land, ungültiges year/metric/by-Argument, Limit-Begrenzung, Pagination) sowie die Sicherheitsgarantien (Schreibversuch löst Exception aus, keine Schreibwerkzeuge, Datenbankdatei unverändert).

Docker (Bonus)

Siehe unten im Abschnitt „Docker“ für eine containerisierte Ausführung.

Projektstruktur

internet-shop-mcp/
├── database/
│   └── shop.db                  # the read-only database
├── pyproject.toml               # package + dependency declaration
├── README.md
├── CONTEXT.md                   # domain glossary
├── docs/adr/                    # ADR-0001..0005
├── src/shop_mcp/
│   ├── __main__.py              # `python -m shop_mcp`
│   ├── main.py                  # server wiring + tool registration
│   ├── config.py                # database/shop.db resolution
│   ├── db.py                    # read-only SQLite connection
│   ├── country.py               # phone-prefix → country mapping
│   └── tools.py                 # tool implementations
├── tests/                       # pytest suite mirroring src
├── examples/mcp/                # agent connection configs
├── Dockerfile
└── .dockerignore

Docker

Build und Start des Servers in einem Container. Die Datenbank wird in das Image unter /app/database/shop.db kopiert (gleiche Konvention wie bei der lokalen Entwicklung).

docker build -t shop-mcp .
docker run --rm -i shop-mcp

Eine passende MCP-Client-Konfiguration mit Docker:

{
  "mcpServers": {
    "shop": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "shop-mcp"]
    }
  }
}

Um eine eigene Datenbank zu mounten statt der gebündelten:

docker run --rm -i -v "$PWD/database:/app/database:ro" shop-mcp

Die Garantien für den Schreibschutz bleiben im Container erhalten: Die Verbindung nutzt mode=ro und query_only=1, und auch hier wird ein destruktiver Prompt weiterhin abgelehnt.

Available Tools

8 tools
count_customers_by_countryA

Count customers by country. The country is NOT a column — it is derived from the customer's phone-number prefix (E.164), so do not look for a country column. With no argument, returns counts per country as a list of {country_code, country_name, customer_count}. With a country argument (either a full name like 'Germany' or an ISO alpha-2 code like 'DE'), returns the count for that country only — an honest 0 if there are no customers there. An unknown country name returns an error.

Inputs: country.

describe_tableA

Describe the schema of one table: columns (name, type, not_null, default, primary_key) and foreign keys. Use this before building any mental model of how tables relate. Returns {table, columns, foreign_keys}. Pass the table name (one of: customers, products, orders, order_items).

Inputs: table (required).

list_tablesA

List every table in the shop database with a short description of what each table holds. Use this first to understand what entities are available. Returns a list of {name, description}.

Inputs: no named parameters.

rank_countries_by_customersA

Rank countries by number of customers, highest first. The country is derived from each customer's phone-number prefix (there is no country column). Returns a list of {country_code, country_name, customer_count}. limit defaults to 100 and is clamped to a maximum of 1000.

Inputs: limit.

revenue_by_categoryA

Rank product categories by revenue, joining orders -> order_items -> products. Only 'completed' and 'shipped' orders count. Revenue is SUM(order_items.quantity * order_items.unit_price) using the actual sale price. Returns a list of {category, revenue}. limit defaults to 100 (max 1000); offset paginates.

Inputs: limit, offset.

revenue_by_yearA

Return total revenue for a single year (a 4-digit integer, e.g. 2025). Revenue is SUM(orders.total_amount) over orders whose order_date falls in that year and whose status is 'completed' or 'shipped'. A year with no qualifying orders returns revenue 0 with a 'no orders in ' note — it does not substitute a different year. An invalid year returns an error.

Inputs: year (required).

top_customersA

Rank customers either by total spend or by number of placed orders.

  • by='spend': sums orders.total_amount over orders with status 'completed' or 'shipped' only (new, processing, cancelled do not count as earned). Returns first_name, last_name, email, total_spend.

  • by='order_count': counts orders whose status is NOT 'cancelled'. Returns first_name, last_name, email, order_count. Customer names are returned as separate first_name and last_name fields. limit defaults to 100 (max 1000); offset paginates.

Inputs: by, limit, offset.

top_productsA

Rank products by units sold (metric='units', default) or by revenue (metric='revenue'). Only 'completed' and 'shipped' orders count. Money is computed from order_items.unit_price (the actual sale price), not the current products.price. Returns a list of {name, units_sold, revenue}. When metric='units', ranking is by units_sold and revenue is a secondary field. limit defaults to 100 (max 1000); offset paginates.

Inputs: limit, metric, offset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation3/5

    Most tools are clearly distinct, but count_customers_by_country and rank_countries_by_customers return the same country-level customer counts with only ordering/filtering differences. The other tools, such as top_customers and top_products, are well separated by their selection criteria.

    Naming Consistency4/5

    Namess are mostly predictable and use snake_case with clear intent, like list_tables and describe_table. The main inconsistency is that some tools follow imperative verb names while others use noun phrases like top_customers or revenue_by_category, but the pattern remains readable.

    Tool Count5/5

    Eight tools is well-suited for a read-only analytics server covering schema inspection and common shop metrics. Each tool has a clear role, and the count does not feel excessive or thin.

    Completeness4/5

    The toolset covers the main analytics surface: customer geography, top customers, top products, category revenue, and annual revenue. It lacks order-level or product-level detail queries and finer time-based filters, but the visible analytical workflows are complete enough for most shop insight requests.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A secure MCP server that exposes a SQLite database to AI agents with Role-Based Access Control, supporting authentication, customer/order/user management, and audit logging.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A natural-language data analyst MCP server that lets users query SQLite sales datasets via MCP tools (list_tables, aggregate, time_series, run_sql) with read-only SQL safety guards, returning results through a FastAPI dashboard.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables safe, read-only analysis of an online store's SQLite database, providing schema introspection, restricted SELECT queries, and specialized analytics tools through MCP.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      This MCP server lets an AI agent securely connect to a read-only SQLite store database, inspect its tables and schema, and run analytical SQL queries without modifying any data.
      -