Repository Public Research preview
1# xlsx-audit-mcp23An MCP server that audits Excel workbooks **without Excel**. It reads the `.xlsx` / `.xlsm` file4itself (a ZIP of XML parts), executes nothing, and reports what a careful reviewer looks for:5errors, numbers buried in formulas, broken patterns, circular references, failing controls and6stale values. It also compares a submission with a reference workbook and prepares rubric-based7grading evidence.89- No dependency beyond the MCP SDK: the reader uses `node:zlib` only.10- Read-only. The only writes are reports, to **new** files inside the allowed directory.11- Local only: no network access.1213## Install1415```bash16skills install @spboucher/xlsx-audit-mcp --client claude-code17```1819or by hand:2021```bash22cd xlsx-audit-mcp && npm install --omit=dev23claude mcp add xlsx-audit --env XLSX_AUDIT_ROOT="$HOME/Documents/models" -- node "$PWD/server.mjs"24```2526Generic MCP configuration:2728```json29{ "mcpServers": { "xlsx-audit": { "command": "node", "args": ["/path/to/xlsx-audit-mcp/server.mjs"], "env": { "XLSX_AUDIT_ROOT": "/path/to/workbooks" } } } }30```3132Requires Node.js 20 or later.3334## Configuration3536| Variable | Default | Meaning |37|---|---|---|38| `XLSX_AUDIT_ROOT` | working directory | Only directory workbooks are read from and reports written to. Symbolic links leaving it are refused. |39| `XLSX_AUDIT_MAX_FILE_MB` | 50 | Largest workbook file accepted. |40| `XLSX_AUDIT_MAX_UNZIPPED_MB` | 128 per part, 384 total | Cap on decompressed size. Inflation stops at the cap whatever the ZIP header declares. |41| `XLSX_AUDIT_MAX_CELLS` | 2 000 000 | Largest number of non-empty cells loaded. |4243## Tools4445| Tool | What it answers |46|---|---|47| `workbook_summary` | What is in this file? Sheets (hidden included), used ranges, counts, names, functions, macros, external links. |48| `read_range` | What do these cells hold? Value, formula, number format, and where the value comes from. Paged. |49| `list_formulas` | How is the model built? Formulas with R1C1 pattern and precedent / dependent counts, or grouped by pattern. |50| `find_errors` | Which cells are in error, and which ones are the root causes? |51| `find_hardcoded` | Where are numbers buried in formulas? Where was a formula overwritten by a typed number? |52| `formula_consistency` | Which cell breaks the pattern of its row or column, and what should it hold? |53| `find_circular` | Are there circular references? Each loop is printed cell by cell. |54| `trace_precedents` | Where does this number come from? |55| `trace_dependents` | What does this cell feed? |56| `check_controls` | Do the model's own checks pass? Are some of them typed by hand? Does the overall cell agree? |57| `recalc_check` | Do the stored results follow from the formulas? (stale or altered values) |58| `compare_workbooks` | How does a submission differ from the reference? |59| `grade_submission` | Rubric-based evidence and suggested points. An aid: a human decides. |60| `export_report` | The whole audit as Markdown or JSON, inline or in a new file. |6162Typical session: `workbook_summary` → `export_report` → `trace_precedents` on each finding worth63explaining.6465### Where values come from6667Every value carries a `source`:6869- `constant`: typed in the cell.70- `cached`: the result Excel (or LibreOffice) stored in the file next to the formula.71- `evaluated`: the file holds no stored result and the formula is inside the supported subset.72- `unknown`: no stored result and the formula is outside the subset. Never guessed.7374### The evaluated subset7576`+ - * / ^`, unary minus, `%`, comparisons, `SUM`, `AVERAGE`, `MIN`, `MAX`, `ROUND`, `IF`, cell,77range and cross-sheet references, defined names that are plain references. Nothing else.78`recalc_check` and `workbook_summary` state the share of formulas outside the subset and the79reasons (for example `function VLOOKUP (212)`); those formulas are only read from stored values.8081### Grading rubric8283```json84{85 "tolerance": 0.005,86 "items": [87 { "id": "revenue", "label": "Revenue per year", "range": "Calc!B3:F3", "points": 5 },88 { "id": "units", "range": "Calc!C2:F2", "points": 4, "formula_required": true, "constant_credit": 0.5 },89 { "id": "summary", "ranges": ["Outputs!B1:B2"], "points": 2, "partial": "all_or_nothing", "carried_forward_credit": 0.5 }90 ]91}92```9394Per cell: `correct` (credit 1), `correct_value_typed_as_constant` (`constant_credit`, default 0.5,95only when `formula_required`), `carried_forward_error` (`carried_forward_credit`, default 1: the96reference formula applied to the submission's own earlier values gives the submitted value, so the97mistake is upstream and penalised there), `wrong`, `missing`, `unknown` (0, listed in98`needs_human_review`). `partial`: `proportional` (default) or `all_or_nothing`. Top-level fields99are defaults for every item. The result always carries a disclaimer: it is evidence for a grader,100not a grade.101102## Security103104- Workbooks are untrusted input. Nothing in them is executed: macros, external links, pivot caches105 and embedded objects are never opened; their presence is reported.106- The ZIP reader refuses entry names that leave the archive (`..`, absolute paths, backslashes),107 ZIP64, multi-disk and encrypted archives, and stops inflating at the configured limit. Nothing is108 ever extracted to disk.109- XML entities other than the five predefined ones are not expanded.110- Paths are resolved with symbolic links followed and must stay inside `XLSX_AUDIT_ROOT`.111- Reports are created with exclusive-create: an existing file is an error, never overwritten.112- Cell text is data. Every result carries a notice reminding the model not to follow instructions113 found in a workbook.114115## Limits116117- `.xlsx` and `.xlsm` only. Not `.xls`, `.xlsb`, `.ods`, `.csv`; not password-protected files.118- The evaluator is deliberately small (see above). A workbook saved by a library that does not119 calculate (openpyxl, for example) has no stored results: formulas outside the subset are then120 `unknown` until the file is opened and saved in Excel or LibreOffice.121- Dates are reported as serial numbers with their number format; they are not converted.122- Array formulas, data tables, structured table references, 3-D references and external references123 are recognised and reported as outside the subset.124- Not read: conditional formatting, data validation, charts, pivot tables, comments, cell125 protection, VBA.126- Pattern checks are heuristics: `formula_consistency` grades each finding `high` or `low`127 confidence, and a constant inside a formula is not always a defect. Errors hidden by `IFERROR`128 are invisible.129- A clean report shows that these mechanical defects are absent. It does not show the model is130 right.131- The dependency graph stops expanding after three million edges and says so (`graph_truncated`).132133## Tests134135```bash136npm test # 37 tests: engine, hostile files, MCP protocol with the official client137npm run fixtures # rebuild the .xlsx fixtures (a test checks they are up to date)138```139140Fixtures are written by a small writer in `test/fixtures/` that stores a result next to each141formula. `clean-libreoffice.xlsx` was recalculated by LibreOffice and serves as an external check142of the evaluator. See `test/fixtures/README.md`.143144## License145146MIT147