MCP 工具完整参考

总览与约定

MCP 工具名是稳定的 namespace.verb。每个工具都归属唯一一个领域，同一个领域 token 既是 klink.find_tools domain=<token> 的导航键，也是 --profile <token> 的过滤器。

阅读约定

• 参数表里 name* 表示必填，其余为可选。
• 坐标：带 _um 后缀是微米（最自然）；带 _dbu 是整数数据库单位。micron = dbu × layout.dbu，dbu 来自 layout.info。
• 图层写法三选一：图层索引 int、"L/D" 字符串（如 "1/0"），或 {layer, datatype} 对象。
• 类型列说明工具跑在哪：rpc 在 KLayout 插件内执行；local 在 MCP 进程内执行。其余徽章： read 只读 · write 写入 · verify 验证 · escape 逃生舱 · mutates 会改动版图（可 Ctrl+Z 撤销）· long 长耗时（走独立超时）。

动态发现工具

目录是实时查询的，不要死记——它由 live plugin 的 method registry 生成，不存在会漂移的手写清单。Python 侧：

from klink import KLinkClient
with KLinkClient() as c:
    print([m["name"] for m in c.methods()["methods"]])   # meta.methods

MCP 侧，tools/list 会公布每一个工具，而 klink.find_tools 负责导航：

klink.find_tools                          # 无参 → 领域索引（每个领域一行）
klink.find_tools domain="routing_backends"  # 该领域的工具 + 详细用法
klink.find_tools query="lvs route"          # 跨全部工具的关键词排序匹配

不确定用哪个工具时，klink.guide 会报告当前打开了什么、磁盘上已有哪些意图状态（declared nets / LVS 报告 / spec），并给出每个可用意图的字面调用。

Profiles 过滤

--profile 沿两条正交轴过滤 MCP 暴露的工具——意图与领域。默认是 read,write,verify,escape。

python -m klink.mcp --profile read,write,verify,escape      # 默认
python -m klink.mcp --profile read,device_photonics         # 混合两轴
python -m klink.mcp --profile routing_backends              # 只暴露一个领域

所有本地工具在任意意图 profile 下都始终包含；核心导航工具 klink.find_tools / klink.status / klink.reconnect 永远在。旧别名仍有效：basic→read、draw→write、advanced→escape、drc→verify。

1 · 连接、自检、发现与视图 connection_and_view · 30 tools

示例。

klink.status
klink.guide
view.list_tabs

# Python client 等价
from klink import KLinkClient
with KLinkClient() as c:
    print(c.hello(client="my-script"))
    print(c.layout_info(verbosity="summary"))
    print(c.ping(nonce=42))

# session 注册表 + 两阶段搬运（先 prepare + dry-run，看清目标/cell/layer/统计再 commit）
klink.session_list
klink.session_label session_id="klayout-8766" label="scratch" aliases=["test"]
klink.session_resolve query="scratch"
klink.transfer_prepare source_session="klayout-8765" target_session="klayout-8766" copy_mode="flat_selection"
klink.transfer_commit package_id="pkg_0001"

2 · 多会话注册表与跨会话搬运（plugin 侧） multi_session_transfer · 7 tools

3 · 几何与单元结构 geometry_authoring · 51 tools

读取（geometry, not pixels）

写入 · 单元与图层

写入 · 形状（批量优先）

写入 · 实例与 PCell（批量优先）

写入 · Layout 级与编辑历史

几何检查（只读报告）

示例。

# 1) 读
layout.info verbosity="summary"
cell.list top_only=true

# 2) 建 cell + 确保层
cell.create name="MYBLOCK"
layer.ensure layer=1 datatype=0 name="M1"

# 3) 批量画一排矩形（微米）——不要循环单插！
shape.insert_boxes cell="MYBLOCK" layer="1/0" boxes_um=[[0,0,10,4],[20,0,30,4],[40,0,50,4]]

# 4) 混合形状一次插入
shape.insert_many cell="MYBLOCK" items=[
  {"kind":"box","layer":"1/0","bbox_um":[0,10,50,14]},
  {"kind":"path","layer":"2/0","points_um":[[0,20],[50,20]],"width_um":2},
  {"kind":"text","layer":"63/0","position_um":[0,26],"text":"MYBLOCK","size_um":4}
]

# 5) 让它可见（新 cell 在 show_cell 前不可见）
view.show_cell cell="MYBLOCK"

# 放置 Basic.CIRCLE PCell（先查参数）
pcell.info library="Basic" pcell="CIRCLE"
instance.insert_pcell parent="MYBLOCK" library="Basic" pcell="CIRCLE" \
    params={"l":"1/0","r":5.0,"n":64} position_um=[100,0]

# 一次放一个 8×8 网格
instance.insert parent="TOP" child="MYBLOCK" position_um=[0,0] \
    array={"rows":8,"cols":8,"pitch_x_um":60,"pitch_y_um":40}

4 · 选择与 SEND 交互记忆 selection_and_send_memory · 10 tools

示例。

# 用户在 KLayout 里选中 A，点 SEND；再选中 B，点 SEND
interaction.selection.recent limit=2       # → [sel_0007(B), sel_0006(A)]
interaction.selection.label id="sel_0006" label="probe pad"
# 现在按 id 去 mark port / 声明 net，而不是靠截图猜位置

5 · 标尺（annotation）与画布测量 rulers_and_measurement · 7 tools

示例。

annotation.list                                    # 列出当前视图里的标尺
annotation.insert points_um=[[0,0],[10,0]] category="klink" text="cut here"
annotation.measure point_um=[5,5]                  # 自动测量最近的缝隙/线宽

6 · Port、Anchor 与 Region（标记 PCell） ports_and_anchors · 26 tools

示例。

port.mark cell="NET1" name="A" center_um=[0,0]   orientation="E" width_um=2 net="sig"
port.mark cell="NET1" name="B" center_um=[80,20] orientation="W" width_um=2 net="sig"
anchor.mark cell="NET1" kind="waypoint_region" center_um=[40,40] radius_um=6 net="sig"
port.list cell="NET1"

routing.tapered_hybrid_cell cell="NET1" angle_mode="manhattan" obstacle_layers=["10/0"]

# Region：拖标尺圈一块地方，认领成一个 Region 标记
region.claim cell="TOP" layer="999/10" rulers=[{"id":12,"role":"include"}]
region.get name="R001"

7 · 可执行版图意图（Region → 确定性阵列） layout_intent · 10 tools

编排（MCP 本地工具）

底层原语（plugin RPC，编排工具背后调用）

示例。

# 1) 认领区域（见 ports_and_anchors 的 region.claim）
region.claim cell="TOP" rulers=[{"id":12,"role":"include"}]

# 2) 规划：任意已有 cell 铺间距网格，带唯一编号
intent.prepare region="R001" source_cell="SENSOR" pitch_um=[20,20] \
    obstacle_layers=["10/0"] numbering={"prefix":"S","width":3,"start":1} \
    label={"layer":"20/0","slot_region":"R00X"}
# -> preview + plan_id + plan_hash，写入任何东西之前先看这份预览

# 3) 应用：一次事务写入
intent.apply plan_id="..." plan_hash="..." confirm="..."

# 4) 改主意：换个编号起点重新生成，apply 原子替换旧容器
intent.regenerate intent_id="..." parameters_patch={"numbering":{"start":201}}
intent.apply plan_id="..." plan_hash="..." confirm="..."

8 · 路由后端 routing_backends · 9 tools

routing.gdsfactory_ports 的 router 策略（选错参数会报错并指出哪些 router 支持它，绝不静默忽略）：

示例。

# klink 自带的主路由，Manhattan，避开你的 keepout 层
routing.tapered_hybrid_cell cell="BLOCK" angle_mode="manhattan" spacing_um=20 obstacle_layers=["900/0"]

# 需要更大障碍间距时
routing.damped_segment_cell cell="BLOCK" damping_distance_um=15 obstacle_layers=["900/0"]

# 多端网络（>2 port）
routing.steiner_cell cell="BLOCK" route_layer="1/0"

# gdsfactory river bundle，等长匹配
routing.gdsfactory_ports cell="BLOCK" route_layer="1/0" router="bundle" \
    separation_um=5 radius_um=10 path_length_match=true

9 · DRC 与 LVS 验证 drc_and_lvs_verification · 2 tools

示例。

# DRC：M1 最小间距 0.2um（交互模式，对当前 layout）
drc.run script="""
m1 = input(1, 0)
m1.space(0.2.um).output("M1_space", "M1 spacing < 0.2um")
"""

# LVS：抽取导体层，和参考 SPICE 比对，打开浏览器
lvs.run cell="BLOCK" conductors=["1/0","3/0"] vias=["2/0"] \
    devices={...} reference={"spice":"ref.spice"} out_lvsdb="block.lvsdb" show=true

10 · 自定义器件网表 → 自动 P&R → LVS device_structdevice · 6 tools

示例。

# 第 1 步：不带 confirm → 拿 proposal（网格 rows×cols、行距、路由层、器件混合）
structdevice.build_from_netlist cell="RINGOSC" netlist={
  "instances":[{"name":"INV0","device":"inv_x1"}, ...],
  "nets":[{"name":"a","terminals":["INV0/in","INV2/out"]}, ...],
  "groups":[]
} mode="3L"
# → needs_confirmation + proposal + next_action(confirm=...)

# 第 2 步：同样参数 + confirm token → 真正 place/route/draw/LVS
structdevice.build_from_netlist cell="RINGOSC" netlist={...} mode="3L" confirm="CONFIRM-xyz"

# SEND 驱动的交互连线：用户为每个网络 SEND 一次（框住该网络的所有端子）
structdevice.declare_nets recent_sends=3 cell="BLOCK" conductors=["1/0","3/0"] vias=["2/0"]
structdevice.connect_nets cell="BLOCK" route_layer="3/0" route_width_um=0.5
structdevice.lvs_check cell="BLOCK" mode="both"
structdevice.spec_write cell="BLOCK" layer_roles={"1/0":"gate","3/0":"metal1"}

11 · 成像（剖面 / 3D / SEM / Blender） imaging · 4 tools

12 · 纳米器件（Hall bar / EBL / flake） device_nanodevice · 2 tools

示例。

nanodevice.hallbar cell="HB1" spec={
  "bar_length_um":60, "bar_width_um":8, "contact_count":6,
  "contact_width_um":4, "pad_size_um":40, "pitch_um":24, "gap_um":6
} route_layer="1/0" dry_run=true

nanodevice.detect_commit cell="FLAKE" traces_path="out/traces.json"

13 · 硅光（gdsfactory 导入 / 连接 / 重路由） device_photonics · 3 tools

示例。

# 1) 一次接管成品脚本（脚本里 c = build_mzi(); 供 klink 取用）
photonics.import_gf script_path="my_mzi.py" cell="MZI" route_layer="1/0"

# 2) 在 KLayout GUI 里拖动某个 phase shifter……然后：
photonics.reroute cell="MZI"     # 光学 + 金属一起重画，保住你的拖动

# 也可从 blackbox stub 约定派生端口后再连（这个工具列在 ports_and_anchors 域）
port.harvest_blackbox cell="MZI" tags=["gc","mmi"] wg_layer="1/0" stub_size_um=0.5
photonics.connect recent_sends=4 cell="MZI" radius_um=10 separation_um=5

14 · L-Edit 桥（文件交换 RPC） bridge_ledit · 18 tools

15 · Escape hatch（pya exec、事件、recorder） escape_hatch · 9 tools

示例。

recorder.status                 # 先确认没在录别人的
recorder.start
# …做一些 typed RPC 编辑 + 手工 GUI 编辑…
recorder.stop                   # 产出 <name>.py 和可独立跑的 <name>_pya.py

# 没有 typed RPC 覆盖时才用逃生舱
exec.python code="print(layout.top_cell().name); print(len(list(layout.each_cell())))"

recorder 产出两个文件：<name>.py（基于 KLinkClient 的回放）和 <name>_pya.py（可在 KLayout 内独立运行的 pya 版）。