mto-mcp-server

An MCP server that reconciles a piping MTO (Material Take-Off) against a Plant 3D SCSA export, for industrial EPC projects.

The problem

MTOs drift out of sync with the model as a piping design evolves. Bringing one back in line is a recurring, mechanical-but-error-prone task: diff two Excel exports with different shapes, decide what changed, update quantities, add new items, and — carefully — remove items that dropped out of the design. Doing this by hand across hundreds of rows and 8 piping categories (pipes, elbows, tees, reducers, flanges, valves, blind flanges, gaskets) is slow and easy to get subtly wrong.

Related MCP server: procurement-tools

Why MCP instead of a script

The reconciliation logic itself could be a plain script. What makes this an agent tool rather than a script is the shape of the two calls:

• diff_mto_scsa only ever computes and reports. It's built so an LLM can call it, read the result, and reason about it in natural language — "SCSA shows 4 of these, MTO has 3, want me to bump it?" — before anything is written.

• apply_mto_update is split into a safe path (quantity corrections, new items — additive/corrective) and a gated path (removals — zeroing a quantity because the item left the design, which is destructive). The gate is two independent flags, dry_run and include_removals, not a single "confirm" toggle, so an agent (or a human driving it) can preview everything with dry_run=True, apply the safe part, and only zero items out once include_removals=True is passed explicitly and deliberately.

That two-tool shape — compute-and-explain, then gated-write — is the actual point of the project: it's the difference between "a script that mutates your MTO" and "a tool an agent can be trusted to drive."

Scope

This project demonstrates the reconciliation logic end-to-end against real elbow (Отвод) data — the two tools, the 3 scenarios, and the confirm-gate on removals are all built and tested against real MTO/SCSA files. Category-specific matching for other categories (valve check-type synonyms, reducer family+OD-pair+line) exists as draft code in matching.py but is intentionally not wired in — see "Known limitations" below. Everything not elbow-specific (normalization, the diff/apply split, the write logic) is category-agnostic and applies to any category once its match key is validated.

Built on prior work

The core normalization and categorization logic is ported, not rewritten, from rustam-zarifov/mto-scsa-reconciliation — a 6-script toolkit built from real EPC piping reconciliation work, covering all 7 major categories with a color-coded Excel report as output. That toolkit's raw-file assumptions (a 26-column master_mto.xlsm with section headers, feeding an intermediate MTO_Lookup_Table; a header-named SCSA export) don't match the simpler raw exports this project was tested against, so the I/O layer (io_excel.py) here is new. What's ported:

• normalize.py's classify_category() — the keyword-based category rules, straight from that project's categorize() (now covering fasteners, insulation, and structural steel too, not just the 8 piping categories, since the keyword list came over wholesale).

• normalize.py's Cyrillic х/Latin x unification, from that project's norm().

• domain_addons.py — GOST year-format normalization, line-code recovery, OD→DN lookup, and pipe-segment splitting, ported in full from 4_normalization_addons.py. Not wired into matching yet — elbows don't hit any of these cases; they're here for when gasket/pipe/flange matching gets built out.

• apply.py's _redistribute_group() — proportional redistribution across multiple MTO rows sharing one match key, from that project's 5_apply_fixes.py, replacing an earlier "dump into one row, zero the rest" approach.

One thing that did not port: that project's match key is (name, material), using a Материал column present on both sides of its pipeline. This project's raw MTO export has no comparable material column (only a line code, which turned out to be unreliable — see below), so the match key here stays name-only until that gap is closed.

The 3 scenarios

Items with matching quantities in both files produce no diff entry (counted in summary.matched only) — this is checked directly in the test suite, not assumed.

Install

pip install -e .

Requires mcp>=1.9.0,<2.0.0. Note: pip install "mcp[cli]" on its own pulls the 2.x line, which drags in a much heavier dependency set (opentelemetry, jsonschema, pyjwt>=2.10) that isn't needed for a local stdio server. This project pins <2.0.0 deliberately.

Run

mto-mcp-server

or point a Claude Desktop / Claude Code MCP config at python -m mto_mcp_server.server.

Tools

diff_mto_scsa(mto_path, scsa_path, category=None)

Read-only. Returns:

{
  "summary": {"matched": 1, "qty_mismatch": 2, "removed": 2, "new": 2},
  "qty_mismatch": [{"name": "...", "line": "...", "mto_qty": 3, "scsa_qty": 4, ...}],
  "removed":      [{"name": "...", "mto_qty": 1, ...}],
  "new":          [{"name": "...", "scsa_qty": 1, ...}]
}

category optionally restricts to one of the categories classify_category() produces — the 8 piping categories (pipe, elbow, tee, reducer, flange, valve, blind_flange, gasket) plus the extra buckets that came along with the ported keyword rules (stud_bolt, bolt, nut, washer, gate_valve, safety_valve, ball_valve, steam_trap, pipe_support, insulation, structural_steel). Omit it to diff everything.

apply_mto_update(mto_path, scsa_path, category=None, include_removals=False, dry_run=False, output_path=None)

Re-derives the diff internally from mto_path/scsa_path every call — it does not accept a pre-computed diff object from the caller. That keeps the tool safe against a stale or hand-edited diff being replayed, and keeps diff_mto_scsa a true preview with no side effects to trust.

• dry_run=True → compute and report, write nothing.

• dry_run=False, include_removals=False (default) → applies qty fixes and inserts; removals are reported but not written.

• dry_run=False, include_removals=True → also zeroes removed items.

• output_path → write to a different file instead of overwriting mto_path in place.

Matching design

• Normalization: strips °, a trailing ?, collapses whitespace, and unifies Cyrillic "х" / Latin "x" (a real bug source in dimension strings like "160x5") before any comparison.

• Default match key is name-only, not name+line. In the real SCSA export, line-code columns are populated for some standards (GOST) and empty for others (ASME) — see tests/fixtures/scsa_test.xlsx. Requiring line in the key would silently drop real matches. Line is still carried through on every diff entry as display metadata.

• Valves and reducers: the spec calls for check-type valve synonym folding (Обратный клапан = Обратный затвор) and family+OD-pair+line matching for reducers, but there was no real valve or reducer data available to validate either against — only elbow data was available. Both key functions exist as drafts in matching.py (valve_key, reducer_key) but are not wired in — see the _KEY_FUNCS comment. Both categories currently fall through to the name-only default key. Wiring either back in is a one-line change once there's real data to check it against.

• GOST/ASME cross-referencing falls out of the name-only key for free — the standard field is read but deliberately excluded from the key.

Testing

tests/test_diff.py runs against real (small) MTO/SCSA export pairs in tests/fixtures/, not synthetic data. Expected values were derived by hand-tracing the fixture files first, then asserted — not read off the code's own output. Covers: exact-match (no false flag), qty mismatch in both directions, removed items, new items, dry-run (no write), apply without removals (removed items untouched), apply with removals (zeroed), and new-item insertion (qty + next POZ number).

pip install pytest
pytest tests/ -v

Known limitations / next steps

• Category-specific matching (valve check-type synonyms, reducer family+OD-pair+line) is drafted but not validated against real data — see above. Demo and tests currently cover elbow reconciliation only.

• The match key is name-only, not (name, material) like the ported toolkit's proven engine — this project's raw MTO export doesn't expose a comparable material field yet. See "Built on prior work" above.

• domain_addons.py is ported but not wired into any matching path yet.

• Column positions in io_excel.py (MTO_COLUMNS, SCSA_COLUMNS) are verified against the two fixture files only; a different SCSA export layout would need the indices adjusted.