SQLite Shop MCP Server 🛍️

Sicherer, leistungsfähiger MCP (Model Context Protocol)-Server in Python zum Anbinden von KI-Agenten (Claude Desktop, Cursor, Antigravity, Gemini CLI) an die relationale Datenbank des Online-Shops (shop.db).

Der Server arbeitet lokal über die Standardeingabe/-ausgabe (stdio), implementiert zweistufigen Schutz vor Änderungen (strenges Read-Only), unterstützt automatische Paginierung, verständliche Fehlerbehandlung zur Selbstkorrektur der Agenten und wird mit 100 % Testabdeckung geliefert.

🌟 Wichtigste Funktionen

1. Mehrstufige Sicherheit (Strict Read-Only):

   • Physische Ebene (SQLite Engine): Die Datenbank wird über die URI file:shop.db?mode=ro geöffnet. Jeder Schreibversuch wird physisch durch die C-Bibliothek von SQLite blockiert (OperationalError: attempt to write a readonly database).

   • Lexikalische Ebene (AST & Token Validator): Abfragen werden vor der Übergabe an die Datenbank analysiert. Erlaubt sind nur SELECT, WITH (CTE) und EXPLAIN. Alle destruktiven Operationen (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, PRAGMA writable) sowie Abfrageketten mit Semikolon werden sofort abgelehnt.

2. Intelligentes Tool-Design (4 Tools):

   • get_database_schema: vollständiger Katalog aller Tabellen, Typen, Primär-/Fremdschlüssel, Zeilenanzahl und fachlicher Hinweise.

   • describe_table: detailliertes Schema einer bestimmten Tabelle.

   • get_sample_data: Vorschau auf die Datensätze einer Tabelle ohne SQL-Schreiben.

   • execute_query: sichere Ausführung beliebiger SQL-Abfragen mit automatischer Paginierung (page, page_size), Schutz vor Kontextüberlauf (bis zu 1000 Zeilen) und Messung der Ausführungszeit.

3. Verständliche Fehlerbehandlung (Self-Correction):

   • Keine „rohen“ Python-Stacktraces nach außen.

   • Wenn beim Zugriff auf eine nicht vorhandene Spalte ein Fehler auftritt, schlägt der Server die Liste der verfügbaren Spalten in der Tabelle vor, sodass das Modell sich sofort selbst korrigieren kann.

4. Portabilität:

   • Keine fest codierten absoluten Pfade. Der Pfad wird automatisch relativ zum Projekt oder über die Umgebungsvariable SHOP_DB_PATH bestimmt.

5. Tests und Docker:

   • 51 pytest-Autotests (Sicherheit, Datenbank, Integration, alle 8 Aufgaben aus der Aufgabenstellung).

   • Fertige Dockerfile und docker-compose.yml.

Related MCP server: Read-Only SQLite Shop Database MCP Server

🏗️ Architektur

[ AI Agent: Claude / Cursor / Antigravity ]
                   │  (stdio JSON-RPC)
                   ▼
           [ server.py ] (MCPServer stdio transport)
                   │
     ┌─────────────┴─────────────┐
     ▼                           ▼
[ src/security.py ]       [ src/db.py ]
(Валидация SQL,           (Подключение в mode=ro,
 защита от инъекций)       пагинация, сбор метрик)
                                 │
                                 ▼
                       [ shop.db (mode=ro) ]

Datenbankschema shop.db

customers (150 строк)
    │
    └──< orders (750 строк)
             │
             └──< order_items (1900 строк) >── products (50 строк)

🚀 Schnellstart

1. Installation der Abhängigkeiten (Install)

Erforderlich ist Python 3.10+:

# Клонируйте репозиторий или перейдите в папку проекта
cd HW_MCP

# Установите зависимости
pip install -r requirements.txt

2. Konfiguration (Configure)

Standardmäßig sucht der Server die Datei shop.db im Projektstamm. Bei Bedarf kann der Pfad über die Umgebungsvariable überschrieben werden:

# Windows (PowerShell)
$env:SHOP_DB_PATH = "C:\path\to\shop.db"

# Linux / macOS
export SHOP_DB_PATH="/path/to/shop.db"

3. Server starten (Run)

Der Server wird im stdio-Modus gestartet:

python server.py

🤖 Verbindung zu KI-Agenten (Connect to Agent)

Claude Desktop

Fügen Sie die Konfiguration in die Einstellungsdatei von Claude Desktop ein:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": [
        "C:\\Users\\user\\OneDrive\\BackToTheFuture\\HW_MCP\\server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Cursor

Gehen Sie in Cursor zu Settings > Features > MCP > Add New MCP Server:

• Name: sqlite-shop

• Type: command

• Command: python C:\Users\user\OneDrive\BackToTheFuture\HW_MCP\server.py

Oder erstellen Sie im Stammverzeichnis des Projekt-Workspace eine Datei .cursor/mcp.json:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

Antigravity / Gemini CLI

Fügen Sie den Abschnitt in mcp_config.json hinzu:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

🛠️ Beschreibung der Tools (MCP Tools)

1. get_database_schema

Gibt die vollständige Struktur aller Tabellen, die Datentypen der Spalten, die Primär- und Fremdschlüssel, die Zeilenanzahl und erläuternde Hinweise zu den Daten zurück.

2. describe_table(table_name: str)

Gibt das detaillierte Schema der Spalten und Einschränkungen der ausgewählten Tabelle zurück (customers, products, orders, order_items).

3. get_sample_data(table_name: str, limit: int = 10)

Gibt Beispielzeilen aus der Tabelle zur vorläufigen Analyse des Datenformats zurück.

4. execute_query(query: str, page: int = 1, page_size: int = 50)

Führt eine sichere SQL-Leseabfrage aus.

• Parameter:

  • query (string, erforderlich): SQL-Abfrage (SELECT, WITH ... SELECT, EXPLAIN).

  • page (int, Standard: 1): Seitennummer.

  • page_size (int, Standard: 50, max: 1000): Anzahl der Zeilen pro Seite.

• Antwortformat:

  {
    "rows": [
      { "id": 1, "first_name": "Арина", "email": "..." }
    ],
    "page": 1,
    "page_size": 50,
    "total_rows_in_page": 50,
    "has_more": true,
    "execution_time_ms": 1.24
  }

📊 Lösung der 8 Kontrollaufgaben aus der Aufgabenstellung

Alle Abfragen wurden mit echten Daten aus shop.db geprüft:

Sicherheitsprüfung (Safety Requirement)

Abfrage des Agenten:

Delete all cancelled orders.

Antwort des MCP-Servers:

{
  "error": true,
  "error_type": "PermissionDenied",
  "message": "PermissionDenied: Modifying or destructive operations are not permitted (read-only server). Statement starts with 'DELETE'."
}

Die Datenbank bleibt vollständig unversehrt.

🧪 Automatische Tests ausführen

Im Projekt ist eine vollständige Testsuite auf Basis von pytest implementiert:

• tests/test_security.py — prüft die Blockierung destruktiver Ausdrücke, SQL-Injektionen und Abfrageketten.

• tests/test_db.py — prüft den physischen mode=ro, das Schema, die Paginierung und Fehlerhinweise.

• tests/test_server.py — Integrationstests für Tool-Aufrufe und Validierung aller 8 Aufgaben der Hausaufgabe.

pytest tests/ -v

Ergebnis:

============================= 51 passed in 0.87s ==============================

🐳 Ausführung in Docker

Build und Start des Containers:

# Сборка образа
docker build -t sqlite-shop-mcp .

# Запуск с монтированием базы
docker run -i --rm -v $(pwd)/shop.db:/app/shop.db:ro sqlite-shop-mcp

Oder über docker-compose:

docker-compose run --rm sqlite-shop-mcp

📁 Repository-Struktur

HW_MCP/
├── .agent/                  # Интеграция с OpenSpec агентами
├── openspec/                # Спецификация требований (OpenSpec living specs & changes)
├── src/
│   ├── __init__.py
│   ├── config.py            # Разрешение путей и настроек SQLite URI
│   ├── security.py          # Валидатор SQL-запросов (Read-Only enforcement)
│   └── db.py                # Слой SQLite (mode=ro, пагинация, сбор схем)
├── tests/
│   ├── test_security.py     # Тесты безопасности SQL
│   ├── test_db.py           # Тесты слоя БД и пагинации
│   └── test_server.py       # Интеграционные тесты 8 аналитических задач
├── Dockerfile               # Контейнеризация сервиса
├── docker-compose.yml
├── mcp_config_example.json  # Примеры конфигов для Claude Desktop, Cursor, Antigravity
├── requirements.txt         # Зависимости Python
├── server.py                # Главная точка входа MCP-сервера
├── shop.db                  # База данных SQLite интернет-магазина
└── README.md                # Полная документация проекта

📜 Lizenz

MIT License.