mcp-win-stdio-excel-db 0.2.5__py3-none-any.whl

mcp_win_stdio/excel_db/__init__.py

@@ -0,0 +1,6 @@
+"""
+Excel & DB Power Engine MCP Server for mcp-win-stdio.
+High-Speed Streaming, Cross-Source Joins, and Diff Auditing.
+"""
+
+__version__ = "0.2.5"

mcp_win_stdio/excel_db/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+from mcp_win_stdio.excel_db.cli import main
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio/excel_db/auditor.py

@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+"""
+Automated Data Auditor and Reconciliation Engine for comparing Database tables
+and Excel spreadsheets with tolerance, column mappings, and multi-tab diff reports.
+"""
+
+import math
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+from openpyxl import Workbook
+from openpyxl.styles import Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+from sqlalchemy import create_engine, text
+
+from mcp_win_stdio.excel_db.stream import resolve_sqlalchemy_url
+
+
+def _clean_val(v: Any) -> Any:
+    """Format primitives safely for JSON serialization and comparison."""
+    if pd.isna(v):
+        return None
+    elif hasattr(v, "isoformat"):
+        return v.isoformat()
+    elif isinstance(v, (float, int)) and (math.isnan(v) or math.isinf(v)):
+        return None
+    return v
+
+
+def _load_dataset(source: Union[str, Dict[str, Any]], db_resolver_func=None) -> pd.DataFrame:
+    """
+    Load a dataset from either a file path (Excel/CSV) or a configuration dict (DB/Excel).
+    """
+    if isinstance(source, str):
+        path = Path(source).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"Source file not found: {path}")
+        if path.suffix.lower() == ".csv":
+            df = pd.read_csv(path)
+        else:
+            df = pd.read_excel(path)
+
+        if len(df) > 0 and (df.columns.dtype == "int64" or all(str(c).isdigit() for c in df.columns)):
+            new_cols = [str(x).strip() for x in df.iloc[0]]
+            df = df.iloc[1:].reset_index(drop=True)
+            df.columns = new_cols
+        return df
+
+    if not isinstance(source, dict):
+        raise ValueError(f"Invalid source specification: {source}")
+
+    s_type = source.get("type", "excel").lower()
+
+    if s_type == "db":
+        conn_id = source.get("connection")
+        raw_sql = source.get("query")
+        if not raw_sql:
+            raise ValueError("Database source must specify 'query'.")
+        db_url = db_resolver_func(conn_id) if db_resolver_func else conn_id
+        resolved_url = resolve_sqlalchemy_url(db_url)
+        engine = create_engine(resolved_url)
+        with engine.connect() as conn:
+            return pd.read_sql_query(text(raw_sql), conn)
+
+    elif s_type in ("excel", "xlsx"):
+        path = Path(source.get("path", "")).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"Source Excel file not found: {path}")
+        sheet = source.get("sheet", 0)
+        return pd.read_excel(path, sheet_name=sheet)
+
+    elif s_type == "csv":
+        path = Path(source.get("path", "")).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"Source CSV file not found: {path}")
+        return pd.read_csv(path)
+
+    else:
+        raise ValueError(f"Unsupported source type: '{s_type}'.")
+
+
+def compare_master_datasets(
+    source_a: Union[str, Dict[str, Any]],
+    source_b: Union[str, Dict[str, Any]],
+    key_columns: List[str],
+    column_mapping: Optional[Dict[str, str]] = None,
+    compare_columns: Optional[List[str]] = None,
+    numeric_tolerance: float = 0.001,
+    ignore_whitespace_case: bool = True,
+    output_report_path: Optional[str] = None,
+    db_resolver_func=None,
+) -> Dict[str, Any]:
+    """
+    Deterministically compare two master datasets (Excel vs Excel, DB vs Excel, or DB vs DB).
+    Detects new records, missing records, and field-level discrepancies with tolerance.
+
+    Args:
+        source_a: Baseline master (file path or dict specification).
+        source_b: Comparison / New master (file path or dict specification).
+        key_columns: List of primary key column names (as named in source_a).
+        column_mapping: Optional map of source_b column names to source_a column names
+                        (e.g. {"Material Number": "material_number", "Unit Rate": "sale_price"}).
+        compare_columns: Optional subset of source_a column names to compare.
+        numeric_tolerance: Maximum absolute difference considered equal for numbers (default 0.001).
+        ignore_whitespace_case: If True, trims whitespace and ignores case for string comparison.
+        output_report_path: Optional path to save a styled multi-tab Excel audit report.
+        db_resolver_func: Function to resolve connection names if DB sources are used.
+    """
+    t_start = datetime.now()
+
+    # 1. Load DataFrames
+    df_a = _load_dataset(source_a, db_resolver_func)
+    df_b = _load_dataset(source_b, db_resolver_func)
+
+    # 2. Normalize and apply column mapping to source_b
+    df_a.columns = [str(c).strip() for c in df_a.columns]
+    df_b.columns = [str(c).strip() for c in df_b.columns]
+
+    if column_mapping:
+        # Rename source_b columns to match source_a naming convention
+        rename_dict = {}
+        for b_col, a_col in column_mapping.items():
+            b_clean = str(b_col).strip()
+            a_clean = str(a_col).strip()
+            if b_clean in df_b.columns:
+                rename_dict[b_clean] = a_clean
+        df_b = df_b.rename(columns=rename_dict)
+
+    # 3. Validate Key Columns
+    for k in key_columns:
+        if k not in df_a.columns:
+            raise ValueError(f"Key column '{k}' not found in Source A. Available: {list(df_a.columns)}")
+        if k not in df_b.columns:
+            raise ValueError(f"Key column '{k}' not found in Source B. Available: {list(df_b.columns)}")
+
+    # 4. Determine columns to compare
+    if not compare_columns:
+        shared_cols = [c for c in df_a.columns if c in df_b.columns and c not in key_columns]
+    else:
+        shared_cols = [c for c in compare_columns if c in df_a.columns and c in df_b.columns and c not in key_columns]
+
+    # Clean key column values to strings for robust joining
+    for k in key_columns:
+        df_a[k] = df_a[k].astype(str).str.strip()
+        df_b[k] = df_b[k].astype(str).str.strip()
+
+    # 5. Full Outer Join on Key Columns
+    merged = pd.merge(df_a, df_b, on=key_columns, how="outer", suffixes=("_a", "_b"), indicator=True)
+
+    only_in_a = merged[merged["_merge"] == "left_only"].copy()
+    only_in_b = merged[merged["_merge"] == "right_only"].copy()
+    in_both = merged[merged["_merge"] == "both"].copy()
+
+    # 6. Detailed Field Comparison
+    discrepancies = []
+    col_discrepancy_counts: Dict[str, int] = {c: 0 for c in shared_cols}
+
+    for _, row in in_both.iterrows():
+        row_diffs = {}
+        for col in shared_cols:
+            val_a = row.get(f"{col}_a")
+            val_b = row.get(f"{col}_b")
+
+            # Handle nulls
+            is_na_a = pd.isna(val_a)
+            is_na_b = pd.isna(val_b)
+            if is_na_a and is_na_b:
+                continue
+            if is_na_a != is_na_b:
+                row_diffs[col] = {
+                    "source_a": _clean_val(val_a),
+                    "source_b": _clean_val(val_b),
+                    "delta": None,
+                    "type": "null_mismatch",
+                }
+                col_discrepancy_counts[col] += 1
+                continue
+
+            # Numeric comparison
+            is_num_a = isinstance(val_a, (int, float)) and not isinstance(val_a, bool)
+            is_num_b = isinstance(val_b, (int, float)) and not isinstance(val_b, bool)
+
+            if is_num_a and is_num_b:
+                delta = float(val_b) - float(val_a)
+                if abs(delta) > numeric_tolerance:
+                    pct = round((delta / float(val_a) * 100), 2) if float(val_a) != 0 else None
+                    row_diffs[col] = {
+                        "source_a": _clean_val(val_a),
+                        "source_b": _clean_val(val_b),
+                        "delta": round(delta, 4),
+                        "pct_change": pct,
+                        "type": "numeric_diff",
+                    }
+                    col_discrepancy_counts[col] += 1
+            else:
+                # String / Boolean comparison
+                s_a = str(val_a).strip()
+                s_b = str(val_b).strip()
+                if ignore_whitespace_case:
+                    s_a_cmp = s_a.lower()
+                    s_b_cmp = s_b.lower()
+                else:
+                    s_a_cmp = s_a
+                    s_b_cmp = s_b
+
+                if s_a_cmp != s_b_cmp:
+                    row_diffs[col] = {
+                        "source_a": _clean_val(val_a),
+                        "source_b": _clean_val(val_b),
+                        "delta": None,
+                        "type": "text_diff",
+                    }
+                    col_discrepancy_counts[col] += 1
+
+        if row_diffs:
+            keys_dict = {k: row[k] for k in key_columns}
+            discrepancies.append({"keys": keys_dict, "differences": row_diffs})
+
+    identical_records_count = len(in_both) - len(discrepancies)
+
+    # 7. Generate Multi-Tab Styled Audit Report
+    report_file_path = None
+    if output_report_path:
+        out_p = Path(output_report_path).resolve()
+        out_p.parent.mkdir(parents=True, exist_ok=True)
+        wb = Workbook()
+
+        # Styles
+        font_title = Font(name="Calibri", size=14, bold=True, color="1F497D")
+        font_header = Font(name="Calibri", size=11, bold=True, color="FFFFFF")
+        font_bold = Font(name="Calibri", size=11, bold=True)
+        fill_header_navy = PatternFill(start_color="1F497D", end_color="1F497D", fill_type="solid")
+        fill_header_green = PatternFill(start_color="27AE60", end_color="27AE60", fill_type="solid")
+        fill_header_orange = PatternFill(start_color="E67E22", end_color="E67E22", fill_type="solid")
+        fill_diff_yellow = PatternFill(start_color="FFF3CD", end_color="FFF3CD", fill_type="solid")
+        fill_diff_red = PatternFill(start_color="F8D7DA", end_color="F8D7DA", fill_type="solid")
+        border_thin = Border(
+            left=Side(style="thin", color="D3D3D3"),
+            right=Side(style="thin", color="D3D3D3"),
+            top=Side(style="thin", color="D3D3D3"),
+            bottom=Side(style="thin", color="D3D3D3"),
+        )
+
+        # Tab 1: Overview
+        ws_overview = wb.active
+        ws_overview.title = "Audit Overview"
+        ws_overview.append(["Master Data Reconciliation Audit Report", ""])
+        ws_overview["A1"].font = font_title
+        ws_overview.append([])
+        ws_overview.append(["Metric", "Count / Value"])
+        ws_overview["A3"].font = font_header
+        ws_overview["B3"].font = font_header
+        ws_overview["A3"].fill = fill_header_navy
+        ws_overview["B3"].fill = fill_header_navy
+
+        metrics = [
+            ("Audit Execution Timestamp", datetime.now().isoformat()),
+            ("Source A Total Records", len(df_a)),
+            ("Source B Total Records", len(df_b)),
+            ("Matched Primary Keys", len(in_both)),
+            ("Identical Records (Within Tolerance)", identical_records_count),
+            ("Records with Value Discrepancies", len(discrepancies)),
+            ("New Records (Source B Only)", len(only_in_b)),
+            ("Missing Records (Source A Only)", len(only_in_a)),
+            ("Numeric Tolerance Applied", numeric_tolerance),
+        ]
+        for m_name, m_val in metrics:
+            ws_overview.append([m_name, m_val])
+
+        ws_overview.append([])
+        ws_overview.append(["Field Name", "Mismatched Rows Count"])
+        ws_overview["A15"].font = font_header
+        ws_overview["B15"].font = font_header
+        ws_overview["A15"].fill = fill_header_navy
+        ws_overview["B15"].fill = fill_header_navy
+        for fld, cnt in col_discrepancy_counts.items():
+            ws_overview.append([fld, cnt])
+
+        # Tab 2: Discrepancies
+        if discrepancies:
+            ws_diff = wb.create_sheet("Field Differences")
+            diff_headers = list(key_columns) + [
+                "Field",
+                "Source A (Baseline)",
+                "Source B (New)",
+                "Delta",
+                "% Change",
+                "Diff Type",
+            ]
+            ws_diff.append(diff_headers)
+            for c_idx in range(1, len(diff_headers) + 1):
+                cell = ws_diff.cell(row=1, column=c_idx)
+                cell.font = font_header
+                cell.fill = fill_header_navy
+
+            for item in discrepancies:
+                k_vals = [item["keys"][k] for k in key_columns]
+                for fld, diff_info in item["differences"].items():
+                    row_vals = k_vals + [
+                        fld,
+                        str(diff_info["source_a"]),
+                        str(diff_info["source_b"]),
+                        diff_info.get("delta"),
+                        diff_info.get("pct_change"),
+                        diff_info.get("type"),
+                    ]
+                    ws_diff.append(row_vals)
+                    # highlight
+                    curr_row = ws_diff.max_row
+                    for c_idx in range(1, len(row_vals) + 1):
+                        ws_diff.cell(row=curr_row, column=c_idx).fill = fill_diff_yellow
+
+        # Tab 3: New Records in B
+        if len(only_in_b) > 0:
+            ws_new = wb.create_sheet("New Records")
+            b_cols = [c for c in df_b.columns if not c.endswith("_a")]
+            clean_b_cols = [c.replace("_b", "") for c in b_cols]
+            ws_new.append(clean_b_cols)
+            for c_idx in range(1, len(clean_b_cols) + 1):
+                cell = ws_new.cell(row=1, column=c_idx)
+                cell.font = font_header
+                cell.fill = fill_header_green
+
+            for _, row in only_in_b.iterrows():
+                ws_new.append([_clean_val(row.get(f"{c}_b", row.get(c))) for c in clean_b_cols])
+
+        # Tab 4: Missing Records in B
+        if len(only_in_a) > 0:
+            ws_miss = wb.create_sheet("Missing Records")
+            a_cols = [c for c in df_a.columns if not c.endswith("_b")]
+            clean_a_cols = [c.replace("_a", "") for c in a_cols]
+            ws_miss.append(clean_a_cols)
+            for c_idx in range(1, len(clean_a_cols) + 1):
+                cell = ws_miss.cell(row=1, column=c_idx)
+                cell.font = font_header
+                cell.fill = fill_header_orange
+
+            for _, row in only_in_a.iterrows():
+                ws_miss.append([_clean_val(row.get(f"{c}_a", row.get(c))) for c in clean_a_cols])
+
+        # Auto-fit columns across all sheets
+        for sheet in wb.worksheets:
+            for col in sheet.columns:
+                max_len = max(len(str(c.value or "")) for c in col)
+                col_letter = get_column_letter(col[0].column)
+                sheet.column_dimensions[col_letter].width = min(max(max_len + 3, 12), 45)
+
+        wb.save(out_p)
+        wb.close()
+        report_file_path = str(out_p)
+
+    duration = (datetime.now() - t_start).total_seconds()
+
+    return {
+        "status": "success",
+        "summary": {
+            "source_a_records": len(df_a),
+            "source_b_records": len(df_b),
+            "matched_keys": len(in_both),
+            "matching_records": identical_records_count,
+            "modified_records": len(discrepancies),
+            "new_records_in_b": len(only_in_b),
+            "missing_records_in_b": len(only_in_a),
+        },
+        "total_source_a_records": len(df_a),
+        "total_source_b_records": len(df_b),
+        "matched_primary_keys": len(in_both),
+        "identical_records_count": identical_records_count,
+        "records_with_discrepancies_count": len(discrepancies),
+        "new_records_in_source_b_count": len(only_in_b),
+        "missing_records_in_source_b_count": len(only_in_a),
+        "column_discrepancy_counts": col_discrepancy_counts,
+        "sample_discrepancies": discrepancies[:10],
+        "audit_report_file": report_file_path,
+        "duration_seconds": round(duration, 3),
+    }
+
+
+def reconcile_db_vs_excel(
+    sql_query: str,
+    excel_path: str,
+    key_columns: List[str],
+    db_url_or_config: Union[str, Dict[str, Any]],
+    sheet_name: Optional[Union[str, int]] = 0,
+    compare_columns: Optional[List[str]] = None,
+    output_report_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Backwards-compatible wrapper delegating to compare_master_datasets.
+    """
+    db_source = {"type": "db", "connection": db_url_or_config, "query": sql_query}
+    excel_source = {"type": "excel", "path": excel_path, "sheet": sheet_name}
+    return compare_master_datasets(
+        source_a=db_source,
+        source_b=excel_source,
+        key_columns=key_columns,
+        compare_columns=compare_columns,
+        output_report_path=output_report_path,
+        db_resolver_func=lambda c: c,
+    )

mcp_win_stdio/excel_db/cli.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""
+CLI entry point for mcp-win-stdio-excel-db.
+"""
+
+import argparse
+
+from mcp_win_stdio.excel_db.server import mcp
+
+
+def main():
+    parser = argparse.ArgumentParser(description="mcp-win-stdio-excel-db MCP Server")
+    parser.add_argument("--transport", default="stdio", choices=["stdio", "sse"], help="MCP transport")
+    parser.add_argument("--port", type=int, default=8001, help="Port for SSE transport")
+    args = parser.parse_args()
+
+    if args.transport == "sse":
+        mcp.run(transport="sse", port=args.port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio/excel_db/engine.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Cross-Source Join Engine for executing unified SQL queries across SQL Databases and Excel Workbooks.
+"""
+
+import re
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+from sqlalchemy import create_engine, text
+
+from mcp_win_stdio.excel_db.stream import resolve_sqlalchemy_url
+
+
+def run_cross_source_query(
+    sources: List[Dict[str, Any]],
+    transformation_sql: str,
+    target: Optional[Dict[str, Any]] = None,
+    db_resolver_func=None,
+) -> Dict[str, Any]:
+    """
+    Execute a unified SQL query joining SQL databases and Excel spreadsheets in memory.
+
+    Args:
+        sources: List of data source definitions:
+            - {"name": "orders", "type": "db", "connection": "postgres", "query": "SELECT * FROM orders"}
+            - {"name": "clients", "type": "excel", "path": "Z:/data/clients.xlsx", "sheet": "VIP"}
+        transformation_sql: The SQL query to join/transform data across sources.
+        target: Optional export target:
+            - {"type": "excel", "path": "Z:/out.xlsx", "sheet": "Report"}
+            - {"type": "db", "connection": "mysql", "table": "report_tbl"}
+        db_resolver_func: Function to resolve connection names to db URLs.
+    """
+    t_start = datetime.now()
+    mem_conn = sqlite3.connect(":memory:")
+    loaded_sources_info = []
+
+    try:
+        # 1. Ingest all sources into in-memory engine
+        for src in sources:
+            s_name = src.get("name")
+            s_type = src.get("type", "db").lower()
+
+            if not s_name:
+                raise ValueError("Each source must specify a unique 'name' table alias.")
+
+            if s_type == "db":
+                conn_id = src.get("connection")
+                raw_sql = src.get("query")
+                if not raw_sql:
+                    raise ValueError(f"Source '{s_name}' is missing 'query'.")
+
+                # Resolve DB URL
+                db_url = db_resolver_func(conn_id) if db_resolver_func else conn_id
+                resolved_url = resolve_sqlalchemy_url(db_url)
+                eng = create_engine(resolved_url)
+
+                with eng.connect() as c:
+                    df = pd.read_sql_query(text(raw_sql), c)
+
+            elif s_type in ("excel", "xlsx", "csv"):
+                file_path = Path(src.get("path", "")).resolve()
+                if not file_path.exists():
+                    raise FileNotFoundError(f"Source file not found: {file_path}")
+
+                if file_path.suffix.lower() == ".csv":
+                    df = pd.read_csv(file_path)
+                else:
+                    sheet = src.get("sheet", 0)
+                    df = pd.read_excel(file_path, sheet_name=sheet)
+
+            else:
+                raise ValueError(f"Unsupported source type: '{s_type}'. Supported: 'db', 'excel', 'csv'.")
+
+            # Clean column headers for SQLite
+            df.columns = [re.sub(r"[^a-zA-Z0-9_]", "_", str(col).strip()) for col in df.columns]
+            df.to_sql(s_name, mem_conn, index=False, if_exists="replace")
+            loaded_sources_info.append(f"{s_name} ({len(df)} rows, {len(df.columns)} cols)")
+
+        # 2. Execute unified transformation query
+        result_df = pd.read_sql_query(transformation_sql, mem_conn)
+        res_rows, res_cols = result_df.shape
+
+        # 3. Export to target or return summary
+        output_summary = {}
+        if target:
+            t_type = target.get("type", "excel").lower()
+            if t_type == "excel":
+                out_path = Path(target.get("path", "unified_report.xlsx")).resolve()
+                out_path.parent.mkdir(parents=True, exist_ok=True)
+                sheet_name = target.get("sheet", "Report")
+
+                with pd.ExcelWriter(out_path, engine="openpyxl") as writer:
+                    result_df.to_excel(writer, sheet_name=sheet_name, index=False)
+                output_summary = {"type": "excel", "path": str(out_path), "sheet": sheet_name, "rows_written": res_rows}
+
+            elif t_type == "db":
+                conn_id = target.get("connection")
+                tbl_name = target.get("table", "pipeline_results")
+                if_exists = target.get("if_exists", "append")
+
+                db_url = db_resolver_func(conn_id) if db_resolver_func else conn_id
+                resolved_url = resolve_sqlalchemy_url(db_url)
+                eng = create_engine(resolved_url)
+
+                result_df.to_sql(tbl_name, con=eng, if_exists=if_exists, index=False, chunksize=1000)
+                output_summary = {"type": "db", "table": tbl_name, "rows_inserted": res_rows}
+
+        duration = (datetime.now() - t_start).total_seconds()
+
+        # If no target specified, return small sample preview (up to 5 rows)
+        sample_preview = result_df.head(5).to_dict(orient="records") if not target else None
+
+        return {
+            "status": "success",
+            "sources_loaded": loaded_sources_info,
+            "result_rows": res_rows,
+            "result_columns": res_cols,
+            "columns": list(result_df.columns),
+            "output_target": output_summary if target else "In-Memory Preview",
+            "preview_sample": sample_preview,
+            "duration_seconds": round(duration, 3),
+        }
+
+    finally:
+        mem_conn.close()

mcp_win_stdio/excel_db/guide.py

@@ -0,0 +1,67 @@
+"""
+Interactive and printable guide for the Excel-DB High-Speed Pipeline MCP Server.
+"""
+
+EXCEL_DB_GUIDE = """
+# ================================================================
+# EXCEL-DB MCP (HIGH-SPEED PIPELINES & RECONCILIATION) - USER GUIDE
+# ================================================================
+
+The Excel-DB MCP server provides 9 specialized tools for zero-context streaming,
+cross-source SQL queries, automated master dataset reconciliation, and transactional
+database migrations between Microsoft Excel and relational databases (PostgreSQL, MySQL, SQLite).
+
+----------------------------------------------------------------
+1. TOOL SUMMARY (9 TOOLS)
+----------------------------------------------------------------
+* Streaming & Direct ETL:
+  - db_to_excel_stream(sql_query, target_excel_path, ...):
+    Directly streams database query results to an Excel file with chunking,
+    optional table styling, and auto-fit column widths without loading rows into LLM context.
+  - excel_to_db_upsert(excel_path, target_table, chunk_size, ...):
+    Bulk streams Excel worksheet rows directly into a database table in chunks with append/replace modes.
+  - db_to_excel_template(sql_query, template_excel_path, output_excel_path, ...):
+    Injects query results into pre-styled Excel template workbooks, preserving charts, logos, and macros.
+
+* Master Data Comparison & Audit:
+  - compare_master_datasets(source_a, source_b, key_columns, column_mapping, tolerance, output_report_path):
+    Deterministically compares two master datasets (Excel vs Excel, DB vs Excel, DB vs DB).
+    Detects additions, removals, and field discrepancies with floating-point tolerance.
+    Generates styled 4-tab Excel audit workbooks with KPI summary cards and cell diff highlights.
+  - reconcile_db_vs_excel(sql_query, excel_path, key_columns, ...):
+    Audits a live SQL database query against an Excel spreadsheet to spot missing records or discrepancies.
+
+* Database Migration & Synchronization:
+  - generate_master_migration_plan(excel_path, target_table, key_columns, column_mapping_json, fk_lookups_json, ...):
+    Generates atomic, transactional PostgreSQL/MySQL migration SQL scripts from an Excel master.
+    Includes pre-flight foreign key validation (resolving codes like 'ROL' to UUIDs against live DB) and UPSERT handling.
+  - sync_master_to_db(excel_path, target_table, key_columns, column_mapping_json, fk_lookups_json, dry_run=True, ...):
+    Executes master data synchronization against a live database with full transactional safety.
+    Dry-run mode (default) simulates the entire migration and verifies all constraints without committing.
+
+* Unified Analytics & Custom Python Pipelines:
+  - query_unified_sources(pipeline_spec_json):
+    Executes in-memory DuckDB/SQLite SQL queries across multiple heterogeneous sources (joining DB tables and Excel files).
+  - py_template_pipeline(template_excel_path, output_excel_path, pipeline_spec_json):
+    Executes custom Python/Pandas logic on multiple sources and writes resulting DataFrames into template sheets as styled tables.
+
+----------------------------------------------------------------
+2. BEST PRACTICES & LLM PROMPT RECIPES
+----------------------------------------------------------------
+* Reconciling Master Data:
+  "Compare masters/NewCatalog.xlsx against showreel_dev database table props_management.materials,
+   key on 'material_number', map 'SKU' -> 'material_number', and generate an audit report at reports/diff.xlsx."
+
+* Safe Transactional Migration:
+  "Run sync_master_to_db with dry_run=True first to verify foreign keys and check constraint violations.
+   Only rerun with dry_run=False after inspecting the dry-run summary."
+
+* Zero-Context Streaming for Large Datasets:
+  "Never load 50,000 rows into prompt context. Always use db_to_excel_stream to pipe query results directly into Excel."
+# ================================================================
+"""
+
+
+def print_excel_db_guide() -> None:
+    """Print the formatted Excel-DB MCP guide to stdout."""
+    print(EXCEL_DB_GUIDE.strip())