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

@@ -195,6 +195,78 @@ Based on the available information, suggest likely causes of the issue and recom
}),
);
// ------------------------------------------------------
// Component Sourcing / BOM Properties Prompt
// ------------------------------------------------------
server.prompt(
"component_sourcing_properties",
{
component_info: z
.string()
.describe(
"Description of the component(s) being sourced and which BOM fields need to be attached " +
"(MPN, distributor part numbers, manufacturer, etc.).",
),
},
() => ({
messages: [
{
role: "user",
content: {
type: "text",
text: `You are attaching sourcing and BOM metadata to schematic components. Here is the situation:
{{component_info}}
KiCad symbols carry arbitrary key/value properties on top of the four built-in fields
(Reference, Value, Footprint, Datasheet). These custom properties are written into
the .kicad_sch file, are exported by export_bom, and are picked up by JLCPCB / Digi-Key
sourcing tooling.
Conventional property names (use these so downstream BOM tools recognise them):
• MPN — Manufacturer Part Number (canonical)
• Manufacturer — Manufacturer name (e.g. "Yageo", "Murata")
• Manufacturer_PN — Alias some BOM templates expect; mirror MPN if unsure
• DigiKey, DigiKey_PN — Digi-Key catalogue number
• Mouser_PN — Mouser catalogue number
• LCSC, JLCPCB_PN — JLCPCB / LCSC part number (used by JLCPCB assembly)
• Distributor, Distributor_PN — Generic fallback fields
• Voltage — Working voltage rating (e.g. "50V")
• Tolerance — Tolerance (e.g. "1%", "±5%")
• Power — Power rating (e.g. "0.1W", "1/4W")
• Dielectric — Capacitor dielectric (e.g. "X7R", "C0G", "Y5V")
• Temperature_Coefficient — Resistor TC (e.g. "100ppm/°C")
• Description — Free-form human-readable description
Tools to use, in this order:
1. \`list_schematic_components\` — confirm which components need updating.
2. \`get_schematic_component\` — inspect what properties are already present
(returns ALL property fields, including custom ones).
3. \`set_schematic_component_property\` — attach or update one property at a time
when working on a single component.
4. \`edit_schematic_component\` with the \`properties\` parameter — batch-update
many properties on the same component in a single call:
properties: { MPN: "RC0603FR-0710KL", Manufacturer: "Yageo", Tolerance: "1%" }
5. \`remove_schematic_component_property\` — delete an obsolete custom field.
Hidden vs visible:
• Newly-created custom properties default to hidden — they appear in BOM exports
but do NOT clutter the schematic canvas. This is the normal convention for
sourcing metadata.
• If a value should be displayed (e.g. you want the MPN visible next to the
symbol), pass \`hide: false\` and a sensible \`x\`/\`y\` position.
Recommend the right set of properties for the components in the brief, generate
the actual tool calls (with concrete values), and explain any sourcing trade-offs
or substitutions you propose.`,
},
},
],
}),
);
// ------------------------------------------------------
// Component Value Calculation Prompt
// ------------------------------------------------------