How to Search for Off-the-Shelf STEP Components with the step-parts Skill

The step-parts skill provides a deterministic command-line interface to query the step.parts catalog, download verified STEP files, and automatically launch them in the CAD viewer for immediate inspection.

The text-to-cad repository implements a modular, skill-driven architecture for generating CAD models from natural language. By leveraging the step-parts skill, engineers can programmatically discover and import manufacturer-verified STEP files—such as fasteners, bearings, and motors—directly into their models/ directory for seamless assembly integration.

What Is the step-parts Skill?

The step-parts skill is a self-contained module under skills/step-parts/ that abstracts the step.parts REST API into reproducible, testable commands. It serves as the gateway to the public step.parts catalog, enabling automatic discovery of real-world mechanical components.

Unlike ad-hoc scripts, this skill bundles its runtime logic, documentation, and API references together. It connects to https://api.step.parts to execute queries and handles result disambiguation, SHA-256 checksum verification, and automatic hand-off to the CAD viewer through the $cad-viewer environment variable.

Repository Architecture

The text-to-cad repository organizes functionality into isolated layers that keep skills interoperable yet independent:

• Skill Registry: Each skill includes a SKILL.md manifest describing its purpose and interface.
• Skill Implementations: Self-contained logic under skills/*/ that never imports code from sibling skills.
• Shared Packages: Common utilities like CAD rendering live in packages/cadjs/, packages/implicitjs/, and packages/cadpy/.
• CAD Viewer: The web-based viewer in viewer/ receives files via the $cad-viewer command.
• Models Store: Downloaded artifacts are stored in models/ and tracked via Git LFS.

How the step-parts Skill Works

The skill executes a five-phase pipeline defined in skills/step-parts/SKILL.md to ensure reliable component retrieval:

1. Interpret the request – Parses natural language queries into API parameters (q, category, family).
2. Query the API – Calls GET /v1/parts on the step.parts service (documented in references/step-parts-api.md).
3. Disambiguate results – When multiple candidates match, presents top results showing id, name, standard, and key attributes.
4. Download and verify – Fetches the stepUrl, verifies SHA-256 checksums, and writes files to models/.
5. Viewer hand-off – Automatically invokes $cad-viewer to render the downloaded component.

Searching and Downloading STEP Files

Command-Line Search

The scripts/download_step_part.py script provides a deterministic CLI for searching and downloading. To search and download in one operation:

python scripts/download_step_part.py "M3 socket head 12" --download

This command searches the catalog, selects the best match, downloads the STEP file, verifies the checksum, and outputs a JSON payload containing the local file path and source URLs.

Programmatic Usage in Python

You can invoke the downloader from Python using subprocess calls to first search, then download by specific ID:

from pathlib import Path
import json, subprocess

def find_step_part(query: str) -> Path:
    # Run the bundled downloader in "search-only" mode

    result = subprocess.check_output([
        "python", "scripts/download_step_part.py",
        query, "--json"
    ], text=True)
    data = json.loads(result)
    # Assume the first hit is acceptable

    part_id = data["items"][0]["id"]
    # Download the STEP file

    download = subprocess.check_output([
        "python", "scripts/download_step_part.py",
        f"--id={part_id}", "--download", "--json"
    ], text=True)
    download_info = json.loads(download)
    return Path(download_info["filePath"])

step_file = find_step_part("bearing 608zz")
print(f"Saved STEP file: {step_file}")

Visualizing Components in the CAD Viewer

After downloading, launch the viewer to inspect the geometry immediately:

cad-viewer open --file models/M3_socket_head_12.step

The $cad-viewer command starts a new viewer instance or connects to an existing one, rendering the STEP file using the rendering utilities defined in packages/cadjs/src/lib/stepRenderAssetClient.js.

Key Implementation Files

File	Purpose
skills/step-parts/SKILL.md	Human-readable skill manifest with workflow and API reference
scripts/download_step_part.py	Deterministic CLI implementing search, download, and checksum verification
references/step-parts-api.md	OpenAPI specification for the step.parts service
packages/cadjs/src/lib/stepRenderAssetClient.js	JavaScript helper used by the viewer to render STEP assets
models/	LFS-tracked directory storing downloaded STEP and STL files
viewer/README.md	Configuration and launch instructions for the CAD viewer

Summary

• The step-parts skill provides deterministic access to the step.parts catalog through scripts/download_step_part.py.
• It verifies downloaded files using SHA-256 checksums before writing to models/.
• The skill integrates seamlessly with the CAD viewer via the $cad-viewer environment variable.
• All API logic is documented in references/step-parts-api.md and encapsulated to avoid cross-skill dependencies.
• Components are searchable via CLI or Python subprocess calls, returning structured JSON for programmatic use.

Frequently Asked Questions

What types of components can I search for with the step-parts skill?

The skill supports any component indexed by the step.parts catalog, including standardized mechanical parts like screws, bolts, bearings, motors, gears, and connectors. The API accepts queries across multiple attribute fields including category, family, and standard identifiers.

How does the step-parts skill ensure file integrity?

When downloading via scripts/download_step_part.py, the skill calculates the SHA-256 hash of the retrieved file and compares it against the checksum provided by the step.parts API. If verification fails, the file is rejected and the operation exits with an error code, ensuring only validated geometry enters your models/ directory.

Can I use the step-parts skill independently of other text-to-cad features?

Yes. While designed for the text-to-cad ecosystem, the step-parts skill is self-contained under skills/step-parts/ and relies only on shared packages in packages/. You can execute scripts/download_step_part.py as a standalone utility provided Python dependencies are met, though the automatic viewer integration requires the $cad-viewer environment variable to be set.

Where can I find the API specification for step.parts?

The complete OpenAPI specification is documented in references/step-parts-api.md within the step-parts skill directory. This file details the GET /v1/parts endpoint, query parameters, response schemas, and authentication requirements for direct API access beyond the skill abstraction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}