CDT-SketchUp

SketchUp-native MCP provider implementing a Generic CAD Primitive / Execution Engine with bounded native execution, semantic state and verified transactional mutation paths.

Current provider version: 0.1.0 · Contract: 0.31 Broad native feature acceptance remains rooted in contract 0.28; the contract 0.30 recovery additions are live-accepted on SketchUp 2024 24.0.594 / Ruby 3.2.2. Retry-sensitive callers use execute_geometry(operation_id=...); ambiguous completion returns unknown_commit, then reconcile_operation(operation_id) decides whether replay/retry is safe.

What it is

CDT-SketchUp lets MCP clients query and manipulate the active SketchUp model through typed generic CAD tools. It is intentionally domain-neutral: architecture, structure, MEP, mechanical, interior, infrastructure, TCVN/QCVN and engineering Audit Report logic belong to external Domain Agents.

Domain Agent / MCP client
        ↓
CDT-SketchUp Python MCP provider
        ↓ bounded authenticated loopback JSON
CDT-SketchUp Ruby extension
        ↓ SketchUp Ruby API on main thread
active SketchUp model

No arbitrary Ruby/script execution tool is exposed.

Related MCP server: vn-sketchup-mcp

Current callable surface

Read/system tools:

• help

• system_status

• system_capabilities

• document_info

• object_list

• object_get

• reconcile_operation

• get_entity_state

• definition_info

• measure_distance

• query_topology

• query_overlap

• asset_list

• place_asset

• texture_list

• material_apply_texture

• material_info

• camera_get

• camera_set

• scene_list

• scene_create

• model_save

• model_save_as

• model_open

• model_export

• model_list

• artifact_seal

• artifact_verify

• integrity_report

• repair_reverse_face

• repair_erase_degenerate

Strict Semantic State Loop surface:

• execute_geometry

• transform_entity

• move_entity

• rotate_entity

• scale_entity

• boolean_operation

• delete_entity

• group_entities

• create_component

• place_instance

• make_unique

• copy_entity

• linear_array

• radial_array

• mirror_entity

• create_polyline

• create_rectangle

• create_circle

• create_arc

• create_polygon

• create_mesh

Current closed strict actions:

• create_box

• create_face

• extrude_face_to_group

• transform_entity

• boolean_operation

• delete_entity

• delete_topology_entity

• push_pull_topology_face

• group_entities

• create_component

• place_instance

• make_unique

• copy_entity

• linear_array

• radial_array

• create_polyline

• create_rectangle

• create_circle

• create_arc

• create_polygon

• create_mesh

• sweep_profile

delete_entity remains the preferred strict object-deletion path for unlocked active-context Groups and ComponentInstances. Raw Edge/Face deletion uses execute_geometry(action="delete_topology_entity"); connected-face push/pull uses execute_geometry(action="push_pull_topology_face"). Both require a prior topology_closure_fingerprint from query_topology, recheck that closure before and inside AI_Step, and commit only when affected PID accounting stays inside the bounded pre/post topology contract. The topology additions in contracts 0.23–0.24 are now natively accepted on SketchUp 2024 24.0.594 / Ruby 3.2.2; document/path safety changes from 0.22 remain a separate acceptance scope.

Contract 0.25 closes a copy-fidelity gap discovered by the townhouse stress test: copy_entity, linear_array, and radial_array preserve generic instance-level appearance/classification properties (material, tag, name, hidden state and shadow flags) for Groups and ComponentInstances, and strict receipt validation aborts if those properties do not survive duplication.

Contract 0.26 added bounded nested instance_path targeting and cryptographic sha256 + native_version asset identity. Contract 0.27 added the generic bounded create_mesh indexed-mesh primitive for externally planned complex geometry. Contract 0.28 adds bounded-exact manifold-solid surface clearance/overlap semantics plus content-addressed artifact_seal/artifact_verify. Spatial exactness is measured only at/above 1e-7 native inches and within the 1024-triangle / 1048576 pair-test budgets; sub-epsilon interference may collapse to touching but is never reported clear. Those paths are natively accepted on SketchUp 2024 24.0.594 / Ruby 3.2.2. Contract 0.29 added optional caller-owned execute_geometry.operation_id, mapped to native mutation identity while wire request correlation remains per connection. Contract 0.30 closes the recovery truth gap: response loss after a sent mutation is reported as unknown_commit rather than a fabricated rejection, reconcile_operation exposes the native journal/proof path publicly, unknown journal entries are not replayed as definitive receipts, and rolled_back=true is emitted only after fingerprint-verified restoration. The public lost-response-after-commit acceptance proves exactly-once side effects and same-ID replay without duplication. Contract 0.31 makes semantic topology/manifold traversal descend a bounded single-container Group/ComponentInstance wrapper chain so nested wrapper state is consistent without flattening mixed/multi-solid structures. Component-definition edits remain shared unless the caller explicitly uses make_unique; asset reuse never trusts filename/path identity alone.

Compatibility modeling tools currently also include edge/face/group creation, selection, delete, move/rotate/scale, push/pull, box component, tags and basic materials. These older mutation paths are not claimed equivalent to the strict pre-commit semantic-validation path; see the Tool Guide.

Machine-readable capability safety

system_capabilities now returns capability metadata schema v2 for every public MCP tool. Clients can select safe paths from JSON instead of inferring from prose. Each descriptor reports the tool/capability key, live support state, safety_class, read-only/destructive status, transaction and verified-rollback guarantees, identity semantics, unit/coordinate semantics, idempotence, limits, measured runtime versions, deprecation/replacement state, and whether the tool is preferred.

The four safety classes are:

• read_only — no model mutation;

• strict_mutation — Semantic State Loop mutation with transaction/compensation + pre-commit validation + verified rollback;

• external_side_effect — bounded preferred file/application action with verified completion but no claimed SketchUp transaction or rollback;

• deprecated_legacy — compatibility mutation path retained temporarily but excluded from preferred_tools.

A deterministic capability_fingerprint hashes only static descriptor semantics, so runtime availability changes do not masquerade as contract changes. observed_runtime is reported separately from the measured runtime_versions evidence list.

Unified semantic receipts

Strict mutations, semantic queries, and document side effects expose discoverable receipt schema v1. Strict geometry returns operation receipts, semantic reads return query receipts, and document save/open/export returns external_side_effect receipts.

Strict operation receipts include receipt_id, command/action, commit truth, context, exact affected PID sets, entity states, before/after model fingerprints, validation, rollback detail, duration and non-secret limits. External-side-effect receipts explicitly report transactional=false, rollback_supported=false, and verified completion rather than pretending a SketchUp transaction was committed.

Affected PID accounting is derived from bounded semantic snapshots of the active edit context: created entities are new PIDs, changed/reparented surviving PIDs are modified, and only PIDs that no longer resolve are deleted. This avoids falsely describing extrusion source topology as deleted when SketchUp has moved it inside the new Group.

Receipt context identity is now verified at contract 0.9: query receipts provide deterministic context.id, context.revision, and entity_fingerprint; successful operations preserve context_before and return the new post-commit context.

Explicit units and coordinate space

Strict semantic tools no longer require clients to know SketchUp's native length storage. execute_geometry, get_entity_state, transform_entity, boolean_operation, and delete_entity expose unit with mm | cm | m | in | ft | model and coordinate_space="active_context". The default remains in for contract-0.9 compatibility, but new integrations should send a unit explicitly.

The native bridge converts dimensional request values exactly once at its boundary, performs SketchUp operations in native inches, and converts semantic states/validation evidence back to the requested unit. model resolves to the active model's configured length unit and the receipt reports both unit and resolved_unit. Bounds/points/distances use the declared length unit, areas use its square, volumes its cube, and transformation matrix translations at indices 12–14 use the declared length unit; rotation/scale matrix terms remain unitless.

Only active-edit-context coordinates are claimed today. When execute_geometry/place_asset receives target_context, active_context means the local coordinate frame of that validated nested edit path; model/world coordinate input is still rejected rather than silently transformed. Legacy compatibility mutation tools retain their documented internal-inch behavior until migrated.

Strict transform convenience tools

move_entity, rotate_entity, and scale_entity are preferred ergonomic tools over the absolute transform_entity matrix API. Each convenience call first reads the current semantic transform/context/fingerprint, constructs an explicit absolute target transform, then submits that target through the same strict transform_entity Semantic State Loop with automatic if_context and if_match guards. Relative transform math never opens a second native mutation path. mirror_entity follows the same pattern with an explicit reflection target (negative-determinant absolute transform).

The older object_move, object_rotate, and object_scale MCP names remain deprecated compatibility aliases, but they now route through the same strict wrapper engine and return operation receipts. Their former direct Ruby bridge commands are no longer exposed.

Context identity and stale-write protection

Contract 0.9 adds deterministic optimistic-concurrency guards for strict mutations. get_entity_state returns a verified context object plus the entity semantic fingerprint. Strict mutation tools accept optional if_context={id, revision} and if_match=<semantic_fingerprint>.

context.id identifies the current SketchUp process/model/edit path using a process-session token, model GUID, and active-path persistent/definition identity. context.revision hashes that context identity with the canonical model fingerprint, so model-state changes advance the revision while an unchanged edit path retains the same context ID.

Guards fail before AI_Step: a changed model/edit context returns context_mismatch; a changed target entity returns stale_entity_state. Successful operation receipts retain both context_before and the new post-commit context, allowing clients to chain safely without guessing which revision the operation consumed.

For low-LLM-dependency usage, the intended flow is: query → echo context as if_context and entity_fingerprint as if_match → mutate. system_capabilities advertises supported preconditions per strict tool.

Semantic State Loop

Strict autonomous mutations use:

exact target/context
  -> AI_Step transaction
  -> native SketchUp action
  -> semantic extraction
  -> invariant + fingerprint validation before commit
  -> commit or verified rollback

Machine geometry validation uses semantic model state, not viewport screenshots.

Requirements

• Python 3.10+

• mcp>=2.2,<3

• SketchUp Desktop with Ruby API

• no third-party Ruby gems

See Compatibility for measured native support.

Build and install the SketchUp extension

python scripts/build_rbz.py

Install dist/cdt-sketchup-bridge-0.1.0.rbz from SketchUp Extension Manager. The extension registers CDT-SketchUp Bridge and starts a loopback bridge on 127.0.0.1:9876.

The extension creates a random per-user bridge credential outside the repository:

• Windows: %LOCALAPPDATA%\\CDT-SketchUp\\bridge.token

• other supported development environments: ~/.cdt-sketchup/bridge.token

Run the MCP provider

python -m pip install -e .
cdt-sketchup

Default endpoint:

http://127.0.0.1:8765/mcp

Loopback is the default. For an explicit non-loopback bind, startup requires:

• CDT_SKETCHUP_MCP_TOKEN — at least 32 characters;

• CDT_SKETCHUP_ALLOWED_HOSTS — exact comma-separated Host allowlist.

Optional browser origins use CDT_SKETCHUP_ALLOWED_ORIGINS. Remote production deployments still need normal TLS/reverse-proxy protection.

Safety highlights

• Ruby bridge is loopback-only;

• random local bridge credential;

• bounded bridge frames and object/geometry work;

• no arbitrary Ruby, shell or script execution surface;

• persistent-ID targeting for identity-sensitive operations;

• active edit-context checks;

• strict semantic validation before commit;

• verified rollback for strict failure paths;

• fail-closed live capability discovery;

• domain-neutral provider boundary.

See Security.

Verification

Offline tests:

python -m unittest discover -s tests -v

The current Linux/gateway automated suite is 238 passed, 2 skipped. The skips are environment-specific optional checks and do not suppress contract coverage.

The broad native baseline remains contract 0.28; contract 0.30 recovery additions are separately live-accepted on SketchUp 2024 24.0.594 / Ruby 3.2.2. The public surface contains 68 MCP tools. The measured 0.28 matrix covers nested three-level edits and context restoration, strong asset identity and exact-definition reuse/drift rejection, Engineer catalog-resolver integration, bounded mesh realization for tetra/frustum/multi-section loft/ellipsoid/rounded/open-molding cases, mesh budget/malformed-input fail-before-mutation and verified rollback, bounded spatial disjoint/touching/penetrating/rotated queries within the documented 1e-7 native-inch and 1024-triangle / 1048576 pair-test envelope, non-manifold/budget fail-closed behavior, uncertain-completion reconciliation and compensation, content-addressed artifact seal/staleness/reseal, save/reopen verification and instance-specific make_unique isolation. Earlier measured topology/copy/unit/texture/camera/scene/document/integrity paths remain part of the supported SketchUp-2024 baseline.

cdt-sketchup-doctor provides offline and live health checks (doctor, doctor --live), extension install/uninstall, token repair, and a sanitized support-bundle that never includes credential material. The RBZ build is byte-reproducible (fixed archive metadata).

Public documentation

• Documentation index

• Architecture

• Security

• Tool Guide

• Compatibility

Public product use does not depend on local development plans or session handoff files.