Shop Analytics MCP Server

Ein schreibgeschützter MCP-Server über stdio, der es einem KI-Agenten ermöglicht, analytische Fragen zur SQLite-Datenbank eines Online-Shops (customers, products, orders, order_items) zu beantworten — ohne sie jemals verändern zu können.

Siehe SPEC.md für die vollständige Begründung des Designs (Entscheidungsprotokoll, Schema, Sicherheitsmodell, Teststrategie).

Anforderungen

• Node.js >= 24.10.0 (erforderlich für setAuthorizer von node:sqlite, das von der unten beschriebenen Schreibschutz-Garantie verwendet wird). Prüfe das mit node --version.

• Keine weiteren Laufzeitabhängigkeiten über das hinaus, was npm ci installiert.

Related MCP server: db-mcp

Installieren → Konfigurieren → Ausführen → Verbinden

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

• shop.db ist in diesem Repository einsatzbereit enthalten. Falls du die Datenbank einmal deterministisch aus dem Schema neu erzeugen musst, führe npm run seed aus (siehe Datenbank unten).

• SHOP_DB_PATH ist optional; standardmäßig wird shop.db im aktuellen Arbeitsverzeichnis verwendet. Im Quellcode ist kein absoluter Pfad hartkodiert.

• Der Server spricht MCP ausschließlich über stdio — es gibt keinen HTTP-Server und nichts anderes zu starten.

Einen KI-Agenten verbinden

Konfigurationsbeispiele für zwei Clients findest du in config/:

• config/claude-code.mcp.json — in die .mcp.json eines Projekts kopieren oder claude mcp add-json mit dem shop-analytics-Eintrag ausführen. Trage zuerst die absoluten Pfade für args/env ein.

• config/codex.mcp.toml — die Tabelle [mcp_servers.shop-analytics] in ~/.codex/config.toml kopieren (oder in ein projektspezifisches .codex/config.toml) oder den Befehl codex mcp add aus dem Datei-Kopfkommentar verwenden.

Um den Server manuell ohne einen bestimmten Agenten auszuprobieren, verwende den tool-agnostischen MCP Inspector:

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

Tools

Der Server stellt genau 8 spezialisierte, schreibgeschützte Tools bereit — kein Tool akzeptiert oder führt beliebiges SQL aus. Jede erfolgreiche Antwort hat die Form { "data": [...], "meta": {...} }; jeder Fehler ist eine einfache, sichere, für Menschen lesbare Nachricht (kein SQL, keine Dateipfade oder Stack-Traces), gekennzeichnet mit isError: true.

from/to sind YYYY-MM-DD und definieren ein halboffenes UTC-Intervall [from, to); from muss strikt früher als to sein. Alle Finanz- und Zählkennzahlen schließen Bestellungen mit Status cancelled aus. Die vollständigen Verträge der einzelnen Tools (exakte Antwortstrukturen, Rangfolgeregeln) findest du in SPEC.md §4.

Sicherheit

Drei unabhängige, mehrstufig ineinsgreifende Schutzschichten garantieren, dass die Datenbank nie verändert wird, selbst bei einem feindseligen Prompt wie "Alle stornierten Bestellungen löschen":

1. Die SQLite-Verbindung wird mit readOnly: true geöffnet.

2. Direkt nach dem Öffnen wird PRAGMA query_only = ON gesetzt.

3. Ein SQLite-authorizer verweigert ausdrücklich jede Schreib-/DDL-Aktion (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, Transaktionen, ...).

Darüber hinaus akzeptiert kein Tool rohes SQL, Tabellennnamen oder Spaltennamen — jede Abfrage ist ein festes Prepared Statement und jede Eingabe wird mit zod validisiert und als gebundener Parameter übergeben, niemals per String-Interpolation.

Datenbank

shop.db wird aus database/schema.sql von einem deterministischen Seed-Skript erzeugt — eine neue Ausführung erzeugt jedes Mal byte-identische Daten (fester PRNG-Seed, keine Abhängigkeit von der echten Uhrzeit):

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

Das Seed-Skript stellt bei der Generierung außerdem sicher, dass der Datensatz keine mehrdeutigen Ranglisten enthält (z. B. ein einzelnes Top-Land, einen einzelnen Top-Ausgeber) und einen von null verschiedenen Umsatz für 2025 aufweist — siehe SPEC.md §3.

Entwicklung

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

Dieses Projekt wurde mit TDD entwickelt: Für jedes Modul wurde zuerst ein fehlschlagender Test geschrieben, dann die Implementierung, Tool für Tool. Die Integrationssuite deckt alle 8 Akzeptanzszenarien Ende-zu-Ende ab, dazu Eingaben mit SQL-Injection-Optik, ungültige Parameterkombinationen und verifiziert, dass der SHA-256-Hash der Datenbankdatei nach jedem Lauf unverändert bleibt.

Projektstruktur

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)