Skip to main content
Glama
geomwright

geomwright

by kostia-egik

Geomwright

English guides · Русская документация

Local-first CAD automation for KOMPAS-3D, exposed as an MCP server and a small browser-based Studio. Geomwright lets an AI agent or a local operator inspect a model, plan a change, execute a bounded operation, and verify the result without turning KOMPAS into an uncontrolled scripting target.

Geomwright is an independent project. It is not affiliated with or endorsed by ASCON or the KOMPAS-3D product team.

What you can do

  • inspect KOMPAS documents, model trees, sketches, features, dimensions, and constraints;

  • create and edit selected sketch and feature entities with explicit targets;

  • inspect and measure finished bodies and face shapes, including user-built parts and assembly components, independently of construction history;

  • preview and build supported parametric parts and spring families;

  • preview and build managed V-belt, Poly-V, flat-belt, timing-belt, selected roller/bush-chain transmission geometry, an external cylindrical gear (spur or helical) with a nominal rack-generated profile, and an internal ring gear with an explicit blank outside diameter, and a straight bevel wheel with a nominal Tredgold profile;

  • preview and build straight-sided spline shafts and hubs per ГОСТ 1139-80 with the standard size catalog, centering methods, and ГОСТ 25346 fits;

  • create specifications, relink assembly paths, run quality checks, and export safe working copies;

  • use Geomwright Studio to preview transmission geometry and edit recognized managed blocks, or calculate and build one create-only cam without shaft/hub/bore. Cam recipes persist in new models: restore a Studio form for a new build or read the recipe through MCP inspect_cam; engineering limits do not inherit CAD slack.

The public MCP surface is discovered at runtime. Call get_mcp_tool_catalog from an MCP client instead of relying on an unversioned list copied into a prompt.

Related MCP server: solidworks-mcp

CAD work modes

CAD defaults to interactive: attach to a selected visible KOMPAS window, retain documents, and never create a substitute instance. hidden is an explicit alternative that requires a separately created, proven-owned process; it must not hide documents inside the user's session. Mode changes and window rebinding are explicit and cannot bypass quarantine. See mode selection and visibility for the operational contract and live-verification limits. Visible API work does not guarantee animation of every sketch edit.

Current status

Version 0.1.0 is an alpha release. The core session, document, composition, specification, relinking, and batch operations are the most stable parts. The parametric, spring, sketch-write, and transmission families are usable only within the scope stated by their contracts and live verification evidence.

Area

Status

Notes

Session and document lifecycle

Stable

Open, inspect, save, export, and close explicit documents

Composition, specifications, relinking, quality

Stable

Preview/apply workflows with bounded changes

Sketch and feature runtime

Experimental

Low-level tools; inspect before writing

Finished model geometry

Experimental, live-verified

Read-only bodies, faces, edges, shape snapshots and explicit geometry measurements

Parametric parts and springs

Experimental

Family-specific parameters and verification

Geomwright Studio

Experimental

Local UI; no arbitrary-body write path

Cylindrical gear

Experimental, live-verified

External spur/helical gear; ГОСТ 13755-2015, ГОСТ 9587-81, ГОСТ Р 50531-93 and ISO 53:1998 contours; nominal preview, create-only managed part, MCP tools

Internal gear

Experimental, live-verified

Internal spur/helical ring gear; explicit blank outside diameter, ГОСТ 19274-73 nominal geometry, create-only managed part, MCP tools

Straight bevel gear

Experimental

Nominal Tredgold projection, create-only dish blank and saved recipe; see the family contract for recorded live cases and limits

Straight-sided splines

Experimental, live-verified

ГОСТ 1139-80 light/medium/heavy catalog, exact end profile and ГОСТ 25346 fits; create-only managed shaft and hub parts, Studio modules and MCP tools

Cam profiles

Experimental

Shared Studio/MCP create-only build, native curve/contact and solid readback

Silent-chain sprockets

Experimental, live-verified

Shared Studio/MCP calculation and new-part creation; solid blank, DIN NURBS, saved recipe inspection

Native KOMPAS module inspection

Research-only

Disabled by default; explicit opt-in for local investigation

An experimental status is a contract boundary, not a promise that every catalog entry or CAD combination is supported. Missing standard data and failed verification stop the operation before an unsafe write where possible.

Requirements

  • Windows;

  • KOMPAS-3D v23 with its runtime components installed;

  • Python 3.11 or newer for the host;

  • an MCP-capable client for the agent interface.

The host Python and the KOMPAS bridge can use separate interpreters. The bridge needs a modern Windows Python with pywin32; the old bundled Python 3.2 cannot run the current source. Prefer a standard Python installation for the CAD runtime.

Install

From PowerShell in a clone:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[ui]"

Configure the CAD interpreter before starting Studio or MCP. If the project interpreter is a standard Windows Python, it can run both host and bridge:

.\.venv\Scripts\python.exe -m pip install pywin32
$env:KOMPAS_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Path
$env:KOMPAS_REQUIRE_VISIBLE = "1"

Alternatively point KOMPAS_PYTHON at a separate Python with pywin32 installed. Without an explicit setting, a source checkout prefers its existing .venv/cad-bridge/Scripts/python.exe; installed packages still need a compatible runtime configured explicitly if the KOMPAS SDK fallback is too old. Studio does not inherit environment settings stored only in an MCP client's configuration. Production bridge calls first compile the selected sources and check pywin32 in a bounded, COM-free preflight. CAD_RUNTIME_INVALID identifies a local setup failure before CAD launch; it does not by itself quarantine the session. Use an actual interpreter path rather than a bare execution alias. KOMPAS_REQUIRE_VISIBLE=1 makes MCP attach to the already running visible KOMPAS instead of starting a COM server. Cam creation requires this running session. For an MCP client, put these variables in the local server's environment configuration so a restart preserves them.

The UI dependency group is optional. For MCP-only use:

.\.venv\Scripts\python.exe -m pip install -e .

The package currently requires mcp>=1.27,<2. Installing the package resolves this dependency; do not substitute MCP 2.x without a compatibility migration. For setup checks and common failures, see English / Русский.

Research-only native-module tools are intentionally absent from the default MCP session. Enable them only in a disposable local investigation:

$env:GEOMWRIGHT_ENABLE_RESEARCH_TOOLS = "1"
.\.venv\Scripts\python.exe -m geomwright

They are not covered by the stable product contract and can inspect installed KOMPAS modules or launch explicitly requested commands.

Run Studio

The easiest Windows path is:

.\start-geomwright-studio.cmd

Or run it in a terminal you control (foreground; keep that terminal open):

.\.venv\Scripts\python.exe -m geomwright.studio --port 8765

For an agent or an unattended session, use the bounded background launcher:

.\.venv\Scripts\python.exe -m geomwright.studio --background --no-browser --startup-timeout 15

It launches without a console window, closes stdin, redirects output to unique log files, checks the new instance's /health, and returns its URL and PIDs. Logs default to local Geomwright state (%LOCALAPPDATA%\Geomwright\studio on Windows); override with --log-dir. Startup failure reports the stderr path and stops only the newly launched process tree. Do not use PowerShell Start-Process to launch Studio through an agent terminal tool.

For potentially blocking finite commands, use the independent watchdog:

.\.venv\Scripts\python.exe scripts/run_bounded.py --timeout 30 -- .\.venv\Scripts\python.exe -m pytest tests/test_bridge_runner.py -q

The watchdog returns exit code 124 on timeout, closes stdin, captures bounded output through files, and stops owned descendants. On Windows it uses a Job Object plus cleanup of the launcher tree; it does not rely on the terminal tool's timeout message. Never wrap Studio --background or another persistent server in this watchdog: it cleans descendants even when the command finishes normally.

Studio opens http://127.0.0.1:8765 unless --no-browser is supplied. Start KOMPAS first and keep it visible: Studio attaches to the already running KOMPAS instance and never creates a hidden substitute session. It previews geometry before a CAD job and only edits recognized managed blocks.

Run the MCP server

.\.venv\Scripts\python.exe -m geomwright

For an MCP client, use the Python executable inside that clone. The tracked opencode.example.json shows the portable shape:

{
  "mcp": {
    "geomwright": {
      "type": "local",
      "command": [
        "C:\\path\\to\\geomwright\\.venv\\Scripts\\python.exe",
        "-m",
        "geomwright"
      ],
      "enabled": true,
      "environment": {
        "KOMPAS_PYTHON": "C:\\path\\to\\geomwright\\.venv\\Scripts\\python.exe",
        "KOMPAS_REQUIRE_VISIBLE": "1"
      },
      "timeout": 600000
    }
  }
}

Do not commit a machine-specific copy of this file. The legacy commands kompas-mcp and kompas-mechanics-ui, and the kompas_mcp import namespace, remain as compatibility aliases. New integrations should use geomwright and geomwright.kompas.

CAD module pilot: MCP and CLI

The shared contract exposes gear_spur (external cylindrical), gear_internal (internal cylindrical), gear_bevel (straight bevel), chain_sprocket (roller/bush chain sprocket), cam (direct or roller-rocker cam lobe) and silent_chain_sprocket (GOST and DIN/ASME open reconstructions), plus the five managed pulley families: v_belt, poly_v, flat_belt, timing_trapezoidal, timing_curvilinear. In MCP, call get_cad_module_contract() (or module_id: null) to list descriptors; get_cad_module_contract(module_id="gear_spur") returns the input/result schemas, defaults, examples, units/frame and limitations. Use the existing list_gear_standards tool to select rack standards and modifications. For sprockets, use list_chain_profiles; the catalog is not repeated in module results. Restart the MCP client after upgrading so a fresh session discovers get_cad_module_contract and run_cad_module.

The CLI uses the same dispatcher without an MCP server:

python -m geomwright.model list
python -m geomwright.model describe gear_spur
python -m geomwright.model run request.json

The installed geomwright-model command accepts the same arguments; run - reads a JSON request from stdin. Stdout is JSON. Exit codes are 0 for success, 1 for operation failure, and 2 for an invalid file/envelope. CAD actions still require the normal KOMPAS environment.

Example request.json (also the request argument of run_cad_module):

{
  "contract_version": 1,
  "module_id": "gear_spur",
  "action": "preview",
  "parameters": {"module_mm": 2, "tooth_count": 24, "face_width_mm": 20}
}

For a two-row sprocket, use module_id: "chain_sprocket" with parameters such as {"designation":"ISO_08B_2","chain_type":"roller","tooth_count":25,"row_count":2}. The row count must match a multi-row designation, and the selected catalog entry must contain the required axial data. Tooth width is catalog-derived, not a free face_width_mm field. gost_profile_variant selects offset or non_offset construction for both ISO and GOST chains.

For cam, parameters contains the typed calculation request, plus width, rotation_deg and tolerance, matching the existing create_cam inputs. Preview/plan use the same strict CAD preflight at 10 samples per cam degree and omit curve and motion-chart arrays. There is no standard catalog for this engineering module. See the cam contract.

silent_chain_sprocket reuses its existing selection schema and list_silent_chain_profiles catalog. Its designation and physical tooth count are required, so discovery defaults are partial, not a complete request. Preview returns data.summary.completion; plan/create return error.code: "INPUT_REQUIRED" with data.completion until required engineering inputs are supplied explicitly. Suggestions are not silently accepted. Source/reconstruction warnings are retained in plan/create and inspection (data.source_summary). The rim occupies positive global X, [0, functional_width_mm], unlike the gear/cam negative-X interval. Inspection has verification.stored_verified: null, not a persisted geometry stamp.

Pulley inputs reuse the existing family schemas. v_belt additionally accepts top_edge_fillet_radius and include_standard_top_edge_fillet in parameters. Use list_v_belt_profiles or list_poly_v_profiles for selection; timing profile choices are in the schema, and custom dimensions require designation: "CUSTOM". Poly-V currently supports catalog geometry only. Flat crown height is explicit circular-arc geometry, not a standards-derived default. V/Poly-V/flat rims occupy positive X; timing pulleys occupy [-face_width, 0]. Create verifies one positive-volume solid, bounds and ownership; timing creation also compares repeated removed material with source-cut volume times tooth count. New pulley creation stores a versioned checksummed full recipe, including finishing and custom-source inputs. Inspect returns that creation recipe, not a geometry audit; detected driving-input changes invalidate it. Old blocks lacking a full recipe remain recognizable with parameters: null. Existing dedicated apply and Studio editing paths remain separate from this create-only interface.

module_id and action are required; actions are preview, plan, create and inspect. Defaults: contract_version: 1, parameters: {}, name: null, confirm_write: false, visible: true; an omitted/null name uses the selected module's default_name (unchanged for gear_spur). document_id is optional except for inspect, which requires the explicit exact opened document ID. parameters is validated by the selected family's schema; runtime flags belong in the envelope, never inside parameters.

create requires confirm_write: true. Check descriptor creation_policy: most modules create a new unsaved part; legacy compression springs retain their saved construction/finalization path described below. inspect recognizes the saved recipe; it is not a fresh geometry audit. To recreate, require data.recreatable: true, then pass its returned parameters to a new create request. Without a recoverable recipe, parameters is null; do not substitute {}, which would select a default part. For bevel gears, face width is along the pitch cone; axial extents come from the plan/readback, not [-face_width_mm, 0]. The module contract describes this frame. There is no update/apply, general composition or new Studio block in this pilot.

The bounded result contains contract_version, module_id, action, ok, stage, executed, verified, parameters, data, verification, error and partial_result. executed is false/true, or null when execution is unknown after runtime failure. verified is false for preview/plan/inspect; create reports true only after actual verification. See the gear contract. data.geometry contains calculated geometry; data.body contains actual CAD readback. data.owned_references identifies the recognized root operations. For sprocket inspection, verification.stored_verified is null: the saved block has no geometry-verification stamp. Creation includes the existing transition-constraint check in verification.transition_constraint, including any solver-state warning that requires UI confirmation.

Legacy compression-spring integration (experimental)

compression_spring adds a typed interface over the existing cylinder, two-zone variable-pitch and conical generators (variant: cylindrical|two_zone|conical). Use get_cad_module_contract("compression_spring") for the schema and restrictions; wire diameter and geometry are explicit, not defaulted. Exactly one cylinder diameter representation is accepted; cones use small/large mean diameters. The old create_compression_spring, scenario and catalog tools remain available. Arbitrary legacy placement/workflow expressions are not part of the new schema.

Unlike the recent rim modules, creation_policy: saved_unique_export_then_open creates a unique .m3d in KOMPAS_EXPORT_DIR, runs the established post-save anchor binding, and opens the saved result. The response has saved: true, closed: false and its exact path in data.document. This is not an unsaved-create promise. Checks cover native rebuild, positive single-solid volume, radial envelope, owned profile/sweep roots and volume preservation through saving/finalization. The axis is global X. Inputs and bounds survive a further reopen. CSPR_RECIPE_* stores a versioned checksummed creation recipe, not driving formulas or a geometry-verification stamp. Inspect does not certify manual edits.

Live control cases cover an open cylinder, grounded right/left two-zone cylinders (including left-hand start phase30), and cones with constant pitch/constant angle. The left-hand segment phase mismatch is fixed; both native fillets now return their edges. end_pitch_gap defaults to0.01 mm in the shared module: end pitch is wire diameter plus this axial increment, without reducing the wire diameter. EG1 drives derived EP1; end spans, grinding planes and length formulas use it. Legacy calls without this field and earlier recipes retain zero gap. Explicit zero is not clamped: invalid contact returns CAD_SELF_INTERSECTION before saving, even with a positive cached volume. The increment is not a certified minimum surface clearance. Both hands and asymmetric ends pass save/reopen; changing EG1 to0.02 retains native validity and wire diameter. height and legacy free_length mean centreline span; standard_length means the legacy physical end-to-end length. These length inputs are mutually exclusive. No new Studio spring editor is added; this is a shared-generator integration, not a complete three-component Studio module.

extension_spring now connects the existing eight engineering hook forms to the same shared interface. It requires wire/outer diameter and turns; gap >= minimum_gap > 0 is explicit and never silently increased. Creation uses a unique saved export, verifies the native coil and valid solid, and restores the ESPR_RECIPE_* inputs after reopening. Independent left_hook_type and right_hook_type include the finalized self-wrapping and bent-ring families; historical spike names are retained. Current runtime verification limits are explicit in the family contract. No new Studio block is added. See the extension-spring contract.

torsion_spring likewise exposes the existing tangent, radial and axial-transition leg generator through the common interface. It retains separate TSPR_RECIPE_* inputs and verifies native coil/leg geometry and save/reopen. Existing legacy tools are unchanged; no new Studio block or torque/strength certification is added. See the torsion-spring contract.

disc_spring connects the legacy normal-thickness conical-ring generator to the same create-only interface, with DSPR_RECIPE_*, native diameter/bounds checks, analytical volume comparison and save/reopen verification. Legacy radius/height variable edits are not reliably driving; recreate from inputs instead. The free_height alias is not the finished axial span. See the disc-spring contract.

diaphragm_spring reuses the finalized flat/single/S-bend workflow with radial slots, circle/oval reliefs and a two-source circular pattern. The common interface checks repeated material removal, owned roots and recipe/volume persistence using DIAPR_RECIPE_*. Per-sketch constraint states are returned after reopening; complete saved-sketch definition and in-place driving edits are not certified. See the diaphragm-spring contract.

stepped_shaft connects the existing full rotational-body constructor, with per-step native radius/axial-span checks, analytical volume, a fully defined creation profile and saved SHFT_RECIPE_*. It is create-only and contains no operations on an external body. See the stepped-shaft contract. The separate construction-chain interface supports explicit axial-bore, face-groove and bolt-circle cuts on supported chain carriers, plus terminal external metric threads on a complete exposed +X cylinder. Arbitrary external-body processing and broader thread modes remain deferred; see the chain contract.

external_conical_step adds the existing standalone frustum with five explicit definition modes. Native verification checks both trimmed end radii, axial bounds, analytical volume and the fully defined reopened profile. The original input mode is restored from ECON_RECIPE_*; resolved diameter/length variables drive CAD. See the external-cone contract.

Construction chains and model images

get_construction_chain_contract discovers the current MCP-only composition contract. run_construction_chain supports plan|create|inspect|rebuild|continue: create/rebuild make a new saved part; inspect recognizes its recipe, not fresh geometry. Continue requires the exact opened saved chain ID, confirm_write=true and only new steps, audits the immutable prefix/current geometry, then saves the same file. Old-step edits and arbitrary standalone models are refused.

Stages A–C (shaft/cone/bore/groove) and D (initial gear_spur, cylindrical hub, continuous bore and saved-chain continuation) are live-verified within the documented limits. Stage E now includes regular polygon sections (own/create and own/add), one/two-flat sections with an inscribed-core carrier, and explicit input/remove bolt-circle holes. Actual planes/cylinders, pattern roots and saved-chain continuation are verified. An initial straight_spline shaft now reuses the GOST 1139-80 numeric family plan, with +X cylindrical continuation, core cuts, native tooth-zone preservation and same-file continue/reopen checks. Terminal input/remove splines on an explicit uncut +X cylinder now support bounded working length with smooth margins at both ends, without chamfers/runout; create, continue, fresh inspect/reopen and source-preserving rebuild are live-verified. Terminal metric threads are also available within their documented limits. Terminal body=hub splines now cut the entire explicit through bore of one cylindrical stock, using the corrected nominal counterpart profile and inherited outside diameter; create/continue/inspect/rebuild/reopen are verified. Explicit exit_mode=blind also supports a shorter cut from open entry in a flat-bottom bore, with positive smooth tail and stock behind the bottom; lifecycle and native length20→22→20 checks passed. Arbitrary partial spans, tool runout, broader input-stock processing and chain Studio integration remain pending. See English examples and limits / русские примеры и ограничения.

For visual review, use export_model_png with an exact open document_id, optional new output_path, view (default current), resolution_dpi=150 and fit=true. For example: {"document_id":"<exact open ID>","view":"left"}. Native views follow KOMPAS orientation; left may be a side view for global-X parts. Export writes an actual PNG without rebuilding/editing geometry, restores and checks matrix/scale and previous active document, but does not certify exact screen pan. Existing files are never overwritten; omitted paths get UUID filenames. See PNG export and supported views.

First safe workflow

  1. Call get_mcp_tool_catalog and choose a category whose status matches the task.

  2. Call get_session_state and list_documents; always name the target document explicitly.

  3. Use inspection, preview, and preflight tools before a write.

  4. Follow Plan → Execute → Verify → Correct. A successful COM Update() is not, by itself, proof that geometry or direction is correct.

  5. Save and reopen a model when the workflow contract requires persistence evidence. Keep generated files under ignored local output directories.

For sketch work, begin with inspect_sketch_full. For a parametric family, begin with its preview operation and then read the family contract in docs/.

Repository map

src/geomwright/                 public application namespace and Studio
src/kompas_mcp/                 KOMPAS implementation and compatibility APIs
bridge/kompas_bridge.py         KOMPAS-side COM bridge
rules/                          tracked runtime rule data
docs/                           current user and maintainer contracts
sample/                         small runnable examples and request payloads
tests/                          deterministic host-side and contract tests
experiments/spikes/              ignored local quarantine for unfinished work

The root bridge and packaged bridge copy must remain byte-identical. Generated CAD files, live readback dumps, local configuration, and disposable probes are not part of the public repository.

Documentation

License

Geomwright is released under the MIT License.

See CONTRIBUTING.md for development boundaries and SECURITY.md for safe local operation and vulnerability reports.

Available Tools

118 tools
analyze_naming_issuesC

Analyze naming issues in the selected or active document.

Inputs: rules_path, document_id.

analyze_spec_issuesC

Analyze basic specification issues in the selected or active document.

Inputs: rules_path, document_id.

apply_changesetC

Apply a prepared changeset to writable fields only.

Inputs: changes (required), save, document_id, close_after_save.

apply_poly_v_groovesC

Preflight or cut exact rounded Poly-V grooves into one global-X rotational body.

Inputs: request (required).

apply_specification_autofillC

Apply filling or syncing of specification rows from the model tree.

Inputs: save, fields, fill_only, document_id, +5 more.

apply_specification_changesC

Apply edits to existing specification rows by object_id and standard fields.

Inputs: updates (required), save, document_id, layout_name, +3 more.

apply_v_belt_groovesA

Preflight or cut previewed V-grooves into one global-X rotational body.

Inputs: request (required).

batch_analyze_model_qualityC

Open models read-only, run naming/spec quality checks, close each document and continue after errors.

Inputs: root, limit, paths, visible, +9 more.

batch_smoke_check_sessionC

Run lifecycle smoke-checks over a folder or explicit file list, continuing after per-file errors.

Inputs: root, limit, paths, dry_run, +9 more.

capture_document_snapshotC

Capture a bounded readback snapshot for an active/opened document, optionally writing the full manifest JSON.

Inputs: visible, read_only, model_path, document_id, +4 more.

check_file_accessC

Check whether a file can be opened and whether it appears locked by another process.

Inputs: path (required).

classify_runtime_errorA

Classify a KOMPAS/COM runtime error into a stable code, category, and recovery hint.

Inputs: message (required), stage, exception_type.

cleanup_to_exportC

Apply the current cleanup rules, export a working copy, and write a report next to it.

Inputs: suffix, rules_path, document_id.

clear_sketch_entity_constraintsC

Delete all constraints attached to one existing sketch entity.

Inputs: entity, sketch_ref, document_id.

close_documentC

Close the selected or active document.

Inputs: save, close_mode, document_id.

create_compression_springC

Create a KOMPAS compression spring part from the supported compression_spring scenario.

Inputs: params (required), visible, output_path, close_after_save, +2 more.

create_part_from_scenarioC

Create a KOMPAS part from a supported parametric scenario such as stepped_shaft.

Inputs: params (required), scenario (required), visible, output_path, +3 more.

create_point3dC

Create a 3D point in the active part and verify the before/after snapshot delta.

Inputs: name, origin, max_items, min_added, +3 more.

create_sketch_arcC

Create one 2D sketch arc in a new or existing sketch and verify the snapshot delta.

Inputs: end, name, plane, start, +11 more.

create_sketch_circleB

Create a sketch with one 2D circle and verify the before/after snapshot delta.

Inputs: name, plane, center, radius, +8 more.

create_sketch_ellipseC

Create one 2D sketch ellipse in a new or existing sketch and verify the snapshot delta.

Inputs: name, angle, plane, center, +10 more.

create_sketch_entitiesA

Create several 2D sketch entities in one target sketch and verify the snapshot delta.

Inputs: name, plane, entities, max_items, +9 more.

create_sketch_line_segmentB

Create a sketch with one 2D line segment and verify the before/after snapshot delta.

Inputs: end, name, plane, start, +8 more.

create_sketch_pointB

Create one 2D sketch point in a new or existing sketch and verify the snapshot delta.

Inputs: name, plane, point, max_items, +7 more.

create_sketch_polylineC

Create one 2D sketch polyline in a new or existing sketch and verify the snapshot delta.

Inputs: name, plane, closed, points, +8 more.

create_sketch_rectangleC

Create a sketch rectangle from two corners and verify the before/after snapshot delta.

Inputs: name, plane, corner1, corner2, +8 more.

create_specificationC

Create a specification description and fill rows from the current assembly tree.

Inputs: save, style_id, document_id, layout_name, +4 more.

create_spring_from_sizeC

Create a supported spring from one resolved catalog entry.

Inputs: entry_id (required), catalog_id (required), visible, overrides, +3 more.

create_spw_from_modelA

Create a separate .spw specification document from the current model tree.

By default writes only position, designation, title, quantity, comment. Engineering fields are written only when mapped by columns and opted in.

Inputs: columns, style_id, document_id, layout_name, +4 more.

delete_sketch_entityC

Delete one existing sketch entity selected by reference, index, or fingerprint.

Inputs: entity, sketch_ref, document_id.

diff_document_snapshotsC

Compare two readback snapshot/manifest payloads or JSON artifact paths with bounded item deltas.

Inputs: after (required), before (required), max_items, ignore_keys, +2 more.

find_itemsC

Search items by text and optional kinds.

Inputs: kinds, query, document_id.

find_spring_sizesC

Find spring catalog entries by type, size, class, or tag.

Inputs: tag, limit, turns, height, +10 more.

get_active_document_stateC

Read bounded active-document state through the primitive operation pipeline.

Inputs: max_items, document_id, include_tree, include_items, +1 more.

get_document_compositionC

Read the stored composition of the selected or active saved document.

Inputs: document_id.

get_document_treeB

Return the assembly/model tree for the selected or active document.

Inputs: document_id.

get_file_compositionC

Read the stored composition of an assembly file directly from the file itself.

Inputs: assembly_path (required).

get_item_propertiesD

Return a practical properties snapshot for selected items.

Inputs: item_ids, document_id.

get_itemsC

Return selected tree items with their current properties.

Inputs: item_ids, document_id.

get_mcp_tool_catalogA

Return the public tool catalog; research tools require explicit opt-in.

Inputs: category, stability, include_research.

get_session_stateB

Return basic information about the current KOMPAS session.

Inputs: no named parameters.

get_specificationC

Read the active or selected specification description with its objects and columns.

Inputs: document_id, layout_name, max_objects, include_objects, +1 more.

get_specification_descriptionsA

List available specification descriptions for the selected or active document.

Inputs: document_id.

inspect_featureB

Inspect one existing 3D feature selected by reference, index, fingerprint, or name.

Inputs: feature, document_id.

inspect_sketch_constraintB

Inspect one existing sketch constraint selected by reference, index, or fingerprint.

Inputs: constraint, sketch_ref, document_id.

inspect_sketch_dimensionB

Inspect one existing sketch dimension selected by reference, index, or fingerprint.

Inputs: dimension, sketch_ref, document_id.

inspect_sketch_entityC

Inspect one existing sketch entity selected by reference, index, or fingerprint.

Inputs: entity, sketch_ref, document_id.

inspect_sketch_fullA

Full dump of an existing sketch: entities, dimensions, constraints, status.

Parameters

document_id : str | None Document ID. None = active document. sketch_ref : str Sketch reference (name or reference ID). include_dimensions : bool If True, read dimensions with values and entity refs. include_constraints : bool If True, read constraints via API5 ksGetObjConstraints (22 types: horizontal, vertical, parallel, perpendicular, merge_points, tangent, fixed_length, concentricity, etc.). include_diagnostics : bool If True, include COM/API5 diagnostic blocks such as projection classification, variable surfaces, available properties, and begin-edit fallback data. max_items : int Max entities per collection.

Returns

dict with: entities — list of {kind, index, geometry, reference, constraints_state} geometry: segments get start/end; arcs get start/end/center/radius/direction; circles get center/radius; points get point coordinates. dimensions — dimensions.items plus api5.dimension_variable_name and linked variable Expression when available. constraints — constraints.items/api5_items/all_items/projection_items with owner_object/partner_object links. status — sketch definition status (0=not_defined, 1=under, 2=fully, 3=over) collections — entity collections metadata projection — per-entity projection classification and UI-like projection constraints when detected.

Inputs: max_items, sketch_ref, document_id, include_dimensions, +2 more.

list_documentsB

Return open KOMPAS documents.

Inputs: no named parameters.

list_featuresC

List existing 3D features with reference, index, fingerprint, and state fields.

Inputs: kinds, max_items, document_id.

list_helical_thread_v1_candidatesA

List only helical-thread-V1-compatible metric standards with bundled size rows.

Inputs: offset, pitch_max, pitch_min, title_query, +4 more.

list_poly_v_profilesA

List ISO 9982:2021 PH, PJ, PK, PL, and PM Poly-V pulley profiles.

Inputs: no named parameters.

list_sketch_constraintsC

List existing sketch constraints with reference, index, fingerprint, and owner entity fields.

Inputs: kinds, max_items, sketch_ref, document_id.

list_sketch_dimensionsB

List existing sketch dimensions with reference, index, fingerprint, and placement fields.

Inputs: kinds, max_items, sketch_ref, document_id.

list_sketch_entitiesC

List existing sketch entities with reference, index, fingerprint, and geometry selectors.

Inputs: kinds, max_items, sketch_ref, document_id.

list_sketchesA

List sketches with their stable sketch_ref values for follow-up entity tools.

Inputs: max_items, document_id, name_contains, include_entity_counts.

list_spring_size_catalogsC

List available built-in spring size catalogs.

Inputs: catalog_dir, spring_type, include_entries.

list_thread_catalog_entriesC

List size rows of one thread standard table (d/p/title), with helical-thread-friendly shaping.

Inputs: standard (required), limit, pitch, offset, +7 more.

list_thread_catalog_standardsC

List thread standards from KOMPAS thread.db with helical-thread V1 compatibility hints.

Inputs: database_path.

list_v_belt_profilesB

List built-in classical or narrow-wedge V-belt groove profiles.

Inputs: request (required).

normalize_operation_resultC

Normalize a primitive operation result, preflight/readback checks, and optional error into one envelope.

Inputs: operation (required), error, stage, checks, +6 more.

open_documentC

Open a KOMPAS document and return a stable document_id.

Inputs: path (required), visible, read_only.

parameterize_sketchC

Apply constraints/dimensions to existing sketch entities selected by reference, index, or fingerprint.

Inputs: entities, max_items, dimensions, sketch_ref, +5 more.

preflight_document_contextC

Check KOMPAS session/document readiness before running a low-level operation.

Inputs: min_items, document_id, require_tree, require_items, +4 more.

preview_changesetC

Build a safe preview of name and designation changes.

Inputs: rules_path, document_id.

preview_compression_springC

Preview a compression spring scenario without creating a KOMPAS document.

Inputs: params (required).

preview_flat_belt_pulleyC

Preview a cylindrical or explicitly crowned flat-belt pulley rim.

Inputs: request (required).

preview_part_scenarioB

Preview a parametric part scenario without creating a KOMPAS document.

Inputs: params (required), scenario (required).

preview_poly_v_grooveB

Preview a rounded Poly-V pulley groove set without hubs, bores, or COM.

Inputs: request (required).

preview_property_changesC

Preview direct property edits for writable item fields.

Inputs: updates (required), document_id.

preview_section_by_surface_operationC

Preview a low-level section-by-surface operation payload.

Inputs: target_ref (required), surface_reference (required), role, keep_side, +2 more.

preview_specification_autofillC

Build a safe preview of filling or syncing specification rows from the model tree.

Inputs: fields, fill_only, document_id, layout_name, +3 more.

preview_specification_changesC

Preview edits for existing specification rows by object_id and standard fields.

Inputs: updates (required), document_id, layout_name, max_objects, +1 more.

preview_specification_generationC

Build a practical specification preview from the assembly tree.

Inputs: document_id, include_root.

preview_spring_from_sizeC

Preview a supported spring from one resolved catalog entry.

Inputs: entry_id (required), catalog_id (required), overrides, catalog_dir.

preview_spw_generationB

Build a preview for a separate .spw specification document from the assembly tree.

columns maps row fields to .spw columns: field, column_type, block_number, column_number, skip_unit_value. column_preset can be default/base or engineering_comment_columns. Engineering fields require explicit opt-in.

Inputs: columns, document_id, include_root, column_preset, +1 more.

preview_timing_belt_pulleyA

Preview an end-view synchronous-belt pulley tooth profile; no CAD write.

Inputs: request (required).

preview_v_belt_grooveB

Preview functional V-groove cut geometry without hubs, bores, or COM.

Inputs: request (required).

probe_document_readbackC

Collect a low-level COM readback manifest for an opened file or active document.

Inputs: visible, read_only, model_path, document_id, +2 more.

probe_model_formulasC

Probe formula-bearing sketch dimensions, constraints, and feature variables.

Inputs: visible, read_only, model_path, document_id, +3 more.

probe_model_object_collectionsC

Probe known sketch/feature collections exposed by the selected or active 3D document.

Inputs: max_items, document_id, include_empty.

recommend_spring_sizesC

Recommend nearest spring catalog entries for target dimensions.

Inputs: tag, limit, end_type, hook_type, +12 more.

refresh_specification_from_modelC

Recreate the active specification from the model and then apply safe autofill for supported fields.

Inputs: save, fields, style_id, fill_only, +7 more.

rename_sketchB

Rename an existing sketch selected by sketch_ref.

Inputs: name, sketch_ref, document_id.

repair_featureB

Plan or apply bounded repairs to existing 3D features: rename, suppress, or delete.

Inputs: apply, operations, document_id.

repair_sketchC

Plan or apply a bounded repair scenario for one existing sketch.

Inputs: apply, operations, sketch_ref, document_id.

resolve_poly_v_profileC

Resolve one ISO 9982:2021 Poly-V pulley groove profile.

Inputs: request (required).

resolve_spring_sizeC

Resolve one spring catalog entry to generator-ready scenario params.

Inputs: entry_id (required), catalog_id (required), overrides, catalog_dir, +1 more.

resolve_thread_catalog_designationC

Resolve a thread size by its designation/title within the default standard for a thread type (or an explicit standard).

Inputs: designation (required), standard, thread_type, database_path.

resolve_v_belt_profileC

Resolve one V-belt groove profile and its diameter-dependent angle.

Inputs: request (required).

save_documentC

Save the selected or active document in place.

Inputs: document_id, close_after_save.

save_document_asC

Save the selected or active document to an explicit path.

Inputs: path (required), document_id, close_after_save.

save_export_copyC

Save the active document to the default export directory with an ASCII-safe file name.

Inputs: suffix, document_id, close_after_save.

scan_model_filesA

Scan a folder or a single file for KOMPAS model files without opening KOMPAS.

Inputs: root (required), max_files, recursive, extensions, +1 more.

set_item_propertiesC

Apply direct property edits for writable item fields.

Inputs: updates (required), save, document_id, close_after_save.

set_sketch_entity_styleC

Set line style on one existing sketch entity selected by reference, index, or fingerprint.

Inputs: entity, line_style, sketch_ref, document_id.

shutdown_sessionB

Close all tracked documents and release the KOMPAS session.

Inputs: save, close_mode.

smoke_check_sessionB

Open, save-as-close, reopen-readonly and close a KOMPAS document to verify lifecycle handling.

Inputs: path (required), visible, output_dir.

update_sketch_entity_geometryA

Update geometry for one existing point, segment, circle, or arc selected by reference, index, or fingerprint.

Inputs: entity, geometry, sketch_ref, document_id.

validate_spring_size_catalogsC

Validate built-in spring catalog metadata and optional previews.

Inputs: catalog_dir, include_preview.

verify_document_readback_stabilityB

Capture two readback snapshots and verify that document readback is stable before write/read checks.

Inputs: max_items, document_id, ignore_keys, ignore_paths, +5 more.

verify_document_snapshot_deltaC

Verify expected before/after readback snapshot deltas for a primitive operation.

Inputs: operation (required), diff, after, before, +16 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.3/5.0

    Scored across 118 tools

    Disambiguation1/5

    The relink family alone has 17 highly similar tools (relink_to_export vs relink_from_map_to_export vs relink_file_to_output, preview_relink_paths vs preview_file_relink_paths vs preview_relink_map_paths) that are nearly indistinguishable without reading detailed descriptions. get_items and get_item_properties also overlap heavily, making agent misselection very likely.

    Naming Consistency3/5

    Most tools follow a readable snake_case verb_noun pattern (list_, create_, preview_, apply_), but the relink group mixes styles inconsistently (apply_relink_paths, relink_to_export, relink_from_map_to_export, preview_relink_paths). Read operations also alternate between get_, list_, probe_, and capture_, which weakens overall predictability.

    Tool Count1/5

    118 tools is far beyond a coherent single-server scope and creates a severe navigation and selection burden. The server bundles many distinct domains — sketches, features, specifications, relinking, thread/belt/spring catalogs, and low-level diagnostics — that should be split into focused MCP servers.

    Completeness3/5

    The surface is very broad and many workflow pairs are present (preview/create, preview/apply, analyze/apply), but there are notable gaps: no direct create/update/delete tools for sketch dimensions, no generic 3D feature creation beyond scenarios, and no assembly creation or component insertion tools. These omissions leave some common CAD workflows incomplete despite the huge tool count.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Enables AI agents to create and edit native KOMPAS-3D models from text descriptions, drawings, or PDFs, with parameterization, assemblies, drawings, and export to STEP, STL, and IGES.
      41
      13
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to build, measure, verify, and correct parametric SolidWorks parts and assemblies locally via the COM API, supporting operations like sketching, extruding, modeling, dimensioning, material assignment, export, and assembly mating.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to drive desktop CAD software through natural language with verified execution, failure recovery, and traceable results across modeling, assemblies, drawings, exports, motion, FEA, and related engineering workflows.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI assistant to control KOMPAS-3D through its COM API, including opening and saving documents, building parts and assemblies, measuring models, and creating dimensioned drawings.
      1
      MIT