data-engineering-mcp

Generischer, lokaler und offline arbeitender MCP-Server, der Kopfzeilen von XLSX-Dateien in einen abfragbaren Katalog überführt, Kandidatenbeziehungen ableitet und ausschließlich Oracle-SQL SELECT/WITH generiert. Er greift nicht auf Datenbanken zu, führt kein SQL aus und besitzt weder eine Integration mit Power BI noch eine Abhängigkeit davon.

Anforderungen und Installation

• Python 3.12

• MCP Python SDK 2.x (MCPServer, das aktuelle öffentliche API der installierten Version)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Laufzeit-Abhängigkeiten: mcp, pandas, openpyxl und pydantic; für Tests wird pytest verwendet. Der Katalog nutzt openpyxl direkt, um die Arbeitsmappen im schreibgeschützten Modus zu öffnen und nur die benötigte erste Zeile zu lesen.

Related MCP server: io.github.Optisol-Business/db-metadata-extractor-mcp

Daten und Architektur

Die Datensätze werden lokal vom Benutzer bereitgestellt und sind nicht Teil des Repositorys. Legen Sie .xlsx-Dateien in data/ ab; sie bleiben für den MCP verfügbar, werden aber von Git ignoriert. Jede Datei ist eine Tabelle. Der logische Name entfernt .xlsx, das Präfix rawzn. und das Suffix _SINTETICO, ohne Beachtung der Groß-/Kleinschreibung. Das erste Arbeitsblatt, das nicht SQL heißt und Kopfzeilen enthält, wird verwendet; Datensätze nehmen nicht an der Erkennung teil.

data/*.xlsx -> Catalog -> RelationshipEngine -> SQLGenerator
                                      \-> explicação conservadora de SQL

Neue Dateien werden durch atualizar_catalogo erkannt, ohne dass Code geändert werden muss. Die Aktualisierung erkennt auch Entfernungen und Änderungen in der geordneten Liste der Kopfzeilen, aktualisiert den Zeitstempel und berechnet Kandidaten neu. Der lokale Ordner für Schemas/Datasets ist über die Variable DATA_ENGINEERING_MCP_DATA_DIR konfigurierbar; die Voreinstellung ist data/.

Ausführung und Tests

.\.venv\Scripts\data-engineering-mcp.exe
# ou
.\.venv\Scripts\python.exe -m data_engineering_mcp.server

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe scripts\smoke_test.py

Der Standardtransport ist stdio. Logs gehen nach stderr, um das Protokoll nicht zu korrumpieren. Setzen Sie DATA_ENGINEERING_MCP_DATA_DIR, um einen anderen lokalen Ordner zu verwenden.

Werkzeuge

• listar_tabelas, descrever_tabela, buscar_coluna, buscar_tabelas

• inferir_relacionamentos, encontrar_caminho, gerar_join

• atualizar_catalogo, status_catalogo

• gerar_sql, gerar_select, explicar_sql

gerar_sql erhält die Parameter tabelas, colunas und typisierte Filter {table?, column, operator, value}. Operatoren: =, <>, >, >=, <, <=, IN, IS NULL, IS NOT NULL, LIKE. Werte werden zu Bind-Variablen (:p1), niemals zu verkettetem Text. Mehrdeutige Spalten erfordern TABELA.COLUNA. Der Standard-JOIN ist LEFT JOIN – eine konservative Wahl, um die Zeilen der ersten Tabelle zu erhalten; das Werkzeug meldet Kandidaten mit MEDIUM und weist LOW standardmäßig zurück.

Beispiel für Argumente:

{
  "tabelas": ["RAW_HAP_TB_USUARIO", "RAW_HAP_TB_PESSOA"],
  "colunas": ["CD_USUARIO", "NM_PESSOA_RAZAO_SOCIAL"],
  "filtros": [{"column": "FL_STATUS_USUARIO", "operator": "=", "value": 2}]
}

Konfidenz der Beziehungen

Jedes Ergebnis ist ein nomineller Kandidat, niemals eine bestätigte PK/FK. Der Score beginnt bei 20 für identische Namen; addiert 30 für Präfixe CD_, ID_ oder NU_; addiert 20, wenn die Entität der Spalte im Namen einer Tabelle vorkommt, und weitere 10, wenn sie in beiden auftritt. Das Vorkommen in mehr als zwei Tabellen reduziert den Score um 5 für jedes zusätzliche Vorkommen (höchstens 25); ein generisches Feld oder fein Feld ohne Identifikator-Präfix reduziert um 25. HIGH >= 75, MEDIUM >= 50, LOW < 50. Es werden keine Werte gelesen und keine Kardinalitäten berechnet; diese Version besitzt keine expliziten PK/FK-Metadaten.

Sicherheit und Einschränkungen

Es wird ausschließlich strukturiertes Oracle-SQL SELECT/WITH generiert. Es gibt keine Oberfläche für DDL/DML, beliebiges SQL in Filtern, Zugangsdaten, Netzwerk, Datenbank oder externe APIs.

Bekannte Einschränkungen:

• Beziehungen werden nominell abgeleitet und können semantisch falsch positive oder falsch negative Ergebnisse erzeugen;

• diese Version besitzt keine expliziten PK/FK-Metadaten;

• generische oder gemeinsam genutzte Felder können ungeeignete Pfade erzeugen;

• Kandidaten mit LOW sollten nicht automatisch verwendet werden;

• Kandidaten mit MEDIUM sind Ableitungen, keine Bestätigungen;

• explicar_sql führt eine konservative syntaktische Analyse durch und validiert die Abfrage nicht semantische in Oracle;

• manche Logs mit Akzenten können auf einer als CP1252 konfigurierten Windows-Konsole kosmetisch falsch dargestellt werden.

Die XLSX-Dateien werden immer schreibgeschützt behandelt. Lokale Datasets (data/*, *.xlsx, *.xls, *.csv und *.parquet) werden ignoriert und sind nicht Teil des Repositorys.