Expose an evidence-first Draftwright MCP surface for agent review and manufacturing readiness

[pzfreo]

Goal

Provide a supported MCP boundary for an agent to inspect a STEP file, generate/edit a Sheet, render it, compare the drawing back to the source, and prepare a controlled shop package.

This is not a request for one opaque generate_drawing tool. The GRM-03 evaluation showed that useful agent work happens between deterministic stages: inspect evidence, review declarations, render candidates, reconcile coverage, ask for missing manufacturing intent, then release.

Why

Without a Draftwright tool boundary, the GRM-03 loop required:

• shelling into Draftwright's private Python environment;
• ad hoc build123d/OpenCascade face and edge probing;
• parsing CLI stdout and Python object reprs;
• arbitrary script rewrites;
• manual PNG/PDF comparison;
• a separate volume reconstruction to compare declarations with the STEP;
• manually distinguishing geometry facts from material/thread/tolerance assumptions.

Draftwright already owns most of the underlying concepts. MCP would expose them as structured evidence rather than requiring consumers to reverse-engineer the process.

Proposed tool groups

Inspect

• dw.inspect_step: hashes, units, product metadata, bbox/volume, PMI, recognized families, stable face/edge evidence, and unclassified defining geometry.
• dw.explain_feature: source faces, measurements, adjacency, classification rationale, alternatives, and a highlighted preview.

Author and validate

• dw.generate_script: Sheet script plus a machine-readable declaration/evidence manifest.
• dw.validate_script: syntax/API, source hash, declaration-vs-STEP reconciliation, unsupported render intents, and unproven manufacturing claims.
• dw.apply_declaration_patch: bounded operations such as reclassify step -> boss, add chamfer from face evidence, consolidate repeated callouts, or set strict scale.

Render and critique

• dw.render: deterministic artifacts, actual page/scale, view and annotation bounds, and per-requirement outcomes.
• dw.lint: structured issue IDs with affected SVG/raster crop bounds.
• dw.try_layouts: candidate thumbnails and comparable drops/overlaps/print-size evidence.

Reconcile and release

• dw.compare_step_to_drawing: map STEP feature/face -> declaration -> approved measurement -> rendered annotation, with covered/consolidated/omitted/dropped/contradicted/unverifiable outcomes.
• dw.manufacturing_readiness: separate geometry coverage from missing material, thread, fit, tolerance, finish, and process intent.
• dw.diff_revision: geometry, requirement, and representation changes.
• dw.export_shop_package: STEP + released PDF + optional DXF/SVG + manifest and hashes; fail closed on preliminary status or unresolved blockers.

Non-negotiable contracts

Every response should include:

• stable artifact ID and source hash;
• units and Draftwright/version identity;
• provenance per fact: STEP geometry, source PMI, user declaration, or unapproved inference;
• one explicit outcome for every authored requirement;
• no invented material/thread/tolerance/finish merely to obtain a passing result.

Writes and release should remain separate. export_shop_package should require explicit authorization after manufacturing_readiness is clear.

Suggested first vertical slice

A useful MVP is five tools:

1. inspect_step
2. generate_script
3. render
4. compare_step_to_drawing
5. manufacturing_readiness

Acceptance for the GRM-03 fixture:

• inspection exposes the three conical faces and the diameter 6 x 0.5 boss evidence;
• generation records unsupported/unrepresented geometry rather than silently losing it;
• render returns view/annotation bounds and a complete outcome ledger;
• comparison identifies any source-profile transition absent from the drawing;
• readiness blocks manufacture on missing material/thread/tolerance/finish intent without guessing values.

Related architecture: #1202, #1217, #1130, #1002.

[pzfreo]

Consumer perspective from draftwright-io, which runs a sandboxed Codex agent against Draftwright to review and improve generated drawings. We reached this issue's conclusion from the opposite direction, and I think the evidence is worth adding.

We just built inspect_step by hand, badly

Until today our agent's only view of the part was six numbers:

size_mm 28.7 10.0 10.0
volume_mm3 391.803
faces 16
edges 24

That is not enough to draw from, and the consequence is measurable: across 467 agent turns in 14 days, "chamfer" appears in one. The agent was not being lazy — it had no way to know the part had any.

Comparing against a hand-run of Codex + Draftwright CLI on GRM-03 made the gap obvious. That run shelled into the Python environment, enumerated faces, and recovered the full axial profile including three conical chamfers. It drew all three. Ours could not.

So we implemented this issue's own acceptance criterion — "inspection exposes the three conical faces and the ⌀6 × 0.5 boss evidence" — inside our repo, in raw build123d:

curved faces, by axis then position —
  cylinder  dia 1.6                    x -3.2 to 4.8
  cylinder  dia 4.0                    x -3.2 to 0.0
  cylinder  dia 6.0                    x -0.0 to 0.5
  cone      dia 9.4 to 10.0 (leg 0.3)  x 0.5 to 0.8
  cylinder  dia 10.0                   x 0.8 to 2.2
  cone      dia 9.4 to 10.0 (leg 0.3)  x 2.2 to 2.5
  cylinder  dia 5.0                    x 2.5 to 5.5
  cylinder  dia 3.0                    x 5.5 to 25.0
  cone      dia 2.0 to 3.0 (leg 0.5)   x 25.0 to 25.5

This is duplication on the day it shipped. It reads OCC surface adaptors directly, it knows nothing about Draftwright's recognised families, and it will drift the first time recognition changes. If inspect_step lands upstream we delete it the same week.

The reason it had to live downstream is simply that there is nowhere else to put it: import draftwright exposes 16 public names, and none of them will tell you what faces a solid has. extract_pmi covers PMI; nothing covers geometry evidence.

Where the code should live

Our suggestion is to split on what is true versus who is asking.

Evidence and verbs belong in Draftwright, as a Python API first — not as MCP. inspect_step, explain_feature, compare_step_to_drawing and the readiness ledger are all statements about geometry and the drawing, and Draftwright already owns recognition, lint and layout. 0.4.9 moved further in this direction than the issue credits: draftwright.linting already exposes evidence, ClaimOutcome, lint_declaration_reconciliation and hole_coverage — a good part of compare_step_to_drawing in embryo.

MCP is a transport, not a home for logic. Two things follow:

• A Draftwright MCP server is worth shipping for CLI and local agent use — it is exactly what would have spared the GRM-03 run from shelling into a private environment. But it should be a thin wrapper over the public Python API, never the only way to reach these facts. Consumers that are not MCP clients need the same evidence.
• The MCP server our agent actually talks to has to stay on our side, because it knows things a drawing library should not: which workspace, which tenant, the job's token budget, the sandbox, which artifacts may leave. Those are session concerns.

export_shop_package fits neither cleanly, as specified. It bundles DXF and SVG, which our public surface deliberately does not expose, and "fail closed on preliminary status" is a release policy with an authorization step — a product decision, and for us a tenanted and billable one. Local/CLI capability, we would guess; we would not expose it as-is.

On the MVP five

We would reorder rather than reduce.

inspect_step is worth more than the other four combined right now. It is the one thing that was actually blocking work, and every consumer who wants it is currently writing their own worse version. The others are further from the critical path: generate_script largely exists as --script, and render/lint are reachable today.

compare_step_to_drawing is the genuinely new and hard one, and the one we would most like not to reimplement — it needs the recognised model, the declaration set and the placement outcomes together, which only Draftwright holds. It would be a shame for consumers to grow second versions of it while the ledger work in 0.4.9 is already heading there.

Two contract notes from running this in production

Determinism matters more than it looks. Before 0.4.9 an unnamed object appeared in lint text as view 'view@140436412189584', so two renders of the same sheet produced different lint. We compare lint verbatim to detect a no-op turn, and this made every candidate look changed — a production run rejected nine consecutive equivalent candidates, each one reaching a paid review. #1196 fixed it, we removed our normaliser, and we now have a test asserting lint text is byte-identical across two renders. Whatever the MCP surface returns, please keep it stable across identical inputs; agent loops compare responses.

Provenance per fact is the right call, and the hardest one to add later. The GRM-03 evaluation's most valuable output was not the drawing but the list of what a STEP cannot establish — material, thread, fit, finish. Our agent's brief forbids inventing those. Having Draftwright distinguish "STEP geometry" from "unapproved inference" in the response itself would let consumers enforce that structurally instead of by prompt, which is the difference between a rule and a hope.