geomwright
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@geomwright List the open KOMPAS documents and show the model tree of the first one."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 geomwrightThey 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.cmdOr run it in a terminal you control (foreground; keep that terminal open):
.\.venv\Scripts\python.exe -m geomwright.studio --port 8765For an agent or an unattended session, use the bounded background launcher:
.\.venv\Scripts\python.exe -m geomwright.studio --background --no-browser --startup-timeout 15It 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 -qThe 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 geomwrightFor 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.jsonThe 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
Call
get_mcp_tool_catalogand choose a category whose status matches the task.Call
get_session_stateandlist_documents; always name the target document explicitly.Use inspection, preview, and preflight tools before a write.
Follow Plan → Execute → Verify → Correct. A successful COM
Update()is not, by itself, proof that geometry or direction is correct.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 workThe 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
Documentation index — choose a guide by task and audience;
Camshaft calculation and CAD / Кулачки ГРМ — timing conventions, strict CAD checks, recipe reuse, recovery, and reference data;
Write operations and safety — mutation rules;
Geomwright Studio — UI workflow and HTTP contract;
Parametric workflows — supported part families;
Construction chains: English / Русский — implemented A–D limits and Stage E roadmap;
Model PNG export — native raster review with temporary standard views and checked restoration;
Spring workflows — spring-family navigation;
Transmission contracts — pulley, sprocket, and gear boundaries;
Cylindrical gear — inputs, rack standards, pin rows, nominal representation, create-only CAD, and live evidence;
Internal gear — ring blank input, ГОСТ 19274-73 geometry, controls, create-only CAD, and live evidence;
Straight bevel gear — nominal projection, dish blank, create-only CAD and recipe; English guide / русское руководство;
Architecture — layer ownership for maintainers;
Module development rules: English / Русский — design and completion criteria;
CAD patterns — verified KOMPAS-specific invariants.
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 toolsanalyze_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_file_relink_pathsC
Apply relinks to an assembly file through KOMPAS itself and save the result to the target path.
Inputs: changes (required), assembly_path (required), output_path.
apply_poly_v_groovesC
Preflight or cut exact rounded Poly-V grooves into one global-X rotational body.
Inputs: request (required).
apply_relink_pathsC
Apply component source-path relinks to the selected or active assembly.
Inputs: changes (required), save, document_id, close_after_save.
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.
build_file_relink_map_planC
Build a grouped actionable relink plan from an explicit mapping file.
Inputs: mapping_path (required), assembly_path (required).
build_file_relink_planC
Build a grouped actionable relink plan for an assembly file.
Inputs: search_root (required), assembly_path (required), relink_all.
build_relink_map_planC
Build a grouped actionable relink plan for the selected or active document from a mapping file.
Inputs: document_id, mapping_path.
build_relink_planC
Build a grouped actionable relink plan for the selected or active document.
Inputs: relink_all, document_id, search_root.
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_file_relink_map_pathsC
Preview relinks for a file assembly from an explicit mapping file.
Inputs: mapping_path (required), assembly_path (required).
preview_file_relink_pathsC
Preview persistent relinks by reading the Sources entry of an assembly file directly.
Inputs: search_root (required), assembly_path (required), relink_all.
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_relink_map_pathsC
Preview relinks from an explicit old->new mapping file, useful when files were also renamed.
Inputs: document_id, mapping_path.
preview_relink_pathsC
Find candidate component path updates by searching for matching filenames under a new root.
Inputs: relink_all, document_id, search_root.
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.
relink_file_from_map_to_outputC
Apply relinks from an explicit mapping file to a copied assembly through KOMPAS itself.
Inputs: output_path (required), mapping_path (required), assembly_path (required).
relink_file_to_outputC
Preview and apply assembly relinks to a copied file through KOMPAS itself.
Inputs: output_path (required), search_root (required), assembly_path (required), relink_all.
relink_from_mapC
Preview and apply assembly relinks from an explicit mapping file.
Inputs: mapping_path (required), save, document_id.
relink_from_map_to_exportC
Apply relinks from an explicit mapping file and save a safe exported copy with a report.
Inputs: mapping_path (required), suffix, document_id.
relink_project_rootC
Preview and apply assembly relinks by matching component filenames under a new root.
Inputs: search_root (required), save, relink_all, document_id.
relink_to_exportC
Preview and apply assembly relinks, then save a safe exported copy with a relink report.
Inputs: search_root (required), suffix, relink_all, document_id.
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
Scored across 118 tools
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.
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.
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.
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
Related MCP Connectors
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
A browser 3D CAD for your AI: it scripts real-size models, uCAD builds them and returns pictures.
Read, query, edit and render DWG drawings with AI. No AutoCAD required.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables 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.4113MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT