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.25 Measured native runtime: SketchUp 2024 24.0.594 / Ruby 3.2.2

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: SketchUp MCP Server

Current callable surface

Read/system tools:

• help

• system_status

• system_capabilities

• document_info

• object_list

• object_get

• 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

• 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

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

• 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 now preserve generic instance-level appearance/classification properties (material, tag, name, hidden state and shadow flags) for Groups and ComponentInstances, and the strict receipt validation aborts if those properties do not survive duplication.

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. Model/world coordinate input is 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 public tree automated suite is 202/202 PASS on the measured Windows development environment.

Native acceptance has been measured on SketchUp 2024 for the baseline bridge plus strict box, face, isolated extrusion-to-group, absolute transform, manifold boolean, object delete, strict group composition, strict component/instance semantics, strict copy/array/mirror duplication, strict tag/material assignment, strict curve/polyline primitives, strict profile sweep, read-only measurement/topology queries, allowlisted asset placement, real-world texture scale, camera/scene control, rooted document lifecycle and CAD integrity with safe repair, including negative/rollback cases. The public HTTP MCP surface was live-smoked at contract 0.21 with 64 tools. Contract 0.22 corrected safety semantics for document I/O, error sanitization, rooted-path containment, and unsaved-model protection. Contract 0.23 added bounded topology closure plus topology-aware raw Edge/Face deletion; contract 0.24 added guarded connected-face push/pull under the same 64-tool MCP surface. The 0.23–0.24 topology path has now been natively exercised twice on fresh disposable SketchUp 2024 models, including connected closure discovery, successful connected push/pull, stale-fingerprint fail-closed behavior, and topology-aware raw delete. Contract 0.25 additionally natively verifies generic copy-property fidelity across direct copy, linear array, radial array and Group copy. Contract 0.22 document/path safety remains a separate native-acceptance scope.

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.