data-engineering-mcp

Servidor MCP 通用、本地、离线的 MCP 服务器：将 XLSX 文件的表头转换为可查询的目录，推断 候选关系，并仅生成 Oracle SQL SELECT/WITH。它不连接数据库、不执行 SQL，也不存在任何 Power BI 集成或依赖。

要求与安装

• Python 3.12

• MCP Python SDK 2.x（MCPServer，已安装版本当前的公共 API）

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

运行时依赖：mcp、pandas、openpyxl 和 pydantic；测试则使用 pytest。目录通过 openpyxl 直接以只读模式打开工作簿，并且只准备读取所需的第一行。

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

数据与架构

这些数据集由用户提供存放于本地，不属于仓库。将 .xlsx 文件放入 data/ 中；它们继续供 MCP 使用，但会被 Git 忽略。每个文件都是一张表。逻辑表名会去除 .xlsx、前缀 rawzn. 以及后缀 _AI，且比较时不区分大小写。第一个不是 SQL 且带有表头的工作表度被采用；数据行不参与发现过程。

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

新文件由 atualizar_catalogo 自动发现，无需不存在代码层面的改动。该更新还会检测已删除的内容、检测有序表头列表中的变化，更新 timestamp，并重新计算候选。模式数据集目录可通过 TABELA.COLUNA 使用数据工程 MCP 的数据目录变量；默认目录为 data/。

执行与测试

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

默认传输通道为 stdio。日志写入 stderr，以免破坏协议。如要使用别的本地目录，请设置 SCALE ENGINEERING_MCP_DATA_DIR。

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 接受表名、列以及类型构建的过滤条件 {表?, 列, 值?}”。操作符：=、<>、>、>=、<、<=、IN、IS NULL、IS NOT NULL、LIKE。数值使用绑定参数（:p1），绝不采用拼接字符串。模糊列必须写成 Table.COLUMN. 默认联查类型为 LEFT JOIN，这是为了保留第一个的行而采取的保险选择；该工具默认提供 MEDIUM候选，并默认拒绝LOW` 候选。

参数示例：

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

关联置信度

所有结果都是名称性的候选，并非已确认的 PK/FK。评分从同名开始为0分；对 CD_、ID_ 或 NU_ 前缀加30分；当列中实体出现在表名中时再累积20分，若两侧同时出现再额外10分。出现在两个以上表中时，多出的每次出现都会减少5分（最多25分）；泛型字段或没有的前缀的字段考虑减少25分。HIGH >= 75、MEDIUM >= 50、LOW < 50。该版本之下不读取数值、也不计算基数，也没有显式的 PK/FK 元数据。

安全与限制

仅生成有结构的 Oracle SQL SELECT/WITH。不会有 DDL/DML 的使用，也看不到过滤参数中的任意 SQL、凭证、网络、数据库或外部 API 的表面。

已知限制：

• 关系是通过名称推断的，可能产生误报或语义误报；

• 当前版本没有显式的 PK/FK 元数据；

• 通用字段或共享字段可能产生不恰当的路径；

• LOW 候选不应自动投入使用；

• MEDIUM 候选只是推断，而非确认；

• explicar_sql 仅提供保守的语法检查，不对 Oracle 中的查询做语义验证；

• 某些带语气符号的日志在配置为 CP1252(代码页) 的 Windows 控制台可能显示效果不正确。

XLXS 文件引用始终以只读方式处理。本地的数据集（data/*、*.xlsx、*.xls、*.csv、*.parquet）不纳入版本控制，它们不属于该仓库。