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} 对象。
• 徽章含义： read 只读 · write 写入 · verify 验证 · escape 逃生舱 · mutates 会改动版图（可 Ctrl+Z 撤销）· long 长耗时（走独立超时）。

动态发现工具

目录是实时查询的，不要死记。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 · 15 tools

示例：连接自检 + 查看当前状态。

# MCP（agent 视角）
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))

2 · 多会话注册表与跨会话搬运 multi_session_transfer · 15 tools

示例：给窗口打标签，再把选中几何从一个窗口搬到另一个。

klink.session_list
klink.session_label session_id="klayout-8766" label="scratch" aliases=["test"]
klink.session_resolve query="scratch"

# 两阶段搬运：先 prepare + dry-run，看清目标/cell/layer/统计再 commit
klink.transfer_prepare source_session="klayout-8765" target_session="klayout-8766" copy_mode="flat_selection"
klink.transfer_commit package_id="pkg_0001"

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

读取（geometry, not pixels）

写入 · 单元与图层

写入 · 形状（批量优先）

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

写入 · Layout 级与编辑历史

示例：先读当前状态 → 建 cell 与层 → 批量画 → 显示。

# 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 · 11 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 · Port 与 Anchor（路由标记） ports_and_anchors · 16 tools

示例：标两个对着的 Port，加一个必经 waypoint，然后路由。

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"]

6 · 路由后端 routing_backends · 9 tools

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

示例：主路由 + 更强避障 + gdsfactory bundle。

# 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

7 · DRC 与 LVS 验证 drc_and_lvs_verification · 2 tools

示例：最小 DRC（间距检查）与 LVS 调用骨架。

# 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

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

示例：从器件级网表两步 build。

# 第 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"}

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

示例：生成并路由一个 Hall bar；再从预算 traces 提交 flake。

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"

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

示例：接管一个 gdsfactory 脚本，然后拖动后重路由。

# 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 约定派生端口后再连
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

11 · Escape hatch（pya exec、事件、recorder） escape_hatch · 8 tools

示例：录制一段会话，用 pya 做一次性操作。

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 版）。