stepscribe

Give any LLM X-ray vision into your CAD model. stepscribe reads a STEP file and writes an LLM context pack: exact measurements, holes, patterns, standard parts, assembly relationships and labelled images, all computed deterministically and offline (no AI model, no network).

Install

python -m pip install stepscribe-cad

From a checkout: python -m pip install -e ".[dev,mcp]". Needs Python 3.11+ (3.12 recommended). The OpenCASCADE bindings come from cadquery-ocp. The command is stepscribe.

Quickstart

stepscribe export robot.step -o out                # portable files for any AI: FULL, COMPACT, SMALL, chat bundle, zip
stepscribe pack robot.step -o out --material alu   # the multi-file context pack
stepscribe pack robots_folder/ -o out --jobs 4     # a whole folder, with index.md
stepscribe analyze robot.step -o out               # report.json only
stepscribe render robot.step --view exploded -o exploded.png
stepscribe section robot.step --plane "z=12.5"
stepscribe init-context                            # template for design intent / materials

Large files can take minutes. Progress shows an estimated time remaining that improves as parts finish; analysis quality is never reduced to go faster.

Use with AI tools

Every route ends with the same files, so you always walk away with something you own.

1. Any AI, nothing to install on its side

stepscribe export robot.step -o out

This writes out/robot_stepscribe/ and out/robot_stepscribe.zip:

Paste a Markdown file into the chat, or upload chat_bundle/. MANIFEST.md lists every file with sizes and token estimates. Exporting an unchanged file again reuses the finished export.

2. Claude Code plugin

/plugin marketplace add idris900323/stepscribe
/plugin install stepscribe@stepscribe

Adds the skill, the MCP server, a mechanical-reviewer agent and three commands: /stepscribe:export <file>, /stepscribe:interview <file> and /stepscribe:review <file>. Everything happens in the chat: progress updates for long runs, the designer interview one question at a time, images inline, results as files. The plugin starts stepscribe mcp, so install the package first (pip install "stepscribe-cad[mcp]"); to run it without a prior install, change plugins/stepscribe/.mcp.json to uvx --from "stepscribe-cad[mcp]" stepscribe mcp.

3. Agent Skill

skills/stepscribe/ follows the open Agent Skills format. Upload dist/stepscribe-skill.zip (from a release, or build it with python scripts/sync_skills.py) where custom skills are supported, or copy the folder into your skills directory. The skill needs an environment where stepscribe can be installed; it works best in Claude Code. Hosted code-execution sandboxes may not allow installing it, so use the export files there.

4. GitHub Copilot

The skill is in .github/skills/stepscribe/. For the MCP server, add this to .vscode/mcp.json:

{
  "servers": {
    "stepscribe": { "type": "stdio", "command": "stepscribe", "args": ["mcp"] }
  }
}

5. Other MCP clients

python -m pip install "stepscribe-cad[mcp]"
stepscribe mcp

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

Tools: start_analysis, get_job_status, export_pack (for big assemblies that outlast a client's call timeout), get_overview, get_part, list_holes, list_cutouts, get_relations, measure_distance, section, render_view, find_parts, get_shopping_list, diff, get_questions, submit_answer. Pass the absolute path of a STEP file. Images come back as PNG content of at most 1200 px; results are cached by file hash.

What is in a pack

00_READ_ME_FIRST.md, 01_overview.md, 02_assembly.md, 03_parts/*.md, 04_design_context.md (if given), 05_understanding.md, context_pack.md (single file under a token budget), images/, data/report.json.

Statements without a prefix are measured facts. Statements starting with Likely: are inferences with a confidence and evidence.

How it works

flowchart LR
    A[STEP file] --> B[Read: names, tree, units]
    B --> C[Measure: faces, holes, features]
    C --> D[Interpret: shape class, standards, mounts, bearings]
    D --> E[Assembly: contacts, joints, relations]
    E --> F[Context pack + labelled images + report.json]
    F --> G[Your LLM: questions, reviews]

Layers 1 and 2 (measure, interpret) are pure Python on the OpenCASCADE kernel: deterministic, offline, explainable. Layer 3 (judging the design) is done by your own LLM, outside this tool.

Understanding layer (how the design works)

Beyond measuring, stepscribe forms rule-based hypotheses about a design (no model, no network). Each one has a confidence and evidence that points to part, joint and contact IDs; statements start with "Likely:". The results are in 05_understanding.md and in the understanding section of report.json:

• Structure and process: ribs, gussets, steps, bends, lightening cutouts (and, for every part, recesses, windows and edge notches with sizes and positions), symmetry and mirror pairs, and the likely manufacturing process of each part (FDM, CNC, laser, sheet metal...).
• Motion: rigid links, the ground link, revolute and prismatic joints with their axes (servo horns included), degrees of freedom, a Mermaid diagram, and mechanisms (direct drive, gear pairs with ratio and module, GT2 belts, lead screws). --check-motion moves each joint and reports its free range and what blocks it.
• Risks: load paths, weak spots (edge distance, thin walls, single fasteners, cantilevers, short screws, tipping) with numbers and a suggestion, and a stability check (centre of mass against the support polygon).
• Purpose: a likely role for every part, and a short design summary.
• Questions: what geometry cannot tell (material, purpose, payload, what drives a joint), asked in order of value.

stepscribe pack robot.step --check-motion          # adds 05_understanding.md and joint arrows on the images
stepscribe kinematics robot.step                   # links, joints, mechanisms, Mermaid diagram
stepscribe weak-spots robot.step --material alu    # the risk table
stepscribe questions robot.step                    # lists questions, adds an answers: stub to design_context.yaml
stepscribe questions robot.step --json             # the same as JSON, for scripts
stepscribe answer robot.step --id QDC283C --value pla   # answer one question (also --skip, --not-sure, --undo)
stepscribe interview robot.step                    # answer them in the terminal; the pack is rebuilt

Answers apply in well under a second (the STEP file is not read again) and are saved in design_context.yaml, with a lock and an atomic replace so several writers can share it. The pack marks them "Confirmed by designer" or "Designer unsure", and an answer that contradicts the geometry is accepted with a visible conflict note. scripts/eval_understanding.py scores the layer against labels you write by hand (tests/real_labels/example.yaml).

Standalone web page

stepscribe ui                  # local page: upload, progress with ETA, tabs, image viewer, interview, zip
stepscribe ui robot.step       # same, with a file preloaded

This is separate from the AI integrations above: it runs only when you start it, is reachable from this computer only, and nothing in the MCP server, the skill or the plugin ever starts it. Large files can be read in place by typing their path.

Optional: talk to a model directly

python -m pip install "stepscribe-cad[llm]"
export STEPSCRIBE_LLM_BASE_URL=http://localhost:11434   # Ollama, or any OpenAI-compatible /v1 URL
export STEPSCRIBE_LLM_MODEL=llama3.1:8b
stepscribe ask robot.step "What is the motor attached to?"
stepscribe eval robot.step      # factual questions scored against report.json

There is no default endpoint and no key is stored on disk (STEPSCRIBE_LLM_API_KEY is read from the environment). Set STEPSCRIBE_LLM_VISION=1 to also send the images.

Honest limitations

• STEP files rarely carry thread data, material or tolerances; the pack says so and only infers.
• Large assemblies take minutes (contact detection between complex solids is the slow part); a live ETA is shown. Assemblies of dozens of heavy parts can take much longer than that.
• Assemblies that only reference other STEP files cannot be read (a clear error says so).
• Knowledge tables (screws, motors, bearings, extrusions) are deliberately small and each entry cites its source; unsure values are left out.
• No hidden-line (HLR) drawings yet.
• Not yet checked against a CAD system for accuracy; verify important numbers there.

Built with help from AI tools

Much of this code was written with AI assistance and then tested against generated ground-truth fixtures and real open-source robot files. Please verify important numbers against your CAD system.

Project docs

• CHANGELOG.md, CONTRIBUTING.md, docs/prelaunch_checklist.md, docs/plugin_testing.md
• examples/README.md (where to get open robot STEP files)

License

stepscribe is free and open source under the GNU AGPL-3.0. You may use, modify and share it under those terms, including the duty to publish source code when you distribute it or offer it as a network service. The analysis output you generate belongs to you. Companies that want to embed it in closed-source products or run a closed hosted service can get a commercial license: see COMMERCIAL.md. To contribute, read CONTRIBUTING.md and the CLA. Third-party dependencies keep their own licenses.

"stepscribe" and its logo are trademarks of the maintainer; see TRADEMARKS.md.