MCP Data Analysis Agent

Lokal zuerst, kontrollierte Analytik für MCP-Clients über SQLite und PostgreSQL.

mcp-data-analysis-agent gibt einem MCP-Client eine kleine, prüfbare Datenzugriffsschicht statt direktem Datenbankzugriff. Es validiert SQL vor der Ausführung, verwendet schreibgeschützte Verbindungen, begrenzt Ergebnisse und Ausführungszeit, schreibt belegbasierte Beobachtbarkeitsdatensätze und hält Anmeldedaten auf dem Rechner des Betreibers.

Warum es existiert

MCP-Clients können über Daten nachdenken, sollten aber keine uneingeschränkten Datenbankanmeldedaten erhalten oder stillschweigend beliebige Anweisungen ausführen. Dieses Projekt bietet einen lokalen Kontrollpunkt für diese Grenze:

• Datenbankpfade, URLs, Passwörter und Token in einer ignorierten .env-Datei aufbewahren.

• Nur eine einzelne parametrisierte SELECT- oder WITH-Anweisung zulassen.

• Mutationen, DDL, Befehle, Anhänge, Mehrfachanweisungen, unsichere Funktionen, eingeschränkte Felder und unsichere Artefaktpfade blockieren.

• Zusätzlich zur Anwendungspolicy schreibgeschützten Datenbankzugriff auf Datenbankebene verlangen.

• Normalisiertes SQL, Zeitmessung, Aufgabenverknüpfung, Belege, Hashes und Ereigniszeitlinien für spätere Prüfung aufbewahren.

Der Server verwendet nur stdio. Er hostet keine öffentliche API, lädt keine Quelldaten hoch, speichert keine entfernten Anmeldedaten und erstellt keine Produktionsdatenbankbenutzer.

Related MCP server: sql-explorer-mcp

Funktionen

• SQLite- und PostgreSQL-Zugriff über SQLAlchemy Core mit SQLGlot-Policy-Validierung.

• Quellen-, Schema-, Beziehungs-, Profil-, Qualitäts-/Frische- und Schema-Drift-Erkennung.

• Validierung, Erklärungspläne, begrenzte Ausführung, nicht-negative Offset-Paginierung, Abbruch, Zeitüberschreitungen und Nebenläufigkeitsgrenzen.

• Klassifizierungen für öffentliche, interne, vertrauliche und eingeschränkte Felder/Quellen.

• Genehmigte semantische Metriken, Git-native Rezepte, Periodenvergleich, Änderungserkennung und Diagrammempfehlungen.

• Offline-HTML-Dashboards, CSV, Parquet, Typst-PDF, Belegmetadaten und sichere atomare Ausgabeverzeichnisse.

• ClineFlow-Kontextladung, Aufgabenjournale, unveränderliche Abfrage-/Ausführungsdatensätze, Ereigniszeitlinien und Integritätsprüfung.

• Deterministische Retail-, SaaS- und Support-Fixtures, einschließlich lokaler SQLite-zu-PostgreSQL-Paritäts-Fixtures.

Voraussetzungen

• Python 3.11 oder neuer und uv.

• Typst für die unterstützte Berichts-Rendering-Installation.

• PostgreSQL-Befehlszeilenwerkzeuge einschließlich createdb für lokale Paritäts-Fixtures.

• Ein gesundes ClineFlow/OKF-Bundle im Zielprojekt.

Führen Sie mcp-data-cli preflight aus, um erforderliche lokale Werkzeuge über einen verfügbaren Paketmanager im Benutzerbereich zu installieren oder zu melden. Es kontaktiert niemals eine konfigurierte Quelle. mcp-data-cli doctor validiert die lokale Installation; eine nicht konfigurierte Quelle wird als configuration_pending gemeldet, nicht als Installationsfehler.

Installation

Dieses Repository in das aktuelle Projekt installieren

Wenn ein Agent oder Betreiber gebeten wird, dieses GitHub-Repository in ein Projekt zu installieren, verwenden Sie den Repository-Installer – nicht einen bloßen uv tool install-Befehl:

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

Der Installer installiert das Befehlszeilenwerkzeug und initialisiert das Verzeichnis, aus dem es ausgeführt wurde. Er erstellt den ignorierten deterministischen Retail-Playground, schreibt den einen privaten MCP_DATA_SOURCE_URL-Wert in .env, schreibt die Quellenpolicy und führt den MCP-Server in jeden erkannten unterstützten Client zusammen. Er kopiert das Paket nicht in das Projekt und legt niemals eine Datenbank-URL oder Anmeldedaten in eine Client-Konfiguration. Client-Vertrauens-/Aktivierungs- und Neustartaufforderungen bleiben unter der Kontrolle jeder Client-Anwendung.

uv tool install installiert absichtlich ausführbare Dateien auf Benutzerebene und führt keine projektverändernden Post-Installations-Hooks aus. Verwenden Sie es nur, wenn Sie die ausführbare Datei separat installieren möchten, und führen Sie dann mcp-data-cli init selbst aus.

PyPI-kompatibler Workflow

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

Um die aktuelle Repository-Version vor einer Paketveröffentlichung zu installieren, ersetzen Sie den Installationsbefehl durch:

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

Bei der ersten Serververwendung in einem unterstützten MCP-Client erstellt und öffnet der Agent einen deterministischen Entwicklungs-Only-Retail-SQLite-Playground unter .mcp-data/playground.sqlite. Das gemeinsame MCP-welcome-Werkzeug erklärt, wie man ihn erkundet und wie man zu einer echten Quelle wechselt. init materialisiert denselben Playground in die explizite Projektpolicy und private .env und führt dann nach einer Bestätigung sichere MCP-Client-Einträge zusammen. Der explizite Repository-Installer verwendet init --yes, da die Ausführung dieses Installers die einzige Autorisierung für diese begrenzten Schreibvorgänge ist.

Verwenden Sie setup --all, um nur die Client-Konfiguration in der Vorschau anzuzeigen, oder setup --all --apply, um nur den mcp-data-analysis-stdio-Eintrag nach einer expliziten Bestätigung zusammenzuführen. Es erhält nicht zusammenhängende Server und Einstellungen. Verwenden Sie setup --status, um die Erkennung und den aktuellen Konfigurationszustand zu prüfen.

Das Setup konfiguriert nur MCP-Definitionen. Es kann die Vertrauens-/Aktivierungsaufforderung eines Clients nicht umgehen oder eine IDE starten/neu starten. Details zur VS-Code-Konfiguration sind in VS Code und GitHub Copilot in VS Code dokumentiert; Continue dokumentiert Projekt-MCP-Fragmente in seinem MCP-Leitfaden.

Prüfsummen-verifizierter Release-Bootstrap

Für ein versioniertes Wheel und seine veröffentlichte SHA-256-Prüfsumme:

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

Der Bootstrap erfordert curl und uv, verifiziert das Artefakt mit sha256sum oder shasum und installiert nur, wenn die Prüfsumme übereinstimmt. Er initialisiert dann das aktuelle Projekt genau wie der Repository-Installer. Er verwendet kein sudo und kontaktiert keine Produktionsdatenbank; er erstellt nur lokale deterministische Demo-Daten.

Eine aktive Quelle konfigurieren

Die Standardinstallation verwendet genau eine aktive Quelle namens data und genau einen privaten Wert in .env: MCP_DATA_SOURCE_URL. Es ist keine Paketkonstante oder ein Testwert – es ist der eine Wert, den der Betreiber ändert, um auf seine eigene schreibgeschützte Datenbank zu verweisen. Halten Sie .env privat; es wird von Git ignoriert.

Bei der ersten Verwendung zeigt data automatisch auf den generierten Retail-Playground. Führen Sie mcp-data-cli init aus, wenn Sie bereit sind, diese Wahl in der Projekt-.env zu materialisieren; es schreibt:

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

Der Playground besteht aus synthetischen Entwicklungs-Only-Daten. Er ermöglicht einer neuen Installation, Schemaerkennung, kontrollierte Abfragen, Belege und Berichte sofort auszuführen; es sind niemals Produktionsdaten und werden von einem späteren init-Lauf nie überschrieben. Alle unterstützten Clients erhalten dieselben stdio-Server-Begrüßungsanweisungen und das welcome-MCP-Werkzeug.

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Für SQLite machen Sie dieselbe einzelne Variable zu einem absoluten Dateipfad oder einer SQLite-URL. Für PostgreSQL verwenden Sie eine postgres://- oder postgresql://-URL. Keine manuelle Dialekteinstellung ist erforderlich:

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Verwenden Sie data als Quellenargument in CLI-Aufrufen, zum Beispiel mcp-data-cli schema data. Der Agent lehnt nicht unterstützte URL-Schemata, relative SQLite-Pfade und einen veralteten deklarierten Dialekt ab, der mit der URL in Konflikt steht. Etablierte Multi-Quellen-Policies bleiben lesbar, aber init weigert sich bewusst, sie neu zu schreiben; migrieren Sie manuell oder starten Sie ein neues vereinfachtes Projekt.

Für PostgreSQL verwenden Sie ein dediziertes Konto mit geringsten Rechten und ohne Schreib- oder DDL-Berechtigungen. Der Agent aktiviert außerdem eine schreibgeschützte Sitzung und wendet den konfigurierten Schema-Suchpfad an, aber die Zugriffskontrolle auf Datenbankebene bleibt obligatorisch.

Typischer Workflow

Vor der Ausführung validieren, dann den Plan prüfen und eine begrenzte Abfrage ausführen:

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

Erstellen Sie eine explizite Aufgabe, wenn mehrere Operationen zu einer Analyse gehören:

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

Generieren Sie Berichte in einem neuen, vom Aufrufer gewählten Verzeichnis. Vorhandene Verzeichnisse und Symlink-Traversierung werden abgelehnt.

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

Jeder Bericht enthält offline HTML, CSV, optionale Parquet/PDF-Artefakte, Belegmetadaten, Pfade und Inhalts-Hashes. Generierte Artefakte, Quellen und Anmeldedaten dürfen nicht eingecheckt werden.

Entwicklungs-Fixtures und PostgreSQL-Parität

init erstellt nur den oben beschriebenen kleinen Retail-Playground. Mitwirkende können zusätzliche deterministische synthetische Fixtures explizit generieren:

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres verwendet lokales createdb, lehnt einen vorhandenen Datenbanknamen ab, erstellt SQLite-Daten nur in einem temporären Verzeichnis und kopiert sie dann in die neue PostgreSQL-Datenbank unter dem mcp_parity-Schema. Es erfordert keine manuell bereitgestellte Wegwerf-PostgreSQL-URL.

seed-postgres ist für eine bereits bereitgestellte isolierte Testdatenbank. Es liest die private Test-URL aus der Umgebung und ersetzt nur deren reserviertes mcp_seed_retail-, mcp_seed_saas- oder mcp_seed_support-Schema. Es berührt niemals öffentliche/Anwendungsschemata.

Führen Sie die vollständige lokale Qualitätssuite mit einer isolierten PostgreSQL-Instanz aus, wenn Sie Adapterverhalten entwickeln. CI umfasst Linting, Typprüfung, Tests, Abdeckungsgrenzen, echtes Typst-Rendering, SQLite/PostgreSQL-Parität, Secret-Scanning, Abhängigkeitsprüfung, SBOM-Erzeugung und vertrauenswürdige Veröffentlichungsautomatisierung.

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

Sicherheitskritische Konfigurations-, Kontext-, Ledger- und SQL-Policy-Module erfordern 100 % Zeilen- und Zweigabdeckung. Gesamtgrenzen erfordern mindestens 90 % Zeilenabdeckung und 85 % Zweigabdeckung.

Sicherheits- und Betriebsvertrag

• Abfragen müssen parametrisiert sein und werden vor Datenbankverbindung/-ausführung validiert.

• Ergebnisgrenzen und Offsets werden durch die Projektpolicy geregelt; Aufrufer-SQL kann sie nicht umgehen.

• Eingeschränkte Spalten werden vor der Ausführung abgelehnt und geheimnisähnliche Parameter werden in Beobachtbarkeitsdatensätzen redigiert.

• Aufgabenjournale, Abfragebelege, Ausführungen und Ereignisse werden unter knowledge/ und observability/ gespeichert; Datenbank-URLs, rohe Geheimnisse, Quelldatenbanken, Ergebnis-Caches und Berichtsbinärdateien sind ausgeschlossen.

• Lokale synthetische Datensätze sind nur Entwicklungsinfrastruktur und keine Produktions-Onboarding.

Siehe Betriebsanleitung, die Sicherheitsrichtlinie und die MIT-Lizenz für den vollständigen Betriebs- und Offenlegungsvertrag.

Beiträge und Veröffentlichungen

Verwenden Sie fokussierte Commits und bewahren Sie die annotierten checkpoint-*-Tags: Sie sind explizite Rollback-Punkte für Liefermeilensteine. Aktualisieren Sie das aktive ClineFlow-Engineering-Journal und das Wissensprotokoll mit wesentlichen Änderungen, führen Sie die OKF-Validierung aus und committen Sie dann Implementierung und Wissensnachweise zusammen.

GitHub Actions erstellt und verifiziert Distributionen bei der Veröffentlichung. Veröffentlichungsendpunkte und Veröffentlichungsanmeldedaten sind Repository-Konfiguration; sie werden niemals in dieser Codebasis gespeichert.