跳转到内容

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_formatsdirection:import 或 export(可选)每种已安装格式的准确名称、文件过滤器,以及许可证是否涵盖该格式。其他工具使用这些名称。
list_optionsfilter:选项名称的一部分,例如 GdsIn 或 DxfOut;offset、limit转换选项及其类型、默认值、当前值,以及工具调用是否可以设置它们。

图纸

工具参数结果
open_drawingpaths(一个或多个文件)、format、export_format、options、layer_map图纸句柄、其概要和导入日志。省略 format 时,会根据文件检测格式。
inspect_drawingdrawing、view、cell、layer、offset、limitview 为 summary(单位、边界、数量)、layers、cells、hierarchy(某个单元引用的单元)、shape_counts(按单元、图层和形状类型)或 shapes(某个单元的形状,分页)。
close_drawingdrawing释放图纸。最多可同时打开八个图纸。

如果要导出图纸,请向 open_drawing 传入 export_format。与转换向导一样,LinkCAD 在读取文件时分配导出图层编号和单元名称,因此之后无法更改导出格式。未指定导出格式而打开的图纸可以检查、修改和预览,但 export_drawing 会以 no_export_format 拒绝它。

options 按名称设置格式选项,仅对本次调用有效,例如 {"GdsInIgnoreText": true}。layer_map 在读取时应用图层映射文件,需要 export_format。

修改图纸

工具参数结果
apply_toolsdrawing、commands按顺序运行工具命令,并返回新的概要和日志。
set_layersdrawing、layers、delete修改图层。layers 的每个条目指定一个图层,并设置 enabled(禁用的图层不会导出)、color(#RRGGBB,预览颜色)或 rename_to。delete 列出要连同其形状一起删除的图层。
list_plugin_tools无已安装的 Python 工具插件及其选项。
run_plugin_tooltool(形式为 module:Class)、drawing、options运行插件工具并返回其结果文本。选项使用简短名称,例如 calculate_area。

commands 是 --apply-tool 的命令,每个数组元素一条,例如 ["SetUnits(um)", "MergeOverlappingPolygons()", "Offset(0.5)"]。没有单位的长度以微米计。SetUnits、SetFillRule 和 SetLayerFilter 等模式命令作用于其后的命令。在运行第一条命令之前,会根据许可证检查所有命令。如果某条命令失败,之前的命令保持已应用状态,错误会指明失败的命令。

set_layers 在做任何更改之前会检查每个图层名称。名称拼写错误时不会做任何更改,也绝不会创建图层。

预览

工具参数结果
render_previewdrawing、width(64 到 2048,默认 1024)、height(64 到 2048,默认 768)、window、layers、fill(默认 true)、background(black 或 white)以 LinkCAD 查看器的绘制方式生成的主单元 PNG,以及以每像素数据库单位表示的比例。window 为以数据库单位表示的 [xmin, ymin, xmax, ymax];layers 将图片限制为这些图层。

写入文件

工具参数结果
export_drawingdrawing、path、overwrite以打开图纸时选择的导出格式写入图纸,并返回写入的文件和导出日志。
convert_fileinput(一个或多个文件)、output、output_format、input_format、options、layer_map、commands、overwrite在一次调用中完成读取、运行工具命令和写入,不会保留打开的图纸。
get_logdrawing、which(import 或 export)、offset、limit完整的导入或导出日志,分页返回。工具结果中包含日志的前几条。

导出永远不会替换读取图纸的源文件,只有在 overwrite: true 时才会替换其他已有文件。写入器先写入目标位置旁边的隐藏文件夹,只有导出成功后才会将其所有文件一起移动到位。对于生成多个文件的写入器(例如每个图层一个文件),可以将文件夹作为 path 传入。

Python

工具参数结果
execute_pythoncode、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_failedPython 无法启动、插件工具不存在或插件工具失败。
python_error传给 execute_python 的 Python 代码无法运行。
render_failed无法绘制预览。
timeout、worker_crashedLinkCAD 已重新启动,所有已打开的图纸都已关闭。
worker_start_failed、worker_protocol_error、internal_errorLinkCAD 无法启动或应答不正确。客户端显示的服务器日志会说明原因。
busy等待中的调用过多。