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에서는 무시됩니다. 각 파일은 하나의 테이블입니다. 논리 이름은 .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, gerar_select, explicar_sql

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점을 더합니다. 둘 이상의 테이블에 나타나는 경우 초과 횟수당 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)은 무시되며 저장소에 포함되지 않습니다.