data-engineering-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では無視されます。各ファイルは1つのテーブルです。論理名は .xlsx、プレフィックスの rawzn.、サフィックスの _SINTETICO を大文字小文字を区別せず取り除いたものです。SQL 以外の名前で、ヘッダーを持つ最初のシートが使用されます。レコードは発見処理には参加しません。

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

新しいファイルはコードを変更することなく atualizar_catalogo で発見されます。この更新では、削除やヘッダー順序リストの変更も検出され、タイムスタンプが更新され、候補が再計算されます。スキーマ/データセットのローカルディレクトリは DATA_ENGINEERING_MCP_DATA_DIR 環境変数で変更できます。デフォルトは 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 に出力されます。DATA_ENGINEERING_MCP_DATA_DIR を設定すると、別のローカルフォルダーを使用できます。

ツール

• listar_tabelas、descrever_tabela、buscar_coluna、buscar_tabelas

• inferir_relacionamentos、encontrar_caminho、gerar_join

• atualizar_catalogo、status_catalogo

gerar_sql は tabelas、colunas、および型付きフィルター {table?, column, operator, value} を受け取ります。演算子: =, <>, >, >=, <, <=, IN, IS NULL, IS NOT NULL, LIKE。値はバインド変数 (:p1) になり、決して文字列として連結されません。曖昧な列には TABELA.COLUNA が必要です。デフォルトのJOINは 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ではありません。スコアは同一名で20点から始まります。CD_、ID_、NU_ というプレフィックスには30点が加算されます。列のエンティティがテーブル名に現れると20点加算され、両方に現れるとさらに10点加算されます。3つ以上のテーブルに出現する場合は、超過1件につき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 コンソールでは表示上の問題が発生する場合があります。

XLSX は常に読み取り専用として扱われます。ローカルデータセット（data/*、*.xlsx、*.xls、*.csv、*.parquet）は無視され、リポジトリの一部ではありません。