sheet-unmess

Forensic-style ingestion for messy Excel (.xlsx) and CSV files. It attempts to identify headers, remove common non-data rows, normalize common number formats, and produce a human-readable audit receipt.

Important: automatic header/row classification is heuristic. Always inspect the output and reconciliation receipt before using cleaned data for financial, regulatory, or other high-stakes decisions. A receipt is an audit report, not a cryptographic signature or proof that no data was lost.

Features

• Detects likely header rows and combines adjacent stacked headers.
• Propagates values from the top-left cell across merged Excel ranges.
• Classifies common title, blank, footnote, subtotal, and grand-total rows.
• Parses common US/EU number formats, accounting negatives, and percentages.
• Optionally returns a cleaning report with dropped-row details and total checks.
• Provides a CLI and a stdio MCP server for compatible AI clients.

Install from source

Python 3.10 or newer is required.

python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -e .

Quick start

from sheet_unmess import read_messy

df = read_messy("quarterly_report.xlsx")
print(df.head())

report = read_messy("quarterly_report.xlsx", return_report=True)
print(report.data.head())
print(report.receipt.to_markdown())

For European day-first dates, pass date_dayfirst=True.

CLI

sheet-unmess clean input.xlsx --out cleaned.csv --receipt audit.md
sheet-unmess clean input.csv --out cleaned.csv --dayfirst
sheet-unmess clean input.xlsx --sheet Financials --out cleaned.csv
sheet-unmess init-ai

--out writes CSV by default; use a .parquet extension for Parquet output (and install a suitable Parquet engine such as pyarrow).

Tests

python -m pip install -e ".[dev]"
python -m pytest

Or run the included test file directly:

python tests/test_sheet_unmess.py

MCP server

The package exposes sheet-unmess-mcp and sheet-unmess mcp. Example generic stdio MCP configuration:

{
  "mcpServers": {
    "sheet-unmess": {
      "command": "python",
      "args": ["-m", "sheet_unmess.mcp_server"]
    }
  }
}

Ensure the python executable points to the environment where sheet-unmess is installed. The sheet-unmess init-ai command writes project rules, a Cursor MCP configuration, and attempts to update the Claude Desktop configuration. Review generated configuration before using it.

Current limitations

• .xls legacy Excel files are not supported by the current openpyxl loader.
• Header detection and row classification are heuristic and may need manual review.
• Reconciliation currently compares embedded totals against aggregated clean-row sums; nested subtotals and multiple independent sections can require more sophisticated grouping logic.
• Mixed ambiguous dates cannot be inferred reliably; use date_dayfirst when appropriate.
• The MCP server reads files by local path and therefore needs filesystem access to the file being processed.

License

MIT