sketchup-mcp2: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) working in this repository.

What This Project Does

MCP Server for SketchUp bridges Claude AI and SketchUp via the Model Context Protocol (MCP). Two components:

1. Python MCP server (src/sketchup_mcp/) — receives Claude's tool calls, forwards them over TCP
2. Ruby SketchUp extension (mcp_for_sketchup/mcp_for_sketchup/) — TCP server inside SketchUp, executes commands against the live model

Non-Obvious Constraints

• Units: SketchUp's internal Ruby API uses inches; all MCP tools accept and return mm. Convert at the boundary via MM = 25.4.
• Group#subtract is reversed: A.subtract(B) returns B - A. To get «target minus tool», call tool.subtract(target). Verified empirically against SketchUp 2026.
• SketchUp is single-threaded: the Ruby extension cannot use threads; all I/O runs in UI.start_timer callbacks.
• Wire protocol (v0.0.1+): 4-byte big-endian length-prefix framing, 64 MiB cap.
• Persistent socket: Python server holds one TCP connection; asyncio.Lock serializes tool-calls. Ruby reads non-blocking inside UI.start_timer, capped at 50 reads per tick (~3.2 MB) to keep SketchUp's UI responsive.
• Ruby supports N concurrent TCP clients: core/server.rb keeps @clients (sock → ClientState) + a global FIFO @frame_queue. Each timer tick: accept connections, drain reads into each client's FrameReader, dispatch frames in FIFO decode-arrival order (accept-order across clients, decode-order within a client — single shared queue, not round-robin). Operations still serialise on the single-threaded SketchUp UI thread. Per-client errors close only that client. Logical races between clients on the model are the user's responsibility (no server-side locking). Half-open sockets detected via SO_KEEPALIVE (OS default ~2h).
• Entity IDs: SketchUp's find_entity_by_id requires Integer; cast incoming string IDs with .to_i.
• Solid tools are unreliable on non-manifold geometry: boolean_operation and edge ops use copy-based + sequential-per-edge workarounds.
• Sketchup::Model#undo does not exist: programmatic undo dispatches Sketchup.send_action("editUndo:").
• Request IDs round-trip: both sides preserve the JSON-RPC id so async responses can be matched.
• Mutating handlers wrap edits in model.start_operation/commit_operation so undo rolls back atomically.
• eval gate: eval_ruby is gated by the eval_enabled pref, which ships on (Config::DEFAULTS[:eval_enabled] = true) and is closed from Plugins → MCP Server → Settings.... An absent pref resolves to that default; a present-but-non-boolean pref fails closed — a corrupt value is no basis for enabling arbitrary code execution. Gate closed ⇒ handlers/eval.rb::eval_ruby raises JSON-RPC -32010, which tools.py::eval_ruby turns into a user-facing message (no [code] prefix) so the LLM repeats it verbatim. Arbitrary-code risk is guarded in two layers: (1) a blocking enable-time security confirm (ui/settings_dialog.rb::confirm_eval_enable — warns it grants full filesystem/network/shell access), shown on an off→on transition inside the Settings dialog — and only there. An upgrade does not pass through the dialog, so an install with no stored pref (never opened Settings) gets the new open default with no confirm, including one upgrading from a -warehouse build where the gate was closed; (2) per-call review at the MCP client — Claude Desktop / Claude Code show each eval_ruby call's code to approve or deny. Note this second layer is a client convention, not a protocol guarantee: MCP does not mandate an interaction model, and a client running pre-authorized (--dangerously-skip-permissions) shows nothing. The extension deliberately does NOT log or re-prompt the code — that would duplicate the client's permission UI and break autonomous (--dangerously-skip-permissions) operation.
• Version handshake (one-time on connect): every TCP connection MUST begin with a JSON-RPC hello request carrying params.client_version. The server validates against core/compat.rb's MIN_PYTHON..MAX_PYTHON range and replies with {server_version, client_id} in result. Mismatches return JSON-RPC error -32001 (IncompatibleVersionError on the Python side) and the server closes the socket. After a successful handshake, regular tools/call requests carry no client_version field and responses carry no server_version field. Compatibility ranges live in src/sketchup_mcp/compat.py and mcp_for_sketchup/mcp_for_sketchup/core/compat.rb. get_version remains a regular tool returning the verdict payload.
• Literal source-guard tests: test/test_operation_names.rb, test/test_transform_absolute.rb, test/test_joints_frame_compensation.rb pin exact handler source text (down to indentation) to protect invariants like the reversed Group#subtract. Never run an auto-formatter over handlers or tests; when refactoring pinned code, update the pins deliberately.