MCP 工具参考
以下是 linkcad-mcp 向智能体提供的工具。智能体会从服务器读取这些工具的说明和参数架构,因此您无需转告这些内容。本页用于了解智能体能做什么,以及阅读它的工具调用。
图纸由 open_drawing 返回的句柄标识,例如 d1a2b3c-1。路径必须位于以 --root 或 --read-root 指定的文件夹下(连接 AI 智能体)。坐标是以数据库单位表示的整数;inspect_drawing 中的 summary.units_per_meter 用于换算。
信息
| 工具 | 参数 | 结果 |
|---|---|---|
get_status | 无 | LinkCAD 版本、许可证状态和已持有的许可证(Basic、Tools、Edit、View)、文件夹以及已打开的图纸。 |
list_formats | direction:import 或 export(可选) | 每种已安装格式的准确名称、文件过滤器,以及许可证是否涵盖该格式。其他工具使用这些名称。 |
list_options | filter:选项名称的一部分,例如 GdsIn 或 DxfOut;offset、limit | 转换选项及其类型、默认值、当前值,以及工具调用是否可以设置它们。 |
图纸
| 工具 | 参数 | 结果 |
|---|---|---|
open_drawing | paths(一个或多个文件)、format、export_format、options、layer_map | 图纸句柄、其概要和导入日志。省略 format 时,会根据文件检测格式。 |
inspect_drawing | drawing、view、cell、layer、offset、limit | view 为 summary(单位、边界、数量)、layers、cells、hierarchy(某个单元引用的单元)、shape_counts(按单元、图层和形状类型)或 shapes(某个单元的形状,分页)。 |
close_drawing | drawing | 释放图纸。最多可同时打开八个图纸。 |
如果要导出图纸,请向 open_drawing 传入 export_format。与转换向导一样,LinkCAD 在读取文件时分配导出图层编号和单元名称,因此之后无法更改导出格式。未指定导出格式而打开的图纸可以检查、修改和预览,但 export_drawing 会以 no_export_format 拒绝它。
options 按名称设置格式选项,仅对本次调用有效,例如 {"GdsInIgnoreText": true}。layer_map 在读取时应用图层映射文件,需要 export_format。
修改图纸
| 工具 | 参数 | 结果 |
|---|---|---|
apply_tools | drawing、commands | 按顺序运行工具命令,并返回新的概要和日志。 |
set_layers | drawing、layers、delete | 修改图层。layers 的每个条目指定一个图层,并设置 enabled(禁用的图层不会导出)、color(#RRGGBB,预览颜色)或 rename_to。delete 列出要连同其形状一起删除的图层。 |
list_plugin_tools | 无 | 已安装的 Python 工具插件及其选项。 |
run_plugin_tool | tool(形式为 module:Class)、drawing、options | 运行插件工具并返回其结果文本。选项使用简短名称,例如 calculate_area。 |
commands 是 --apply-tool 的命令,每个数组元素一条,例如 ["SetUnits(um)", "MergeOverlappingPolygons()", "Offset(0.5)"]。没有单位的长度以微米计。SetUnits、SetFillRule 和 SetLayerFilter 等模式命令作用于其后的命令。在运行第一条命令之前,会根据许可证检查所有命令。如果某条命令失败,之前的命令保持已应用状态,错误会指明失败的命令。
set_layers 在做任何更改之前会检查每个图层名称。名称拼写错误时不会做任何更改,也绝不会创建图层。
预览
| 工具 | 参数 | 结果 |
|---|---|---|
render_preview | drawing、width(64 到 2048,默认 1024)、height(64 到 2048,默认 768)、window、layers、fill(默认 true)、background(black 或 white) | 以 LinkCAD 查看器的绘制方式生成的主单元 PNG,以及以每像素数据库单位表示的比例。window 为以数据库单位表示的 [xmin, ymin, xmax, ymax];layers 将图片限制为这些图层。 |
写入文件
| 工具 | 参数 | 结果 |
|---|---|---|
export_drawing | drawing、path、overwrite | 以打开图纸时选择的导出格式写入图纸,并返回写入的文件和导出日志。 |
convert_file | input(一个或多个文件)、output、output_format、input_format、options、layer_map、commands、overwrite | 在一次调用中完成读取、运行工具命令和写入,不会保留打开的图纸。 |
get_log | drawing、which(import 或 export)、offset、limit | 完整的导入或导出日志,分页返回。工具结果中包含日志的前几条。 |
导出永远不会替换读取图纸的源文件,只有在 overwrite: true 时才会替换其他已有文件。写入器先写入目标位置旁边的隐藏文件夹,只有导出成功后才会将其所有文件一起移动到位。对于生成多个文件的写入器(例如每个图层一个文件),可以将文件夹作为 path 传入。
Python
| 工具 | 参数 | 结果 |
|---|---|---|
execute_python | code、drawing | 在 LinkCAD 的嵌入式解释器中使用 linkcad 包运行 Python 代码。指定 drawing 时,该图纸即为全局变量 drawing。返回标准输出、标准错误以及错误(如有)。 |
只有在服务器以 --allow-python 启动时才提供 execute_python。代码以您的用户权限运行,不受文件夹限制。
资源和提示
服务器还提供文档和提示模板。客户端将资源显示为可附加的上下文,将提示显示为命令,例如 Claude Code 中的 /mcp__linkcad__inspect_layout。
| 名称 | 类型 | 内容 |
|---|---|---|
linkcad://guide/agent | 资源 | 如何使用这些工具:工作流程、单位、选项名称、如何验证转换以及每个错误的含义。 |
linkcad://reference/tool-apply | 资源 | 工具命令的语法。 |
linkcad://reference/python-api | 资源 | Python 包 linkcad。仅在使用 --allow-python 时提供。 |
inspect_layout | 提示 | 打开文件并报告其单位、边界、顶层单元、图层和日志,附带预览。 |
convert_and_verify | 提示 | 转换文件,重新打开输出并与源文件进行比较。 |
错误
失败的调用会返回一个错误,其中包含固定的代码、消息,对于读取和写入还包含转换日志。智能体在其指南中会收到同一张表。
| 代码 | 含义 |
|---|---|
invalid_arguments | 参数与工具的架构不匹配。 |
path_outside_roots、no_roots_configured | 路径不在为服务器指定的文件夹下。 |
path_not_writable | 文件夹为只读(--read-root)。 |
path_not_found | 文件不存在。 |
file_exists | 输出已存在,且未指定 overwrite。 |
would_overwrite_input | 输出是图纸自身的源文件。 |
unknown_format、format_unavailable | 没有已安装的读取器或写入器使用该名称。 |
format_not_licensed | 许可证不涵盖该格式。 |
license_blocked、license_read_only、license_unavailable | 许可证不允许此操作。get_status 会显示状态和原因。 |
basic_license_required、tools_license_required、edit_license_required、view_license_required | 缺少所指明的许可证。未做任何更改。 |
no_export_format | 图纸在未指定 export_format 的情况下打开。 |
read_failed、write_failed | 读取器或写入器失败;日志会说明原因。 |
tool_failed | 某条工具命令失败。之前的命令已应用。 |
option_rejected | 该选项不存在,或者因为它是应用程序设置或会自行写入文件等原因,不能通过服务器设置。 |
unknown_drawing、unknown_layer、unknown_cell | 没有该名称的图纸、图层或单元。名称区分大小写。 |
too_many_drawings | 已打开八个图纸。请先关闭一个。 |
python_unavailable、unknown_plugin_tool、plugin_tool_failed | Python 无法启动、插件工具不存在或插件工具失败。 |
python_error | 传给 execute_python 的 Python 代码无法运行。 |
render_failed | 无法绘制预览。 |
timeout、worker_crashed | LinkCAD 已重新启动,所有已打开的图纸都已关闭。 |
worker_start_failed、worker_protocol_error、internal_error | LinkCAD 无法启动或应答不正确。客户端显示的服务器日志会说明原因。 |
busy | 等待中的调用过多。 |