shop-mcp
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 unterdatabase/shop.db)uv(empfohlen) – führt den Server in einer isolierten Projektumgebung ohne globale Installation aus. Installation mitbrew install uv(macOS) odercurl -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.tomlOhne 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_mcpoder, mit dem in ein aktives venv installierten Paket:
python -m shop_mcpoder äquivalent:
shop-mcpDer 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 |
|
Claude Desktop |
|
Generischer Stdio |
|
Kanonisch/Standard |
|
Docker |
|
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.jsonein (oder verwenden Sie den Bereich Project MCP und committen Sie ihn).Claude Desktop: Kopieren Sie den Inhalt von
examples/mcp/claude_desktop.jsoninclaude_desktop_config.json(macOS:~/Library/Application Support/Claude/claude_desktop_config.json).Generischer Stdio-Client: Verwenden Sie
examples/mcp/generic_stdio.jsonmit 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 |
| Aufgabe 1 – Tabellen auflisten und was jede enthält |
| Schema einer Tabelle |
| Aufgabe 2 – Kunden eines Landes |
| Aufgabe 3 – Land mit den meisten Kunden |
| Aufgaben 4 und 8 – größter Ausgeber / meiste Bestellungen |
| Aufgabe 5 – Bestseller-Produkte |
| Aufgabe 6 – Top-Kategorien nach Umsatz |
| 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 aufunknownabgebildet. 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
completedundshipped.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_amountfür Bestell-/Kunden-/Jahres-Aggregationen und ausSUM(order_items.quantity * order_items.unit_price)für Produkt-/Kategorie-Aggregationen (der tatsächliche Verkaufspreis, nicht der aktuelleproducts.price).Limits sind standardmäßig 100 und werden auf maximal 1000 begrenzt;
offsetpaginiert.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 Schreibversuchsqlite3.OperationalError: attempt to write a readonly databaseauslöst.PRAGMA query_only = 1ist 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):
Alle Tabellen auflisten –
list_tablesgibtcustomers,products,orders,order_itemsjeweils mit einer Beschreibung zurück.Wie viele Kunden kommen aus Deutschland? –
count_customers_by_country("Germany")→0(ehrliche Null; kein Kunde hat eine+49-Nummer).Welches Land hat die meisten Kunden? –
rank_countries_by_customers→ Russland (RU), 150 Kunden.Wer hat das meiste Geld ausgegeben? –
top_customers(by="spend", limit=1)→ Полина Козлов,polina.kozlov340@icloud.com, Gesamtausgaben 531810.0.Top 5 der meistverkauften Produkte –
top_products(limit=5)→ nach verkauften Einheiten geordnet (Эспандер плечевой, Планшет Tab 10, …) mit Umsatz daneben.Top 3 der umsatzstärksten Kategorien –
revenue_by_category(limit=3)→ Электроника, Бытовая техника, Одежда и обувь.Umsatz im Jahr 2025 –
revenue_by_year(2025)→0mit dem Hinweisno orders in 2025(keine Jahres-Ersetzung; alle Bestellungen sind 2026).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 pytestDie 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
└── .dockerignoreDocker
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-mcpEine 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-mcpDie 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 toolscount_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.
limitdefaults to 100 (max 1000);offsetpaginates.
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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
MerchantFlow is a hosted, read-only ecommerce analytics MCP server for Shopify and WooCommerce. It gives AI assistants tenant-scoped access to revenue, profit and loss, product and SKU profitability, COGS coverage, fulfillment costs, advertising spend, ROAS, marketing performance, cohorts, LTV, and business valuation across connected commerce and marketing platforms. Connect with OAuth over Streamable HTTP. No local server installation is required.
Read-only Google Analytics 4 MCP server for AI assistants.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA 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.-
- AlicenseNot gradedqualityDmaintenanceA 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
- FlicenseNot gradedqualityDmaintenanceEnables safe, read-only analysis of an online store's SQLite database, providing schema introspection, restricted SELECT queries, and specialized analytics tools through MCP.-
- FlicenseNot gradedqualityDmaintenanceThis 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.-