Skip to content

KLayout Observer MCP Design

Goal

Build an observer-first MCP server for KLayout that lets an LLM inspect and reason about photonic integrated circuit layouts generated by Python workflows. The server should expose machine-readable geometry, deterministic rendered views, and KLayout-native check results without allowing direct layout editing in the initial release.

Why This Exists

The digital EDA MCP projects reviewed so far are centered on RTL, OpenLane, and shelling out to GUI tools. That is not enough for a PIC workflow. For photonics, the useful capability is not "open KLayout", but "let the model inspect what is actually in KLayout".

This server should answer questions like:

  • What cells and instances are present in this layout?
  • What layers are populated in this region?
  • What is the actual waveguide width, gap, bend radius, or port spacing?
  • What does this coupler or routing region look like right now?
  • What DRC markers exist around this geometry?

Scope

In Scope

  • Open GDS and OASIS layouts produced by Python design flows
  • Persist inspection state in reusable layout sessions
  • Enumerate cells, hierarchy, layers, labels, and bounded geometry summaries
  • Measure core geometry relations relevant to PIC inspection
  • Render deterministic viewport images for model consumption
  • Run existing KLayout DRC scripts and extract marker summaries

Out of Scope for MVP

  • Editing geometry
  • Instance placement or transformations
  • PCell authoring or execution beyond loading an already materialized layout
  • Automatic generation of DRC decks
  • Strong semantic inference of device intent from raw polygons

Use a Python-only MCP server with a thin internal boundary between the MCP adapter and the KLayout bridge.

MCP Layer

Responsibilities:

  • Validate inputs
  • Manage session identifiers
  • Enforce response size limits
  • Return structured JSON and image artifacts
  • Normalize errors into MCP-friendly responses

Implement this layer in Python for MVP. Do not split the server across Node and Python unless there is a later need for transport-specific features. The MCP layer should not contain geometry logic.

KLayout Bridge

Responsibilities:

  • Load layouts through the KLayout Python API
  • Query hierarchy, layers, shapes, labels, and regions
  • Measure geometry in a repeatable way
  • Render viewport images
  • Run DRC scripts and extract markers

This layer should be Python-based and own all interaction with klayout.db and klayout.lay.

Execution Model

Support one required mode in MVP and one deferred mode:

Required for MVP: Headless Deterministic Mode

  • Open the layout without relying on an interactive desktop session
  • Render images from explicit coordinates and layer filters
  • Produce stable JSON and image artifacts suitable for automation

This should be the default because it is reproducible and testable.

Deferred: Attach-to-GUI Mode

  • Inspect a currently open KLayout session
  • Reuse the active view, top cell, and user-selected region
  • Help with ad hoc debugging when a designer is actively using KLayout

This mode is useful, but it should be optional and clearly less deterministic.

Session Model

Every operation after layout open should work against a session_id.

Each session stores:

  • Source path
  • File hash
  • Format
  • Top cell
  • Database unit
  • Loaded layout handle
  • Active layer filter
  • Current viewport or query box
  • Cached rendered artifacts
  • Optional marker database from the latest DRC run

This lets the model iteratively inspect the same design instead of reopening the file for every call.

The implementation should also provide an explicit session close operation and an idle expiration policy so artifacts and in-memory layouts do not accumulate indefinitely.

Initial MCP Tool Surface

Keep the first release small and composable.

open_layout

Inputs:

  • path
  • top_cell optional
  • format optional

Returns:

  • session_id
  • top cells
  • selected top cell
  • dbu
  • bbox
  • layer count
  • file hash

close_session

Inputs:

  • session_id

Returns:

  • closed state
  • deleted artifact count
  • whether the session existed

list_cells

Returns:

  • top-level cells
  • hierarchy counts
  • instance counts
  • optional depth-limited tree summary

describe_cell

Inputs:

  • session_id
  • cell
  • depth optional

Returns:

  • child instances
  • transforms
  • bbox
  • label summary
  • per-layer shape counts

list_layers

Returns:

  • layer/datatype pairs
  • names if available from conventions or layer properties
  • visibility state
  • counts by layer

query_region

Inputs:

  • session_id
  • box
  • layers optional
  • cell optional
  • hierarchy_mode optional

Returns a bounded JSON summary of geometry in a region:

  • polygons
  • paths
  • boxes
  • texts
  • instances
  • bbox statistics
  • truncation metadata

measure_geometry

Inputs should describe one or more targets plus a measurement mode.

Initial measurement modes:

  • path width
  • segment length
  • centerline distance
  • edge-to-edge gap
  • bend radius estimate
  • overlap or intersection detection
  • label-to-geometry distance
  • port-to-port spacing

All measurements must report both micron-scale units and raw dbu values.

set_view

Inputs:

  • session_id
  • box
  • layers optional
  • cell optional

Updates the current session viewport without rendering.

render_view

Inputs:

  • session_id
  • box optional
  • layers optional
  • annotate optional
  • image_size optional

Returns:

  • artifact path
  • image metadata
  • render bbox
  • active cell
  • active layers

This is the core observability tool. The model needs a rendered image of the exact geometry under discussion.

run_drc_script

Inputs:

  • session_id
  • script_path
  • script_type
  • optional parameter map

Returns:

  • success state
  • marker count
  • summary by rule
  • artifact paths for reports

extract_markers

Returns:

  • marker boxes
  • rule names
  • counts
  • optional cropped renders for each marker

PIC-Specific Observation Support

The server should remain geometry-first, but it should still support PIC workflows directly.

Useful first-class behaviors:

  • Layer-filtered region inspection for waveguide and pin layers
  • Label extraction for port names and device references
  • Gap and width measurements in directional couplers and routing sections
  • Radius estimation around bends
  • Per-region shape density summaries for dense reticle fragments

Photonic semantics are not native to raw GDS. If higher-level concepts like ports or devices are needed, accept an optional convention file that maps:

  • layer meanings
  • label patterns
  • marker conventions
  • known port markers

Treat these as heuristics, not ground truth.

Determinism Rules

To keep the server reliable:

  • Every render call must take explicit image size
  • Every query must cap output size
  • Every response must include units
  • Every truncation must be explicit
  • Every derived metric must identify the objects it was computed from

Do not silently flatten large hierarchies. Expose hierarchy_mode explicitly so the caller decides whether to inspect flat geometry or hierarchical summaries.

Error Handling

Return structured diagnostics for:

  • file not found
  • unsupported format
  • missing top cell
  • empty query region
  • oversized query region
  • ambiguous label targets
  • measurement target not found
  • no markers available
  • render failure
  • truncated output

Errors should be machine-readable first, human-readable second.

MVP

The MVP should include only:

  • open_layout
  • close_session
  • list_cells
  • describe_cell
  • list_layers
  • query_region
  • measure_geometry
  • set_view
  • render_view
  • run_drc_script
  • extract_markers

This is enough to support practical inspection flows such as:

  • Review a Python-generated PIC layout
  • Inspect a suspicious routing region
  • Measure actual coupler or waveguide geometry
  • Run an existing KLayout DRC deck
  • Render images around violations

Deferred Features

Postpone these until the observer path is stable:

  • layout editing
  • new geometry authoring
  • auto-fixing violations
  • full PCell orchestration
  • semantic device recognition from polygons alone
  • net extraction or simulation coupling
  • collaborative GUI control beyond viewport sync

Testing Strategy

Use artifact-based tests with a small fixture corpus:

  • straight waveguide
  • bend
  • directional coupler
  • MMI
  • grating-related region
  • hierarchical reticle fragment

For each tool, assert against:

  • JSON snapshots
  • measurement tolerances
  • marker counts
  • rendered PNG reference outputs

Render tests should use explicit coordinates and sizes so the results remain stable.

Recommendation

Treat this project as a KLayout-native observability service for Python PIC workflows, not as a generic EDA shell wrapper. The first release should optimize for truthful inspection, deterministic rendering, and reusable layout sessions. Editing can come later if the observation layer proves reliable.