shop-db MCP Server

Ein schreibgeschützter Model Context Protocol-Server, der KI-Agenten analytischen Zugriff auf eine E-Commerce-SQLite-Datenbank (customers, orders, order_items, products) gewährt – ohne die Möglichkeit, Daten zu verändern.

Entwickelt für Node.js v24.19+, führt TypeScript-Quelldateien direkt aus (kein Build-Schritt) unter Verwendung von nativem node:sqlite und node:test.

Setup

npm install

Das Repository enthält bereits eine befüllte ./shop.db im Projektstamm – kein Seed-Schritt ist erforderlich. Nichts in npm start oder npm test schreibt darauf: Der Server öffnet sie schreibgeschützt, und die Testsuite erstellt ihre eigenen Wegwerf-Datenbanken unter tests/ aus tests/fixtures/seed.sql.

Related MCP server: shop-mcp

Server ausführen

npm start

Der Server kommuniziert über stdio (StdioServerTransport) – er soll von einem MCP-Client (Claude Code, Claude Desktop usw.) gestartet werden, nicht interaktiv ausgeführt werden.

Tests

npm test

Führt node --test gegen tests/ aus und deckt SQL-Validierungs-Grenzfälle ab (Mutationsschlüsselwörter, Kommentar-Umgehung, Multi-Statement-Injection, CTEs, EXPLAIN) sowie die drei MCP-Tools Ende-zu-Ende gegen isolierte Testdatenbanken, die aus tests/fixtures/seed.sql erstellt wurden. Die eingecheckte ./shop.db wird von der Testsuite nie gelesen oder beschrieben.

Konfiguration des Datenbankpfads

Standardmäßig liest der Server ./shop.db (relativ zum Arbeitsverzeichnis, aus dem er gestartet wird). Überschreiben Sie dies mit der Umgebungsvariable DB_PATH:

DB_PATH=/absolute/path/to/shop.db npm start

Tools

• list_tables – listet die 4 Tabellen mit einer kurzen Beschreibung jeder Tabelle auf.

• describe_table – Spaltendefinitionen, Typen, Primärschlüssel und bis zu 3 Beispielzeilen für eine Tabelle (tableName) oder alle Tabellen (weglassen).

• read_query – führt eine schreibgeschützte SELECT/WITH/EXPLAIN/PRAGMA-Abfrage aus (query, erforderlich) und gibt bis zu limit Zeilen zurück (optional, Standard 100, max. 1000). Jeder Mutationsversuch (INSERT, UPDATE, DELETE, DROP, ...) wird mit einer klaren Fehlermeldung abgelehnt, selbst wenn er mit SQL-Kommentaren getarnt oder in eine CTE verpackt ist.

KI-Agenten-Konfiguration

{
  "mcpServers": {
    "shop-db": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.ts"],
      "env": {
        "DB_PATH": "/absolute/path/to/shop.db"
      }
    }
  }
}

Projektdokumentation

• AGENTS.md – Anweisungen für KI-Codierungsagenten, die an diesem Repository arbeiten (auch als CLAUDE.md über Symlink geladen).

• CONTEXT.md – Domänenmodell und Sicherheitsarchitektur.