Complete MCP tool reference

Start here when unsure. klink.status reports connection, active session, interpreter and optional capabilities; klink.guide reports what is open + on-disk intent state + the literal next call; klink.find_tools navigates the rest; klink.reconnect recovers a dropped link. This domain also carries the MCP-side session registry helpers (klink.session_*, klink.transfer_*) — klink drives many KLayout sessions from one MCP bridge; sessions are equal peers, pass the one you mean explicitly. View tools are read-mostly navigation: a freshly created cell is invisible until view.show_cell; view.new_tab opens a disposable scratch tab; view.show_25d opens the native 2.5D viewer from a display list; view.hier_levels raises displayed hierarchy depth if child instances render as name-label boxes. Screenshots (view.screenshot) are a user-requested artifact only — never an agent verification step; prefer geometry queries. Destructive here: view.close_tab — disposable test tabs only.

The plugin-side half of session/transfer: session.label_set and session.mark_klive_target manage the shared registry directly from a KLayout window; transfer.pending_set/status/clear and transfer.paste_pending hold and apply a reviewed flat-selection package in this window; transfer.import_cell_tree_package imports a cell tree from a GDS/OAS package via native Cell.copy_tree. The MCP-side orchestration (klink.session_*, klink.transfer_prepare/commit) lives in connection_and_view — start there for the two-phase, confirmation-safe transfer flow.

The core drawing surface. Read first: layout.info, cell.list/cell.tree, layer.list/layer.display_list, shape.query, instance.query, pcell.*, library.list. Author with BATCH RPCs for anything generated — never one RPC per object. layer.ensure before drawing. edit.undo/redo/status wrap edits in transactions. Beyond basic authoring this domain also carries: geometry.boolean/cell_xor/density (diff and coverage checks), cell.fill_region (dummy fill / test-structure tiling), cell.flatten, layer.load_lyp/save_lyp/set_style/set_visible (view styling), library.list/refresh/register_file, pcell.convert_to_static, shape.change_layer/transform, instance.transform. Destructive: layout.clear, cell.delete — disposable/test cells only; do NOT touch the user's working tab/layout UNLESS the user explicitly instructs it.

Two distinct things. selection.* is the LIVE current selection in KLayout: selection.get, selection.set_box (replaces current selection), selection.clear, selection.send_context (agent-side explicit SEND). interaction.* is durable session memory of selections the user explicitly SENT (toolbar SEND, recorded as ids like sel_0006): interaction.selection.latest/recent (default latest 5, ordered NOT time-pruned)/get/label, and interaction.context (current selection + recent memory together). Use these whenever the user says "just sent", "this area", "here", "that one". Resolve by order/count, not age. Bind user phrases to these ids/queries, NOT to screenshots.

Ports are net endpoints (klink_Port PCells: net + orientation + width). Anchors are routing constraints (klink_Anchor PCells) whose kind is waypoint_region, bend_region, or corridor (a plain corridor is a REQUIRED pass-through; label it choice_group=BUS for an OPTIONAL channel). port.mark/list/update/transform/set_layer/unmark/delete_all/repair_names; the same verbs on anchor.* (+ anchor.repair_ids). port.mark_many marks many ports in one cell with a single RPC/undo step (validate-before-mutate) — use it instead of looping port.mark for generated port arrays. port.harvest_blackbox derives Ports from LIVE gdsfactory/PDK blackbox instance positions via the waveguide stub convention — a photonics-adjacent tool that lives in this domain. Routing tools default port_layer=999/99, anchor_layer=999/1. Keepouts are NOT an anchor kind — pass your OWN design's obstacle layer(s) to routing tools as obstacle_layers; klink ships no default keepout layer (900/0 is klink's reserved keepout layer, used internally by structdevice). These are the INPUT to routing_backends: mark Ports+Anchors, then call a routing.* tool.

All read Port/Anchor PCells in a cell and write routes. Pick by topology/quality: routing.tapered_hybrid_cell is the main path+patch backend; routing.tapered_polygon_cell writes continuous taper polygons (first-class, not a fallback); routing.steiner_cell handles multi-terminal nets (>2 ports); the routing.damped_* family adds explicit extra obstacle clearance; routing.global_channel_cell is a global-decision router (candidate-sink assignment + corridor-capacity load-balancing) on top of tapered hybrid geometry; routing.multilayer_escape_cell routes wall-blocked nets via a bridge layer + vias; routing.gdsfactory_ports routes Port markers with a named gdsfactory strategy (needs gdsfactory in the interpreter). Always inspect the structured result: ok=false, obstacle_hit_count>0, sibling overlaps, short route_count all mean failure. Pass your own design's obstacle_layers (no default).

Both are long-running, pure pya, domain-agnostic. drc.run runs arbitrary DRC DSL (Ruby) you supply against the layout — exceptions inside the script come back as results, they do NOT fail the RPC. lvs.run is the connectivity counterpart: extracts the live layout into a device netlist and compares it against a REFERENCE netlist you supply, writes a native .lvsdb and (default) opens it in the Netlist/LVS browser. A P&R/device stage counts as DONE only on a real live LVS match=True — offline fixtures and marker counts never substitute. For the structdevice flow prefer structdevice.lvs_check.

This is the device-AGNOSTIC custom-device P&R flow. A "device" is any cell with an arbitrary parameter set + terminals; klink assumes no parameter names/count and no device vocabulary. The device library, process profile, and terminal source are EXAMPLE/PDK data passed in explicitly — the tools ship none and return an instructive "write/run an example" error. structdevice.build_from_netlist is the headline one-call flow (confirmation-gated: call once for a proposal, again with the confirm token to build); routing runs on the flexdr engine using a compact physical model where the device's own metal layers double as routing layers. structdevice.declare_nets / connect_nets / lvs_check / spec_write are the SEND-driven interactive path. structdevice.register_pcell wraps the lower-level plugin RPC pcell.register_fitted (listed under geometry_authoring).

Everything runs klink-side (no plugin involvement); heavy deps are optional and the error names the exact pip install command. Recipes/VisualStack instances are example-owned — klink ships mechanism only. imaging.xsection_run makes a process cross-section along an explicit cut line from a .pyxs recipe (engine klayout_pyxs); steps=true + '# klink-step: <name>' recipe markers give a per-step film. imaging.render3d builds a GLB plus a self-contained interactive viewer HTML; mode=fast extrudes a visual-stack declaration, mode=process sweeps the xsection engine so process curvature (LOCOS, CMP) is real; fraction<1 exposes a true cutaway section. imaging.sem_top renders deterministic SEM-style top-view PNGs (greyscale + false color). imaging.blender renders a paper-grade image via a headless bpy subprocess — mode=die polishes a render3d GLB, mode=figure builds a device figure from GDS+stack at 1:1 layout coordinates (lattice layers become atomic-structure motifs).

nanodevice.hallbar is a one-call closed loop: from a HallBarSpec (bar length/width, contact_count, contact/pad dims, pitch, gaps) it computes and draws the whole device (bar + N symmetric contact arms + pads + Port markers + labels), then delegates routing to the generic router (overlap validation on, optional EBL writefield walls as keepouts), committing to a disposable cell (dry_run supported). Failures return problems/next_action and change nothing. nanodevice.detect_commit commits flake traces as polygons from a precomputed traces.json, or runs live detection from a microscope image (needs cv2 + numpy).

Photonic circuit flow. Needs gdsfactory in the MCP interpreter. Two port sources, one interactive loop: photonics.import_gf takes a finished user gdsfactory script over into the loop in one call — device instances become real KLayout cells+instances, routed connections collapse to device-level nets, per-device port templates persist in the spec, and nets are routed by klink. port.harvest_blackbox (listed under ports_and_anchors — it derives Ports from live blackbox instance positions) is the other port source; re-run it after moving instances, then route. photonics.connect reads the latest N SENDs as port pairs, auto-names nets, persists, re-harvests, and routes with gdsfactory. photonics.reroute re-routes a cell after the user moved components (reads the persisted net table). Multi-port optical nets are not routed as stars — insert an explicit splitter/MMI/Y-branch first and route the resulting two-port nets.

Requires L-Edit running with the bridge macro loaded as SOURCE (example_template/ledit_bridge/ledit_bridge.cpp via Tools > Macro > Load Macro..., zero compile). Transport is a JSON file exchange under %LOCALAPPDATA%\klink\ledit_bridge\<namespace>; one namespace per L-Edit instance, only ONE L-Edit may hold a namespace at a time. ledit.status is discovery + handshake — call it first when anything misbehaves; errors name the exact fix. ledit.import_selection does a fresh GET of the user's current L-Edit selection into a new KLayout landing cell. ledit.push_cell pushes a flat KLayout cell back into L-Edit (append-only; use a fresh target cell to regenerate). Deeper T-Cell workflows live in the Python API klink.bridges.ledit — see the L-Edit Bridge guide.

Prefer typed RPCs. exec.python runs raw pya for operations no typed RPC covers / debugging / compact one-offs (exec.reset clears its namespace); it still schedules recorder + layout-diff detection. events.* (channels/status/subscribe/unsubscribe) is the live event stream the bridge subscribes to for SEND memory — usually you read interaction.* instead. recorder.* (start/stop/status) generates a replay SCRIPT (not a literal RPC log); a bulk RPC may expand into replay actions. Check recorder.status before tests so you never clobber a user recording.