Add an MCP tool to inspect and visualize sketch-region topology

[JordanNoone]

Summary

Add an MCP tool that returns both machine-readable sketch-region topology and a
high-contrast PNG for a sketch in an active modeling session.

Zookeeper can currently validate KCL and take 3D snapshots, but it cannot inspect
the 2D topology that Engine used when deciding whether sketch segments form
regions. When region creation or solid lofting fails, the agent therefore has to
infer whether the cause is an open loop, self-intersection, wrong arc sweep,
incorrect winding, an exterior face, or an unintended nested face from a generic
text error.

Current behavior

• MCP's persistent modeling-session tools can execute KCL, query scene entities,
  and return snapshots.
• MCP does not expose sketch_get_info, region_obj, DCEL faces, ordered region
  loops, or a sketch-region image.
• Engine's existing sketch_get_info modeling command returns source curves,
  region_count, and region_obj. The latter is a Toolpaths/Waveback-style
  l/c/3pa serialization, not Wavefront OBJ and not directly useful to an
  MCP client without parsing and rendering support.
• A recent production review on KCL 0.3.178 found 63 region-construction failure
  spans across 28 traces in the fixed window 2026-08-26 20:50:37Z through
  23:59:47Z. The observed mechanisms were not one defect: they included
  conflicting constraints, incomplete segment selections, collapsed arc
  centers, self-overlapping profiles, and genuinely open loft sections.

Proposed tool

Add a tool such as inspect_sketch_regions with inputs:

• session_id: active persistent modeling session;
• path_id: Engine UUID of the sketch path;
• optional bounded image dimensions.

Return:

1. A versioned JSON manifest containing:
   • original analytic source curves;
   • ordered split-edge loops;
   • DCEL face/region IDs and indexes;
   • interior/exterior classification;
   • nesting depth and parent/child relationships;
   • region count, unmapped edges, unresolved descendants, and other
     non-fatal topology diagnostics.
2. An MCP ImageContent PNG rendered from that same manifest, with distinct
   layers for source curves, interior faces, exterior/hole faces, and labels.

Exterior and interior DCEL faces can share the same boundary. The renderer must
not draw one generic stroke that lets the later face hide the earlier one. Use
classification-aware layers, for example an exterior halo, interior color band,
and source-curve core.

Engine dependency / implementation options

The MCP implementation needs an authoritative Engine response rather than
reconstructing regions from a 3D snapshot.

Either:

1. send sketch_get_info through MCP's existing modeling websocket and parse its
   topology response; or
2. depend on an Engine endpoint/command that returns a versioned topology
   manifest and PNG for path_id.

If MCP continues to require a raw path_id, document how an agent obtains it
from KCL execution/artifact metadata. Prefer also allowing a KCL sketch variable
or artifact reference when the active session can resolve that deterministically.

Expected behavior

After a region/open-profile failure, a caller can inspect the implicated sketch
without rebuilding customer geometry outside Engine. The result should make it
possible to distinguish at least:

• an open boundary;
• a self-intersection or complementary long arc sweep;
• an exterior face selected instead of an interior face;
• nested regions/holes and winding/classification mistakes;
• disconnected or unmapped curve fragments.

Acceptance criteria

• The tool is scoped to an existing session_id and rejects missing, stale, or
  disconnected sessions with a structured error.
• A valid path_id returns a versioned topology manifest and PNG representing
  the same geometry.
• Lines, circles, and three-point arcs preserve analytic geometry; arcs are not
  silently reduced to ambiguous endpoint-only chords.
• Shared interior/exterior boundaries remain visually distinguishable.
• Image dimensions and command duration are bounded consistently with existing
  modeling tools.
• Invalid or non-sketch IDs return an actionable error without evicting an
  otherwise healthy session.
• Mocked-transport tests cover command shape, matching response, Engine error,
  wrong response, timeout, and disconnected session.
• Renderer tests cover nested faces, holes, shared boundaries, and deterministic
  manifest-to-image output.
• Tool documentation explains region_obj's format and how to obtain/resolve the
  sketch path ID.

Downstream follow-up

Once the MCP primitive exists, text-to-cad/Zookeeper should call it after
region-creation and open-profile loft failures and use the manifest before
rewriting the sketch. That orchestration belongs in text-to-cad rather than this
MCP issue.

Duplicate search

No open or closed issue or pull request was found in KittyCAD/mcp for:

• sketch region;
• sketch_get_info;
• region_obj;
• DCEL visualization.

No matching public issue or pull request was found in KittyCAD/engine for
sketch region visualization, sketch_get_info, or region_obj.

Suggested labels

enhancement

[adamchalmers]

We have the start of something with the new debug sketch visualization tool: KittyCAD/modeling-app#13311 which produces ZK-readable image of a sketch, like this:

Karan is currently testing it out for help sketching, but we should add more information to it to make it useful for selecting regions too.