data-engineering-mcp

Servidor MCP genérico, local y offline que transforma los encabezados de archivos XLSX en un catálogo consultable, infiere relaciones candidatas y genera únicamente SQL Oracle SELECT/WITH. No accede a bases de datos, no ejecuta SQL y no tiene integración ni dependencia de Power BI.

Requisitos e instalación

• Python 3.12

• MCP Python SDK 2.x (MCPServer, la API pública actual de la versión instalada)

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

Dependencias de runtime: mcp, pandas, openpyxl y pydantic; las pruebas usan pytest. El catálogo usa openpyxl directamente para abrir los workbooks en modo de solo lectura y leer únicamente la primera línea necesaria.

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

Datos y arquitectura

Los datasets son proporcionados localmente por el usuario y no forman parte del repositorio. Coloque archivos .xlsx en data/; permanecen disponibles para el MCP, pero Git los ignora. Cada archivo es una tabla. El nombre lógico elimina .xlsx, el prefijo rawzn. y el sufijo _SINTETICO, con una comparación que no distingue mayúsculas de minúsculas. Se utiliza la primera pestaña no llamada SQL que tenga encabezados; los registros no participan en el descubrimiento.

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

Los archivos nuevos se descubren mediante atualizar_catalogo, sin cambios de código. La actualización también detecta remociones y cambios en la lista ordenada de encabezados, actualiza el timestamp y recalcula los candidatos. El directorio local de schemas/datasets es configurable mediante la variable DATA_ENGINEERING_MCP_DATA_DIR; el valor por defecto es data/.

Ejecución y pruebas

.\.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

El transporte por defecto es stdio. Los logs van a stderr para no corromper el protocolo. Defina DATA_ENGINEERING_MCP_DATA_DIR para usar otra carpeta local.

Tools

• 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 recibe tabelas, colunas y filtros tipados {table?, column, operator, value}. Operadores: =, <>, >, >=, <, <=, IN, IS NULL, IS NOT NULL, LIKE. Los valores se convierten en bind variables (:p1), nunca en texto concatenado. Las columnas ambiguas exigen TABELA.COLUNA. El JOIN por defecto es LEFT JOIN, una elección conservadora para preservar las filas de la primera tabla; la herramienta informa candidatos MEDIUM y rechaza los LOW por defecto.

Ejemplo de argumentos:

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

Confianza de las relaciones

Todo resultado es un candidato nominal, nunca una PK/FK confirmada. La puntuación comienza en 20 por nombre idéntico; suma 30 para prefijos CD_, ID_ o NU_; suma 20 cuando la entidad de la columna aparece en el nombre de una tabla y 10 más si está en ambos. La ocurrencia en más de dos tablas reduce 5 por cada ocurrencia excedente (máximo 25); un campo genérico o sin prefijo identificador reduce 25. HIGH >= 75, MEDIUM >= 50, LOW < 50. No se leen valores ni se calcula cardinalidad, y esta versión no cuenta con metadatos explícitos de PK/FK.

Seguridad y limitaciones

Solo se genera SQL Oracle SELECT/WITH estructurado. No existe una superficie para DDL/DML, SQL arbitrario en filtros, credenciales, red, base de datos o API externas.

Limitaciones conocidas:

• las relaciones se infieren de manera nominal y pueden producir falsos positivos o negativos semánticos;

• esta versión no cuenta con metadatos explícitos de PK/FK;

• los campos genéricos o compartidos pueden generar caminos inadecuados;

• los candidatos LOW no deben utilizarse automáticamente;

• los candidatos MEDIUM son inferencias, no confirmaciones;

• explicar_sql realiza un análisis sintáctico conservador y no valida semánticamente la consulta en Oracle;

• algunos logs con acentos pueden presentar una visualización estética incorrecta en la consola de Windows configurada como CP1252.

Los XLSX siempre se tratan como de solo lectura. Los datasets locales (data/*, *.xlsx, *.xls, *.csv y *.parquet) se ignoran y no forman parte del repositorio.