cadtokens — GD&T out of STEP files. Locally.

Read the semantic PMI (GD&T) of STEP AP242 files, check it for errors, and turn it into a ballooned inspection report — plus an MCP server so AI agents can query it.

• Pure Python, zero dependencies for parsing, PMI and characteristic lists

• Runs 100% locally — no cloud, no upload, works air-gapped

• Validated against the NIST MBE PMI test models

What it does

1. PMI extraction from STEP AP242 — mapped to faces

Every tolerance, dimension and datum is resolved to the B-Rep faces (or edges, axes, or the whole part) it applies to. Values carry their unit; nothing is assumed.

2. Inspection characteristic list (FAI / EMPB)

A numbered list — the starting point for an AS9102 Form 3, VDA 2 / EMPB or PPAP report. Characteristics on the same feature stay together, as on a ballooned drawing.

$ cadtokens characteristics nist_ftc_10_asme1_ap242-e2.stp
#   Characteristic    Specification                 Min   Max    Unit  Applies to
--  ----------------  ----------------------------  ----  -----  ----  ---------------------
1   Surface profile   ⌓ | 1.5 | A | B | C           0     1.5    mm    whole part
2   Flatness          ⏥ | 0.2                       0     0.2    mm    1 faces
3   Diameter          ⌀6.00 ±0.15                   5.85  6.15   mm    2 faces
4   Perpendicularity  ⟂ | ⌀0.25 | A                 0     0.25   mm    2 faces
...
10  Diameter          8X ⌀2.50 ±0.15                2.35  2.65   mm    16 faces
11  Position          8X ⌖ | ⌀0.75 | A | B | C      0     0.75   mm    16 faces
...
36  Position          ⌖ | ⌀0.8 | D | E-F-G Ⓜ        0     0.8    mm    4 faces
49  Position          2X ⌖ | ⌀0.8 Ⓟ3.2 | D | E | B  0     0.8    mm    supplemental geometry

Export for Excel (; and decimal comma for German Excel) or JSON:

cadtokens chars part.stp -f csv -o part_merkmale.csv --delimiter ";" --decimal-comma
cadtokens chars part.stp -f json -o part_characteristics.json
cadtokens chars part.stp --toleranced-only     # skip basic / general-tolerance dims

ISO fits are resolved to limits per ISO 286-1 (⌀3.5 G6 (+0.012/+0.004) → 3.504–3.512); classes outside the tables are flagged, never guessed.

Ballooned inspection report (PDF)

cadtokens report part.stp                  # → part_inspection.pdf

Page 1: isometric wireframe of the part with numbered balloons pointing at each characteristic's feature, plus any data-quality warnings. Following pages: the characteristic table with feature control frames drawn as real GD&T symbols, numeric limits, faces, and empty Measured / OK columns for the inspector. Pure Python, no fonts or CAD kernel needed.

When the file itself is inconsistent, you are told instead of getting a silently wrong list:

1 data-quality warning(s):
  ! Mixed length units in PMI: tolerances use ['mm'], dimensions use ['in'].
    The file may be exported inconsistently — check values against the drawing.

3. MCP server — let AI agents read GD&T

Any MCP client (Claude Code, Claude Desktop, local agents) can ask "which features have a position tolerance tighter than 0.1 mm, and to which datums?" and get exact answers from the file, not a guess from a drawing image.

pip install -e ".[mcp]"
claude mcp add cadtokens -- cadtokens mcp

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "cadtokens": { "command": "cadtokens", "args": ["mcp"] } } }

Related MCP server: cad-mcp-server

Validation

Tested against the 17 AP242 files of the NIST MBE PMI test models (CTC, FTC, STC — AP242 editions 1–3, mm and inch, files from several CAD systems):

python scripts/fetch_nist.py      # downloads the NIST models (sha256-pinned)
pytest

Not yet supported

Be aware of these before using the list for a real inspection:

• ISO 286 fits beyond 500 mm or outside C–S / c–s are flagged, not computed

• Graphical-only PMI (no semantic representation) cannot be read; such dimensions are flagged

• Datum targets, thread designations (M3x0.5-6g), surface texture, notes

• Assemblies (PMI is read per file, without assembly transforms)

• Very large files: memory use is roughly 45× file size

• The report view is a wireframe (no hidden-line removal); balloons on whole-part or supplemental-geometry characteristics appear in the table only

Installation

git clone https://github.com/giltsch/cadtokens.git
cd cadtokens
pip install -e .              # core: no dependencies, Python 3.10–3.15
pip install -e ".[mcp]"       # + MCP server
pip install -e ".[dev]"       # + tests

Python API

import cadtokens
from cadtokens.characteristics import build_characteristics, to_csv

pmi = cadtokens.extract_pmi(cadtokens.load("part.stp"))

for t in pmi.tolerances:
    print(t.tolerance_type, t.value, t.unit, t.datum_labels, t.face_ids)

for w in pmi.warnings:
    print("!", w)

chars = build_characteristics(pmi)
to_csv(chars, "part_characteristics.csv")

The parser also exposes the STEP entity graph, B-Rep topology (cadtokens.BRepExtractor), a STEP editor and a PMI writer (cadtokens.PMIWriter) for attaching tolerances to faces.

Citing

If you use cadtokens in research, please cite it — see CITATION.cff (GitHub shows a "Cite this repository" button).

Contributing

Bug reports with shareable STEP files are the most valuable contribution — see CONTRIBUTING.md. Never attach customer or export-controlled data.

Earlier experiments (LLM chat over OCC geometry, a GNN face classifier) were removed to keep the project focused; they are preserved under the git tag archive/chat-gnn.

License

Apache-2.0 — see LICENSE and NOTICE.