kicad-mcp-server/python/annotations/kicad_ipc_tool_annotations.json

{
  "annotations": {
    "AddToSelection": {
      "description": "Adds the given items to the current selection in the editor.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "items": "List of KIIDs of items to add to the selection."
      },
      "returns": "SelectionResponse containing the updated set of selected items."
    },
    "BeginCommit": {
      "description": "Begins a staged set of changes. Modifications made after this call are held in a pending commit until EndCommit.",
      "parameters": {
        "header": "ItemHeader specifying which document to associate the commit with."
      },
      "returns": "BeginCommitResponse with an opaque KIID tracking the commit."
    },
    "BoardEditorAppearanceSettings": {
      "description": "Message describing the appearance settings of the PCB editor (inactive layers, net colors, flip, ratsnest).",
      "parameters": {
        "inactive_layer_display": "How inactive layers are displayed (dimmed, hidden, normal).",
        "net_color_display": "How net colors are applied in the editor.",
        "board_flip": "Whether the board view is flipped.",
        "ratsnest_display": "How the ratsnest is shown."
      }
    },
    "BoardLayers": {
      "description": "A simple wrapper containing a list of BoardLayer enum values.",
      "parameters": {
        "layers": "List of BoardLayer enum values."
      }
    },
    "CheckPadstackPresenceOnLayers": {
      "description": "Tests whether the given pads/vias have copper presence on the given set of board layers.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "items": "List of pad/via KIIDs to test.",
        "layers": "List of BoardLayer values to test against."
      },
      "returns": "PadstackPresenceResponse with an entry per (item, layer) pair."
    },
    "ClearSelection": {
      "description": "Removes all items from the current selection.",
      "parameters": {
        "header": "ItemHeader specifying the target document."
      }
    },
    "CloseDocument": {
      "description": "Closes the given open document in KiCad.",
      "parameters": {
        "document": "DocumentSpecifier identifying the document to close."
      }
    },
    "CreateItems": {
      "description": "Creates new items on a given document, optionally inside a container (symbol or footprint).",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "items": "List of items to create (Any-wrapped typed messages).",
        "container": "Optional KIID of a container (symbol/footprint) the items should be added to. Omit for top-level insertion."
      },
      "returns": "CreateItemsResponse with per-item status and the created items (with assigned KIIDs)."
    },
    "DeleteItems": {
      "description": "Deletes items from a given document by KIID.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "item_ids": "List of KIIDs of items to delete."
      },
      "returns": "DeleteItemsResponse with a per-item deletion status.",
      "warnings": [
        "Deletion is destructive; use BeginCommit/EndCommit to make it undoable."
      ]
    },
    "EndCommit": {
      "description": "Finalizes or discards a pending commit that was started with BeginCommit.",
      "parameters": {
        "id": "Opaque KIID of the commit, as returned by BeginCommit.",
        "action": "CommitAction indicating whether to commit or roll back the staged changes.",
        "message": "Optional human-readable changeset message.",
        "header": "ItemHeader specifying which document the commit is associated with."
      }
    },
    "ExpandTextVariables": {
      "description": "Expands KiCad text variables (like ${VAR}) in the supplied strings using the given document's variable table.",
      "parameters": {
        "document": "DocumentSpecifier identifying the document whose variable table to use.",
        "text": "List of input strings potentially containing text variable references."
      },
      "returns": "ExpandTextVariablesResponse with one expanded string per input, in order."
    },
    "GetActiveLayer": {
      "description": "Returns the currently active (drawing) layer of the PCB editor for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "BoardLayerResponse containing the active BoardLayer."
    },
    "GetBoardDesignRules": {
      "description": "Retrieves the design rules (constraints, predefined sizes, mask/paste, teardrops, severities, exclusions) for a board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "BoardDesignRulesResponse with the rules and custom rules status."
    },
    "GetBoardEditorAppearanceSettings": {
      "description": "Returns the current appearance settings of the PCB editor.",
      "parameters": {},
      "returns": "BoardEditorAppearanceSettings with the current editor appearance state."
    },
    "GetBoardEnabledLayers": {
      "description": "Returns the set of layers currently enabled in the given board's stackup.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "BoardEnabledLayersResponse with copper_layer_count and the full list of enabled layers."
    },
    "GetBoardLayerName": {
      "description": "Returns the user-facing display name of a single board layer (may be default or user-customized).",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "layer": "The BoardLayer whose display name should be returned."
      },
      "returns": "BoardLayerNameResponse containing the layer's GUI name."
    },
    "GetBoardOrigin": {
      "description": "Retrieves a specific origin point (drill/place, grid, etc.) for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "type": "BoardOriginType selecting which origin to retrieve."
      },
      "returns": "Vector2 with the origin's x and y coordinates in nanometers."
    },
    "GetBoardStackup": {
      "description": "Retrieves the full board stackup (finish, impedance, edge settings, and layer list) for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "BoardStackupResponse with the board's BoardStackup."
    },
    "GetBoundingBox": {
      "description": "Returns the bounding boxes of the given items in the target document.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "items": "List of KIIDs to measure.",
        "mode": "BoundingBoxMode controlling whether movable child text (e.g. footprint fields) is included."
      },
      "returns": "GetBoundingBoxResponse with a Box2 (in nanometers) for each item."
    },
    "GetConnectedItems": {
      "description": "Retrieves all copper-connected items reachable from one or more source items.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "items": "One or more source item KIIDs used as the connectivity roots.",
        "types": "Optional KiCadObjectType filter. If empty, all connected item types are returned."
      },
      "returns": "GetItemsResponse with the list of connected items."
    },
    "GetCustomDesignRules": {
      "description": "Retrieves the custom (user-defined) DRC rules associated with the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "CustomRulesResponse with the parse status and the list of custom rules."
    },
    "GetGraphicsDefaults": {
      "description": "Retrieves the per-layer-class graphics defaults (text attributes and line thickness) for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "GraphicsDefaultsResponse with the board's GraphicsDefaults."
    },
    "GetItems": {
      "description": "Retrieves items of the given KiCad object types from the target document.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "types": "List of KiCadObjectType values identifying which item types to retrieve."
      },
      "returns": "GetItemsResponse with the matching items wrapped in Any."
    },
    "GetItemsById": {
      "description": "Retrieves specific items from the target document by their KIIDs.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "items": "List of KIIDs to look up."
      },
      "returns": "GetItemsResponse with the requested items (Any-wrapped)."
    },
    "GetItemsByNet": {
      "description": "Retrieves copper items (pads, vias, tracks, zones by default) that belong to the given nets.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "types": "Optional list of item types to filter by. Defaults to pads, vias, tracks, and zones.",
        "nets": "List of Nets used as filters; items belonging to any of them are returned."
      },
      "returns": "GetItemsResponse with the matching copper items."
    },
    "GetItemsByNetClass": {
      "description": "Retrieves copper items that belong to any of the given net classes.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "types": "Optional list of KiCadObjectType filters. Defaults to pads, vias, tracks, and zones.",
        "net_classes": "List of net class names used as filters."
      },
      "returns": "GetItemsResponse with the matching copper items."
    },
    "GetKiCadBinaryPath": {
      "description": "Returns the full path to a KiCad binary (e.g. kicad-cli) on the current system.",
      "parameters": {
        "binary_name": "Short name of the binary, e.g. 'kicad-cli'. On Windows, a '.exe' extension is assumed if missing."
      },
      "returns": "PathResponse with the absolute path to the binary."
    },
    "GetNetClassForNets": {
      "description": "Computes the effective (merged) netclass for each provided net, combining all classes a net belongs to by priority.",
      "parameters": {
        "net": "List of Nets to resolve effective netclasses for."
      },
      "returns": "NetClassForNetsResponse mapping each net to its effective netclass."
    },
    "GetNetClasses": {
      "description": "Returns all netclasses defined in the current project.",
      "parameters": {},
      "returns": "NetClassesResponse with the list of NetClass definitions."
    },
    "GetNets": {
      "description": "Retrieves the nets defined on a board, optionally filtered by one or more netclass names.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "netclass_filter": "Optional list of netclass names. If provided, only nets in any of these classes are returned."
      },
      "returns": "NetsResponse with the matching nets."
    },
    "GetOpenDocuments": {
      "description": "Retrieves a list of currently open documents of the requested type (board, schematic, etc.).",
      "parameters": {
        "type": "DocumentType specifying which kind of document to query."
      },
      "returns": "GetOpenDocumentsResponse with DocumentSpecifiers for each open document of that type."
    },
    "GetPadShapeAsPolygon": {
      "description": "Computes the polygon outline of one or more pads on a given layer, merging custom shapes and approximating curves as segments.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "pads": "List of pad KIIDs to process.",
        "layer": "BoardLayer on which to evaluate the pad shape."
      },
      "returns": "PadShapeAsPolygonResponse containing parallel lists of pad KIIDs and their PolygonWithHoles outlines."
    },
    "GetPluginSettingsPath": {
      "description": "Returns a writeable directory path a plugin can use for persistent configuration/data. The directory may not yet exist.",
      "parameters": {
        "identifier": "The plugin's identifier (used to namespace the settings directory)."
      },
      "returns": "StringResponse with the plugin's settings directory path."
    },
    "GetSchematicHierarchy": {
      "description": "Retrieves the hierarchical sheet structure of a schematic project.",
      "parameters": {
        "document": "DocumentSpecifier with type DT_SCHEMATIC; only the project field is used."
      },
      "returns": "SchematicHierarchyResponse with the top-level SheetInstances and their children."
    },
    "GetSelection": {
      "description": "Retrieves the currently selected items in the editor, optionally filtered by type.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "types": "Optional KiCadObjectType filter. If empty, all selected items are returned."
      },
      "returns": "SelectionResponse with the selected items."
    },
    "GetTextAsShapes": {
      "description": "Renders the given text or textbox objects as shapes (polygons or stroke segments, depending on font).",
      "parameters": {
        "text": "List of TextOrTextBox objects to render."
      },
      "returns": "GetTextAsShapesResponse pairing each input with its CompoundShape representation."
    },
    "GetTextExtents": {
      "description": "Calculates the bounding box of a temporary text item as it would be rendered.",
      "parameters": {
        "text": "A temporary Text item whose extents should be measured."
      },
      "returns": "Box2 (in nanometers) giving the text's bounding box."
    },
    "GetTextVariables": {
      "description": "Retrieves the text variable table defined for the given document.",
      "parameters": {
        "document": "DocumentSpecifier identifying the target document."
      },
      "returns": "TextVariables with the name/value map of text variables."
    },
    "GetTitleBlockInfo": {
      "description": "Retrieves the drawing-sheet title block fields (title, date, revision, company, comments) for the given document.",
      "parameters": {
        "document": "DocumentSpecifier identifying the target document."
      },
      "returns": "TitleBlockInfo with the title block's field values."
    },
    "GetVersion": {
      "description": "Retrieves the version of the running KiCad instance.",
      "parameters": {},
      "returns": "GetVersionResponse containing a KiCadVersion (major/minor/patch and full version string)."
    },
    "GetVisibleLayers": {
      "description": "Returns the list of layers currently set visible in the PCB editor for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board."
      },
      "returns": "BoardLayers with the visible BoardLayer list."
    },
    "HitTest": {
      "description": "Tests whether a point lies within a given tolerance of an item's geometry.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "id": "KIID of the item to test against.",
        "position": "Point to test, in nanometer coordinates.",
        "tolerance": "Tolerance distance in nanometers."
      },
      "returns": "HitTestResponse with a HitTestResult indicating hit or miss."
    },
    "InjectDrcError": {
      "description": "Injects a synthetic DRC marker onto the board at a given location, referencing specific items. Useful for plugins emitting custom rule violations.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "severity": "DrcSeverity level of the injected marker.",
        "message": "Human-readable message describing the violation.",
        "position": "Location of the marker in nanometer coordinates.",
        "items": "List of KIIDs of items associated with this DRC error."
      },
      "returns": "InjectDrcErrorResponse with the KIID of the newly created marker."
    },
    "InteractiveMoveItems": {
      "description": "Selects the given items and starts an interactive move in the PCB editor; KiCad becomes unresponsive to API calls until the user confirms or cancels.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "items": "List of KIIDs of items to move."
      },
      "warnings": [
        "Takes ownership of the active commit if one exists: the move tool pushes it on confirm or rolls it back on cancel. Account for this when combining with explicit commits."
      ],
      "interactive": true
    },
    "ItemStatus": {
      "description": "Per-item status returned alongside creation and update results.",
      "parameters": {
        "code": "ItemStatusCode indicating success or a specific failure reason.",
        "error_message": "Human-readable error message when the code indicates failure."
      }
    },
    "OpenDocument": {
      "description": "Opens a document of a given type from a file path in KiCad.",
      "parameters": {
        "type": "DocumentType of the document to open (board, schematic, etc.).",
        "path": "Filesystem path to the document to open."
      },
      "returns": "OpenDocumentResponse with a DocumentSpecifier for the opened document."
    },
    "PadstackPresenceEntry": {
      "description": "One entry in a PadstackPresenceResponse, describing an (item, layer) pair's padstack presence.",
      "parameters": {
        "item": "KIID of the pad or via being reported on.",
        "layer": "BoardLayer being reported on.",
        "presence": "PadstackPresence value indicating whether the item has copper on this layer."
      }
    },
    "ParseAndCreateItemsFromString": {
      "description": "Parses an s-expression item container (like the Paste action in the editor) and creates the resulting items in the document.",
      "parameters": {
        "document": "DocumentSpecifier identifying the target document.",
        "contents": "S-expression text describing items to create."
      },
      "returns": "CreateItemsResponse with per-item creation status."
    },
    "Ping": {
      "description": "Pings KiCad to verify the API connection is alive.",
      "parameters": {}
    },
    "RefillZones": {
      "description": "Refills some or all copper zones on the given board. Blocking: returns Empty immediately and KiCad returns AS_BUSY to further API calls until the fill completes.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "zones": "List of zone KIIDs to refill. If empty, all zones on the board are refilled."
      },
      "blocking": true
    },
    "RefreshEditor": {
      "description": "Requests that the given editor frame redraw itself, if open.",
      "parameters": {
        "frame": "FrameType identifying which editor frame to refresh."
      }
    },
    "RemoveFromSelection": {
      "description": "Removes the given items from the current selection.",
      "parameters": {
        "header": "ItemHeader specifying the target document.",
        "items": "List of KIIDs of items to deselect."
      },
      "returns": "SelectionResponse with the updated selection."
    },
    "RevertDocument": {
      "description": "Reverts the given document to its on-disk state, discarding unsaved changes.",
      "parameters": {
        "document": "DocumentSpecifier identifying the document to revert."
      },
      "warnings": [
        "Discards all unsaved changes in the target document; this cannot be undone."
      ]
    },
    "RunAction": {
      "description": "Runs a TOOL_ACTION through the TOOL_MANAGER of a frame. Intended for low-level prototyping only.",
      "parameters": {
        "action": "Action name, e.g. 'eeschema.InteractiveSelection.ClearSelection'."
      },
      "returns": "RunActionResponse with a RunActionStatus.",
      "warnings": [
        "TOOL_ACTIONs are specifically NOT a stable API. Action names may change or be removed as code is refactored; use only for prototyping."
      ]
    },
    "SaveCopyOfDocument": {
      "description": "Saves a copy of the given document to a new path, without opening the copy.",
      "parameters": {
        "document": "DocumentSpecifier identifying the source document.",
        "path": "Destination file path for the saved copy.",
        "options": "SaveOptions controlling overwrite and whether to save a project alongside the file."
      }
    },
    "SaveDocument": {
      "description": "Saves the given open document to its current location on disk.",
      "parameters": {
        "document": "DocumentSpecifier identifying the document to save."
      }
    },
    "SaveDocumentToString": {
      "description": "Serializes the given document to a string (s-expression) without writing to disk.",
      "parameters": {
        "document": "DocumentSpecifier identifying the document to serialize."
      },
      "returns": "SavedDocumentResponse with the serialized contents."
    },
    "SaveOptions": {
      "description": "Options controlling how SaveCopyOfDocument behaves.",
      "parameters": {
        "overwrite": "If true, destination file(s) may be overwritten if they already exist.",
        "include_project": "If true, save a new project alongside the file when the file type normally requires one (board or schematic)."
      }
    },
    "SaveSelectionToString": {
      "description": "Serializes the current selection to a string (s-expression) suitable for later pasting.",
      "parameters": {},
      "returns": "SavedSelectionResponse with the selected items' KIIDs and serialized contents."
    },
    "SetActiveLayer": {
      "description": "Sets the active (drawing) layer in the PCB editor for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "layer": "The BoardLayer to make active."
      }
    },
    "SetBoardDesignRules": {
      "description": "Replaces the board's design rules (constraints, predefined sizes, mask/paste, teardrops, severities, exclusions).",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "rules": "BoardDesignRules to install on the board."
      },
      "returns": "BoardDesignRulesResponse with the resulting rules and custom rules status."
    },
    "SetBoardEditorAppearanceSettings": {
      "description": "Updates the PCB editor's appearance settings (inactive layer display, net colors, flip, ratsnest).",
      "parameters": {
        "settings": "BoardEditorAppearanceSettings to apply."
      }
    },
    "SetBoardEnabledLayers": {
      "description": "Changes which layers are enabled in the board stackup.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "copper_layer_count": "Number of copper layers to enable; must currently be an even number >= 2.",
        "layers": "Non-copper layers to enable. Copper layers in this list are ignored (use copper_layer_count). F/B.Courtyard, Edge.Cuts, and Margin cannot be disabled and remain enabled regardless."
      },
      "returns": "BoardEnabledLayersResponse with the updated enabled layer set.",
      "warnings": [
        "Any existing content on layers removed by this call is deleted. This operation cannot be undone."
      ]
    },
    "SetBoardOrigin": {
      "description": "Sets a specific origin point (drill/place, grid, etc.) for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "type": "BoardOriginType selecting which origin to set.",
        "origin": "New origin location in nanometer coordinates."
      }
    },
    "SetCustomDesignRules": {
      "description": "Replaces the custom (user-defined) DRC rules for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "rules": "List of CustomRule definitions to install."
      },
      "returns": "CustomRulesResponse with parse status, resulting rules, and any error text."
    },
    "SetNetClasses": {
      "description": "Updates the project's netclass definitions, merging with or replacing the existing set based on merge_mode.",
      "parameters": {
        "net_classes": "List of NetClass definitions to apply.",
        "merge_mode": "MapMergeMode controlling merge vs. replace semantics. With MMM_MERGE, existing classes not named here are kept; named classes are replaced. With MMM_REPLACE, unnamed classes are erased except 'Default', which always persists."
      }
    },
    "SetTextVariables": {
      "description": "Updates the text variable table for a document, merging with or replacing the existing variables.",
      "parameters": {
        "document": "DocumentSpecifier identifying the target document.",
        "variables": "TextVariables map to apply.",
        "merge_mode": "MapMergeMode controlling whether to merge with or replace the existing variables."
      }
    },
    "SetTitleBlockInfo": {
      "description": "Sets the drawing-sheet title block fields (title, date, revision, company, comments) for the given document.",
      "parameters": {
        "document": "DocumentSpecifier identifying the target document.",
        "title_block": "TitleBlockInfo with the new field values."
      }
    },
    "SetVisibleLayers": {
      "description": "Sets which layers are visible in the PCB editor for the given board.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "layers": "List of BoardLayers to mark visible."
      }
    },
    "TextOrTextBox": {
      "description": "A union-style wrapper holding either a Text or TextBox object, used as input for text-related commands.",
      "parameters": {}
    },
    "TextWithShapes": {
      "description": "Pairs an input text/textbox with its rendered CompoundShape, as returned by GetTextAsShapes.",
      "parameters": {
        "text": "The original TextOrTextBox input.",
        "shapes": "CompoundShape rendering (polygons or stroke segments) of the text."
      }
    },
    "UpdateBoardStackup": {
      "description": "Replaces the board stackup with the contents of this message. Not yet implemented.",
      "parameters": {
        "board": "DocumentSpecifier identifying the target board.",
        "stackup": "The new BoardStackup to install."
      },
      "returns": "BoardStackupResponse with the updated stackup in normalized form.",
      "warnings": [
        "Any existing content on layers removed by this call is deleted. This operation cannot be undone."
      ]
    },
    "UpdateItems": {
      "description": "Modifies existing items in a document; fields updated are controlled by the ItemHeader field mask.",
      "parameters": {
        "header": "ItemHeader specifying the target document and field mask.",
        "items": "List of items (Any-wrapped) with updated values. Each item's KIID must identify an existing item."
      },
      "returns": "UpdateItemsResponse with per-item update status."
    }
  },
  "_meta": {
    "kicad_ref": "master",
    "generator": "generate_tool_annotations.py"
  }
}