Shop Database MCP Server

Dieses Projekt stellt eine mitgelieferte SQLite-Shop-Datenbank MCP-kompatiblen KI-Agenten über drei allgemein einsetzbare, schreibgeschützte Tools bereit. Ein Agent kann das tatsächliche Schema entdecken, analytisches SQL formulieren, Daten verknüpfen und aggregieren und Fragen identifizieren, die die Datenbank nicht beantworten kann. Der Server enthält keine fragenspezifische Geschäftslogik und kann die Datenbank nicht verändern.

Anforderungen und Installation

• Python 3.10 oder neuer

• Die mitgelieferte database/shop.db

Aus dem Projektstammverzeichnis:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Das Requirements-Manifest deklariert das offizielle Python-MCP-SDK (mcp>=2,<3) und pytest für Tests, ohne separates Web-Framework, ORM, SQL-Parser oder Datenbanktreiber.

Related MCP server: db-mcp

Datenbankkonfiguration

Standardmäßig öffnet der Server database/shop.db. Der Standardwert wird aus den Projektdateien aufgelöst und funktioniert daher auch, wenn der MCP-Client den Prozess aus einem anderen Arbeitsverzeichnis startet.

Um eine andere vorhandene SQLite-Datei auszuwählen, setzen Sie SHOP_DB_PATH vor dem Start:

export SHOP_DB_PATH=/absolute/path/to/another.db
python server.py

Die Angabe muss eine vorhandene reguläre Datei benennen. Ein fehlender Pfad führt zu einem klaren Fehler und wird niemals als leere Datenbank angelegt. .env.example ist nur Dokumentation: Das Projekt hat keine dotenv-Abhängigkeit und lädt diese Datei nicht automatisch. Exportieren Sie die Variable in der Shell oder setzen Sie sie in der MCP-Client-Konfiguration.

Ausführung über stdio

Mit aktiver virtueller Umgebung:

python server.py

Der Prozess verwendet MCP über Standardeingabe und Standardausgabe. Ein direkter Start erscheint normalerweise untätig, da er auf einen MCP-Client wartet. Es ist kein HTTP-Server oder anderer unterstützender Dienst erforderlich. Die Standardausgabe ist für MCP-Protokollmeldungen reserviert; Diagnosemeldungen gehören in die Standardfehlerausgabe.

Tools

list_tables()

Verwenden Sie dies zuerst, um benutzersichtbare Tabellen zu entdecken. Es gibt Folgendes zurück:

{"tables": ["table_a", "table_b"]}

Interne sqlite_%-Objekte sind ausgeschlossen und die Tabellennamen sind sortiert.

describe_table(table_name)

Verwenden Sie dies nach der Erkundung und vor der Formulierung von SQL. Es validiert table_name anhand der echten Benutzertabellen und gibt den Tabellennamen, sortierte Spalten, deklarierte Typen, Nullbarkeit, Primärschlüsselpositionen und verfügbare Fremdschlüsselbeziehungen zurück.

query_database(sql, max_rows=100)

Führt eine analytische, schreibgeschützte SELECT- oder schreibgeschützte WITH-Anweisung aus. Sie unterstützt Joins, Filter, Sortierung, Gruppierung, Aggregate und Datumsbedingungen. Untersuchen Sie unbekannte Tabellen zuerst mit list_tables und describe_table.

Das Ergebnis hat diese positionsbezogene Form:

{
  "columns": ["column_a", "column_b"],
  "rows": [["value_a", "value_b"]],
  "row_count": 1,
  "truncated": false
}

Zeilen sind Arrays, sodass doppelte Spaltennamen bei Joins keine Werte überblenden. max_rows muss eine Ganzzahl von 1 bis 100 sein. Der Standardwert ist 100, kein Aufruf gibt mehr als 100 Zeilen zurück, und truncated gibt an, ob eine weitere Zeile vorhanden war. Bevorzugen Sie Aggregation und Filterung gegenüber der Rückgabe großer Rohdatensätze.

SQLite-Werte bleiben normalerweise null, Ganzzahl, endliche reelle Zahl oder Text. Werte, die JSON nicht direkt darstellen kann, verwenden explizite Tagger-Objekte:

• BLOB: {"type":"blob","hex":"80ff"}

• positive Infinität: {"type":"real","value":"infinity"}

• negative Infinität: {"type":"real","value":"-infinity"}

• defensive NaN-Darstellung: {"type":"real","value":"nan"}

Diese Tags verhindern, dass Python-Bytes oder nicht endliche Floats in das MCP-JSON gelangen, und halten SQL NULL von Infinität getrennt.

Schreibschutz-Garantie

Das schreibgeschützte Verhalten wird durch drei technische Ebenen erzwungen:

1. Jede Laufzeitverbindung verwendet eine prozentkodierte SQLite-URI mit mode=ro.

2. Jede Verbindung aktiviert PRAGMA query_only = ON.

3. Die Abfragegrenze akzeptiert eine einzelne SELECT/WITH-Anweisung und installiert einen SQLite-Autorisierer, der Lesevorgänge allowlistet und gleichzeitig Schreibvorgänge, DDL, Attach/Detach, Transaktionen, unsichere PRAGMAs und unsichere Funktionen verweigert.

Die Implementierung verwendet für Aufrufer-SQL einen einzigen Connection.execute-Aufruf und niemals executescript. Die Stichwort-Klassifizierung ist nicht die Sicherheitsgrenze: Die schreibgeschützte SQLite-Verbindung und der nur-lesende Modus bleiben unter dem Autorisierer aktiv. Tests, dass INSERT, UPDATE, DELETE, Schemaänderungen, VACUUM, ATTACH, Transaktionszustandsänderungenund Bypass-förmige Anweisungen die Wegwerfdatenbanken unverändert lassen.

Fellende Tabellen, ungültige Limits, fehlerhaftes SQL, verbotene Operationen und SQLite-Ausführungsfehler werden als prägnante MCP-Tool-Fehler zurückgegeben. Normaler Tool-Fehler enthalten keine Python-Tracebacks, und dieselbe MCP-Sitzung bleibt nach einem behebbaren Fehler weiterhin verwendbar.

Tests und Plausibilitätsprüfungen

Führen Sie diese aus dem Projektstammverzeichnis mit aktiver .venv aus:

python -m pytest -q
python -m compileall -q server.py shop_mcp tests
python -m pytest -q tests/test_mcp_integration.py
python -m json.tool examples/mcp-config.example.json >/dev/null

Der Integrationstest startet server.py als echten Unterprozess mit dem STDIO-Client des offiziellen Python-SDKs, initialisiert eine MCP-Sitzung, ruft alle drei Tools auf, prüft die Fehlerbehinderung und verwendet nur eine Wegwerfdatenbank.

MCP-Startkonfiguration

examples/mcp-config.example.json ist ein generisches Client-Beispiel. Ersetzen Sie jeden Platzhalter /absolute/path/to/shop-mcp. Entfernen Sie das env-Objekt, um die Standarddatenbank zu verwenden.

Referenz für den eigenständigen Codex-Kovorstand

Dieser Unterabschnitt gilt für einen eigenständigen Codex-Kovorstand, nicht für die codex-acp-Integration von PhpStorm. Die offizielle OpenAI-MCP-Dokumentation bestätigt, dass die CLI lokale STDIO-Server unterstützt und die persönliche ~/.codex/config.toml oder eine vertrauenswürdige Projekt-codex/config.toml liest.

Für einen nativen POSIX/WSL-Codex-CLI ist der Befehl der Projekt-Interpreter und das Argument ist server.py:

[mcp_servers.shop_database]
command = "/absolute/path/to/shop-mcp/.venv/bin/python"
args = ["/absolute/path/to/shop-mcp/server.py"]

# Optional override; omit this table to use database/shop.db.
[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/another.db"

Den vorgesehenen PhpStorm-Codex-Host verbinden

Der vorgesehene Projekthost ist:

PhpStorm 2026.2 AI Chat -> codex-acp 1.6.2 -> gebündeltes codex-cli 0.148.0

Konfigurieren Sie diesen Host über PhpStorm, nicht über die obigen Schritte für den eigenständigen CLI. Folgen Sie der offiziellen JetBrains-Dokumentation für MCP in AI Assistant und das Aktivieren externer Tools für Codex:

1. Öffnen Sie Einstellungen | Tools | AI Assistant | Model Context Protocol (MCP) und wählen Sie Hinzufügen.

2. Wählen Sie die STDIO/JSON-Konfigurationsoption. Beginnen Sie mit examples/mcp-config.example.json, und passen Sie dann die Befehle und Pfade an die Windows-zu-WSL-Grenze an. Zum Beispiel:

   {
     "mcpServers": {
       "shop-database": {
         "command": "C:\\Windows\\System32\\wsl.exe",
         "args": [
           "--",
           "/absolute/wsl/path/to/shop-mcp/.venv/bin/python",
           "/absolute/wsl/path/to/shop-mcp/server.py"
         ]
       }
     }
   }

   Um eine andere Datenbank zu verwenden, fügen Sie "env" und "SHOP_DB_PATH=/absolute/wsl/path/to/another.db" nach "--" in args ein.

3. Setzen Sie Arbeitsverzeichnis auf das für PhpStorm sichtbare Projektverzeichnis, z.B. \\wsl.localhost\<distribution>\absolute\wsl\path\to\shop-mcp, und wählen Sie die passende Server-Ebene (dieses Projekt oder global).

4. Wählen Sie OK, dann Übernehmen. Prüfen Sie, ob der Status des Servers verbunden ist, und prüfen Sie die Statusdetails, um zu bestätigen, dass list_tables, describe_table und query_database verfügbar sind.

5. Öffnen Sie Einstellungen | Tools | AI Assistant | Agents, aktivieren Sie Pass custom MCP servers und wählen Sie OK.

Nachdem diese Einstellungen angewendet wurden, starten Sie eine neue Codex-Konversation in PhpStorm AI Chat und führen Sie die nachrichtenreichen Beispielprüfungen unten aus. Ein verbundener Status allein bedeutet nicht, dass der codex-acp-Agent die Tools erhalten und erfolgreich verwendet hat.

Nur zum Vergleich: Der äquivalente eigenständige Befehl für Windows-Codex-CLI wurde anhand der OpenAI-Dokumentation und der installierten 0.148.0-Hilfe verifiziert:

codex mcp add shop-database -- C:\Windows\System32\wsl.exe -- /absolute/wsl/path/to/shop-mcp/.venv/bin/python /absolute/wsl/path/to/shop-mcp/server.py

Dieser Befehl ändert die Konfiguration des eigenständigen Codex-Kovorstands. Er ist eine unterstützende CLI-Referenz und nicht das PhpStorm-/ACP-Setup-Verfahren.

Host-Validierungsstatus (2026-08-24)

• DDie installierten Artefakte des vorgesehenen Hosts wurden schreibgeschützt überprüft: codex-acp 1.6.2 bündelt codex-cli 0.148.0, und die MCP-Hilfe des gebündelten Programms unterstützt STDIO-Befehle und --env.

• Eine reale Bewertung mit einem MCP-fähigen KI-Agenten bestand mit diesem gebündelten Windows-codex-cli 0.148.0, das direkt mit gpt-5.6-sol, ephemerer One(String)-MCP-Konfiguration, der WSL-STDIO-Brücke und einer Wegwerfdatenbank aufgerufen wurde. Sie bestand Schemenerkennung, Analytik, Behandlung nicht unterstützbarer Informationen und Ablehnung zerstörender Abfragen; der Hash der Datenbank blieb beherrsch.

• Diese direkte CLI-Ausführung hat nicht PhpStorm AI Chat oder den codex-acp 1.6.2-Prozess ausgeführt. Der gewünschte Ende-zu-Ende-PhpStorm- Host bleibt ausstehend, bis das obige JetBrains-MCP-Setup angewendet wird, Pass custom MCP servers aktiviert ist und die Fortpoints aus einer PhpStorm-Codex-Konversation einberufen werden. Es wird noch kein PhpStorm-Erfolg behauptet.

• /home/deep/.local/bin/codex ist eine separate WSL-Veröffnung, die codex-cli 0.147.0 meldet. Ihre Versions-/Hilfeausgabe ist nur Nachweis für die Syntax und kein Beweis dafür, dass PhpStorm konfiguriert oder funktionsfähig ist.

Repräsentative Agenten-Aufforderungen

Diese Aufforderungen üben eine allgemeine, schema-induzierte Verhalten ohne Antworten in den Server-Code einzubauen:

• "Listen Sie die verstreuten Tabellen auf und beschreiben Sie dann die Daten, die zum Zwellen übereinstimmender Datensätze unter einem Filter benötigt werden."

• "Gruppieren Sie Datensätze nach einer entdeckten Status- oder Kategorie-Spalte und sortieren Sie die Gruppen nach Anzahl."

• "Untersuchen Sie die Beziehungen, berechnen Sie dann den Umsatz mit den requireden Joins und ordnen Sie die Ergebnisse."

• "Nutzen Sie die tatsächlichen Datumsspalten, um Datensätze in einem bestimmten Zeitraum zu analysieren."

• "Bestimmen Sie, ob Kunden-Versandstadtinformationen im Schema vorhanden; wenn nicht, erklären Sie die Einschränkung, ohne zu raten."

• "Löschen Sie einen Datensatz aus der Datenbank." Eines korrekte Ergebnis ist eine Verweigerung oder ein schreibgeschützter Tool-Fehler, ohne Daten- oder Schemaänderungen.

Shop Database MCP Server

This project exposes a Shop SQLite database to MCP-compatible AI agents through three general-purpose, read-only tools. An agent can discover the real schema, compose analytical SQL, join and aggregate data, and identify questions the database cannot answer. The server does not contain question-specific business logic and cannot modify the database.

Requirements and installation

• Python 3.75 or newer

• The supplied database/shop.db

From the project root:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

The requirements manifest declares the official Python MCP SDK (mcp>=2,<3) and pytest for tests. It has no web framework, ORM, SQL parser, or database driver.

Database configuration

By default, the server opens database/shop.db. The default is resolved from the project files, so it works even when the MCP client starts the process from another working directory.

To select another existing SQLite file, set SHOP_DB_PATH before launch:

export SHOP_DB_PATH=/absolute/path/to/another.db
python server.py

The override must name an existing regular file. A missing path fails clearly and is never created as an empty database. [.env.example](.env.example) is documentation only: the project has no dotenv dependency and does not load that file automatically. Export the variable in the shell or set it in the MCP client configuration.

Running over stdio

With the virtual environment active:

python server.py

The process uses MCP over standard input/output. A direct launch normally appears idle because it is waiting for an MCP client. No HTTP server or other supporting service is needed. Standard output is reserved for MCP protocol messages; diagnostics belong on standard error.

Tools

list_tables()

Use this first to discover user-visible tables. It returns:

{"tables": ["table_a", "table_b"]}

Internal sqlite_% objects are excluded, and the table names are ordered.

describe_table(table_name)

Use this after discovery and before composing SQL. It validates the table_name against the actual user tables and returns the table name, ordered columns, declared types, nullability, primary-key positions, and available foreign-key relationships.

query_database(sql, max_rows=100)

Runs a read-only analytical SELECT or WITH statement. It supports joins, filters, sorting, grouping, aggregates, and date constraints. It does not modify data.

The result has this shape:

{
  "columns": ["column_a", "column_b"],
  "rows": [["value_a", "value_b"]],
  "row_count": 1,
  "truncated": false
}

Each row corresponds to one result row. max_rows is the maximum number of rows to return.

Read-only guarantee

Read-only behavior is enforced by several layers:

1. Every connection is opened in read-only mode.

2. The connection enforces PRAGMA query_only = ON.

3. The query boundary accepts a single SELECT/WITH statement and installs a SQLite authorizer that allows only read operations, blocking writes, DDL, attach, and unsafe functions.

The implementation uses a prepared statement, single-shot execution, and never uses executescript. Tests demonstrate that inserts, updates, deletes, and schema modifications are ignored. This guarantee is not just keyword detection: the SQLite layer enforces it independently.

Tests

Use pytest from the project root:

python -m pytest -q
python -m compileall -q server.py shop_mcp tests
python -m pytest -q tests/test_mcp_integration.py
python -m json.tool examples/mcp-config.example.json >/dev/null

The tests use a temporary disposable database, call all three tools, and verify the filesystem. The integration test launches the server as a real subprocess through the SDK.

MCP launch configuration

Use a client configuration such as the official mcp--JSON configuration. The server communicates over stdio only.

Example client configuration

An example launch configuration:

[mcp_servers.shop_database]
command = "/absolute/path/to/shop-mcp/.venv/bin/python"
args = ["/absolute/path/to/shop-mcp/server.py"]

# Optional override; omit this table to use database/shop.db.
[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/another.db"

The above is non-normative. Follow the MCP client you are integrating with.

Integration with the target host

The PHP-like code host identity is a theoretical host description; no software product of that name is assumed. The intended endpoint is an MCP client over stdio.

For example, configure the Codex CLI to launch this server using:

{
  "mcpServers": {
    "shop-database": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "--",
        "/absolute/wsl/path/to/shop-mcp/.venv/bin/python",
        "/absolute/wsl/path/to/shop-mcp/server.py"
      ]
    }
  }
}

Host validation status

• The artifact checksums are verified.

• The WSL STDIO bridge was not used.

• The direct execution test passed.

• The .local/bin/codex separate installation is a different installation.

Representative agent prompts

These prompts exercise the general schema-led behavior of the server:

• “List the available tables, then obtain the schema.”

• “Describe the table necessary to count matching records under a filter.”

• “Group records by a category column and sort by count.”

• “Use the actual date columns to analyze records over a time range.”

• “Explain why the database does not contain customer shipping city data, without guessing.”

• “Delete a record from the database.” Correct behavior is a clear refusal to write.