feat: support arbitrary custom properties on schematic components

Promotes BOM / sourcing fields (MPN, Manufacturer, DigiKey_PN, LCSC,
JLCPCB_PN, Voltage, Tolerance, Dielectric, ...) to first-class citizens
on placed schematic symbols.

New MCP tools:
- set_schematic_component_property: add or update one custom property
  on a component (convenience wrapper around edit_schematic_component).
- remove_schematic_component_property: delete one custom property.
  The four built-in fields (Reference, Value, Footprint, Datasheet) are
  protected and rejected.

edit_schematic_component enhancements:
- New `properties` parameter: map of property name to either a string
  value or a full spec object { value, x?, y?, angle?, hide?, fontSize? }.
  Adds the property when missing, otherwise updates the existing field
  (and optionally its label position / visibility). Lets a single tool
  call attach an entire BOM payload to a component.
- New `removeProperties` parameter: list of custom property names to
  delete in the same call.
- Property values are now backslash-escaped so descriptions containing
  a double-quote or a backslash no longer corrupt the .kicad_sch file.
- New properties default to (hide yes) so they appear in BOM exports
  without cluttering the schematic canvas.

get_schematic_component description clarified to highlight that it
already returns every field on the symbol, including custom ones.

New MCP prompt component_sourcing_properties guides agents through the
conventional property names recognised by downstream BOM tooling and
the recommended call sequence.

Implementation (python/kicad_interface.py):
- _PROTECTED_PROPERTY_FIELDS frozenset
- _escape_sexpr_string / _find_matching_paren static helpers
- _set_property_in_block / _set_hide_on_property /
  _remove_property_from_block surgical text-level edits that preserve
  formatting and the property's UUID
- _handle_edit_schematic_component rewritten to orchestrate
  add/update/remove and return a per-property summary
- New handlers _handle_set_schematic_component_property and
  _handle_remove_schematic_component_property registered in the
  command dispatch table

Tests (tests/test_schematic_component_properties.py):
32 tests covering escape helper, paren matcher, add/update/remove
(single + batched), full spec dicts, default position, default
(hide yes), special-character escaping, UUID preservation, protected
built-in field rejection, no-op removal, both new convenience tools,
and input validation. All 590 tests in the project still pass.

Docs: README, SCHEMATIC_TOOLS_REFERENCE, TOOL_INVENTORY, CHANGELOG.
This commit is contained in:
William Viana
2026-04-20 17:36:38 -07:00
parent 5b7434fdef
commit 4d7843c03a
8 changed files with 1471 additions and 64 deletions

View File

@@ -2,6 +2,63 @@
All notable changes to the KiCAD MCP Server project are documented here.
## [Unreleased]
### New MCP Tools
- `set_schematic_component_property` — Add or update a single custom property
(BOM / sourcing field) on a placed schematic symbol. Convenience wrapper
around `edit_schematic_component` for the common case of attaching one MPN /
Manufacturer / DigiKey_PN / LCSC / JLCPCB_PN / Voltage / Tolerance /
Dielectric value at a time. Newly created properties default to hidden so
they do not clutter the schematic canvas.
- `remove_schematic_component_property` — Delete a custom property from a
placed schematic symbol. The four built-in fields (Reference, Value,
Footprint, Datasheet) are protected and cannot be removed; clear them by
setting their value to `""` via `edit_schematic_component` instead.
### Tool Enhancements
- `edit_schematic_component`: extended with two new optional parameters that
promote arbitrary custom properties to first-class citizens:
- **`properties`** — map of property name to either a string value or a full
spec object `{ value, x?, y?, angle?, hide?, fontSize? }`. Adds the
property if it does not yet exist on the symbol, otherwise updates the
existing value (and optionally its label position / visibility). Lets a
single tool call attach an entire BOM / sourcing payload to a component:
`properties: { MPN: "RC0603FR-0710KL", Manufacturer: "Yageo", Tolerance: "1%" }`.
- **`removeProperties`** — list of custom property names to delete in the
same call.
- String values written through any of the property paths are now properly
backslash-escaped so descriptions containing `"` or `\` no longer
corrupt the .kicad_sch file.
- `get_schematic_component`: clarified description — it already returns every
field on the symbol (built-in + custom). The tool description now spells
this out explicitly so agents know they can use it to inspect MPN,
Manufacturer, Distributor PN and other BOM fields without a separate call.
### New MCP Prompt
- `component_sourcing_properties` — Guides the LLM through attaching BOM and
sourcing metadata (MPN, Manufacturer, distributor part numbers, parametric
fields like Voltage / Tolerance / Dielectric) to schematic components. Lists
the conventional property names recognised by downstream BOM tooling and the
recommended call sequence (`list_schematic_components`
`get_schematic_component``set_schematic_component_property` /
`edit_schematic_component`).
### Tests
- `tests/test_schematic_component_properties.py`: 32 new tests covering custom
property add / update / remove (single + batched), full spec dicts, position
defaults, `(hide yes)` defaulting, protected built-in field rejection,
no-op removal, special-character escaping, UUID preservation, and the two
new convenience tools.
---
## [2.2.3] - 2026-03-11
### Merged: PR #57 (Kletternaut/demo/rpiCSI-videotest → main)