kcaa 0.2.2__tar.gz → 0.2.4__tar.gz

{kcaa-0.2.2 → kcaa-0.2.4}/.gitignore

@@ -73,6 +73,7 @@ fp-info-cache
 *.kicad_pcb-bak
 *.kicad_sch-bak
 *.kicad_pro-bak
+**/.versions/
 *.kicad_prl
 *.kicad_prl-bak
 *.kicad_sch.lck

{kcaa-0.2.2 → kcaa-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kcaa
-Version: 0.2.2
+Version: 0.2.4
 Summary: Model Context Protocol (MCP) server for KiCad electronic design automation (EDA) files
 Project-URL: Homepage, https://github.com/paul356/KiCad-AI-Assistant
 Project-URL: Bug Tracker, https://github.com/paul356/KiCad-AI-Assistant/issues
@@ -263,10 +263,8 @@ kcaa
 | Tool | Description |
 |------|-------------|
 | `extract_schematic_netlist` | Extract netlist from a schematic |
-| `extract_project_netlist` | Extract netlist for a whole project |
 | `find_component_connections` | Find all connections for a component |
 | `identify_circuit_patterns` | Identify common circuit patterns |
-| `analyze_project_circuit_patterns` | Analyze circuit patterns in a project |
 | `validate_project` | Basic validation of a KiCad project |
 | `validate_project_boundaries` | Validate component boundaries |
 | `generate_validation_report` | Generate a comprehensive validation report |
@@ -292,6 +290,9 @@ kcaa
 | `list_footprint_libraries` | List all available footprint libraries |
 | `search_footprints` | Search footprints by name, description, or tag |
 | `get_footprint_details` | Get footprint details (pads, bounding box, etc.) |
+| `find_footprints_not_in_libraries` | List board footprints missing from every indexed library |
+| `create_footprint_library` | Create a global 3rdparty or project-local footprint library |
+| `add_footprints_to_library` | Export explicitly named board footprints into a library |
 
 ### PCB Query
 
@@ -323,7 +324,7 @@ kcaa
 
 | Tool | Description |
 |------|-------------|
-| `set_footprint_position` | Move and/or rotate a single footprint |
+| `set_footprint_position` | Move and/or rotate one or more footprints (via `items`) |
 | `flip_footprint` | Flip a footprint between top and bottom layer |
 | `align_footprints` | Align footprints to the same axis |
 | `distribute_footprints` | Distribute footprints evenly along an axis |
@@ -371,11 +372,10 @@ kcaa
 
 | Tool | Description |
 |------|-------------|
-| `save_file_version` | Save a version snapshot for rollback |
-| `list_file_versions` | List saved version snapshots |
-| `restore_file_version` | Restore to a previously saved version |
+| `save_project_version` | Save a project version archive (schematic+PCB+project file) |
+| `list_project_versions` | List saved project version archives |
+| `restore_project_version` | Restore project files together to a saved archive |
 | `generate_pcb_thumbnail` | Render a PCB thumbnail image |
-| `generate_project_thumbnail` | Render a project thumbnail |
 
 ### Skill System
 

{kcaa-0.2.2 → kcaa-0.2.4}/README.md

@@ -224,10 +224,8 @@ kcaa
 | Tool | Description |
 |------|-------------|
 | `extract_schematic_netlist` | Extract netlist from a schematic |
-| `extract_project_netlist` | Extract netlist for a whole project |
 | `find_component_connections` | Find all connections for a component |
 | `identify_circuit_patterns` | Identify common circuit patterns |
-| `analyze_project_circuit_patterns` | Analyze circuit patterns in a project |
 | `validate_project` | Basic validation of a KiCad project |
 | `validate_project_boundaries` | Validate component boundaries |
 | `generate_validation_report` | Generate a comprehensive validation report |
@@ -253,6 +251,9 @@ kcaa
 | `list_footprint_libraries` | List all available footprint libraries |
 | `search_footprints` | Search footprints by name, description, or tag |
 | `get_footprint_details` | Get footprint details (pads, bounding box, etc.) |
+| `find_footprints_not_in_libraries` | List board footprints missing from every indexed library |
+| `create_footprint_library` | Create a global 3rdparty or project-local footprint library |
+| `add_footprints_to_library` | Export explicitly named board footprints into a library |
 
 ### PCB Query
 
@@ -284,7 +285,7 @@ kcaa
 
 | Tool | Description |
 |------|-------------|
-| `set_footprint_position` | Move and/or rotate a single footprint |
+| `set_footprint_position` | Move and/or rotate one or more footprints (via `items`) |
 | `flip_footprint` | Flip a footprint between top and bottom layer |
 | `align_footprints` | Align footprints to the same axis |
 | `distribute_footprints` | Distribute footprints evenly along an axis |
@@ -332,11 +333,10 @@ kcaa
 
 | Tool | Description |
 |------|-------------|
-| `save_file_version` | Save a version snapshot for rollback |
-| `list_file_versions` | List saved version snapshots |
-| `restore_file_version` | Restore to a previously saved version |
+| `save_project_version` | Save a project version archive (schematic+PCB+project file) |
+| `list_project_versions` | List saved project version archives |
+| `restore_project_version` | Restore project files together to a saved archive |
 | `generate_pcb_thumbnail` | Render a PCB thumbnail image |
-| `generate_project_thumbnail` | Render a project thumbnail |
 
 ### Skill System
 

{kcaa-0.2.2 → kcaa-0.2.4}/README_CN.md

@@ -223,10 +223,8 @@ kcaa
 | 工具 | 说明 |
 |------|------|
 | `extract_schematic_netlist` | 从原理图提取网表 |
-| `extract_project_netlist` | 提取整个项目的网表 |
 | `find_component_connections` | 查找元件的所有连接 |
 | `identify_circuit_patterns` | 识别常见电路模式 |
-| `analyze_project_circuit_patterns` | 分析项目中的电路模式 |
 | `validate_project` | 项目基本验证 |
 | `validate_project_boundaries` | 验证元件边界 |
 | `generate_validation_report` | 生成综合验证报告 |
@@ -252,6 +250,9 @@ kcaa
 | `list_footprint_libraries` | 列出所有可用封装库 |
 | `search_footprints` | 按名称/描述/标签搜索封装 |
 | `get_footprint_details` | 获取封装详情（焊盘、边界框等） |
+| `find_footprints_not_in_libraries` | 列出板上缺失于所有已索引库的封装 |
+| `create_footprint_library` | 创建全局 3rdparty 或项目级封装库 |
+| `add_footprints_to_library` | 将显式指定的板载封装导出到库 |
 
 ### PCB 查询
 
@@ -283,7 +284,7 @@ kcaa
 
 | 工具 | 说明 |
 |------|------|
-| `set_footprint_position` | 移动/旋转单个封装 |
+| `set_footprint_position` | 批量移动/旋转一个或多个封装 |
 | `flip_footprint` | 将封装在顶层/底层之间翻转 |
 | `align_footprints` | 将封装对齐到同一坐标轴 |
 | `distribute_footprints` | 沿坐标轴等间距分布封装 |
@@ -331,11 +332,10 @@ kcaa
 
 | 工具 | 说明 |
 |------|------|
-| `save_file_version` | 保存版本快照以便回退 |
-| `list_file_versions` | 列出已保存的版本快照 |
-| `restore_file_version` | 恢复到之前保存的版本 |
+| `save_project_version` | 保存项目版本归档（原理图+PCB+项目文件） |
+| `list_project_versions` | 列出已保存的项目版本归档 |
+| `restore_project_version` | 将项目文件一起恢复到已保存的归档 |
 | `generate_pcb_thumbnail` | 渲染 PCB 缩略图 |
-| `generate_project_thumbnail` | 渲染项目缩略图 |
 
 ### 技能系统
 

{kcaa-0.2.2 → kcaa-0.2.4}/kcaa/server.py

@@ -6,11 +6,12 @@ Two server profiles are supported, selected via the KICAD_MCP_PROFILE environmen
   full   (default) — registers all tools, resources, and prompts. Intended for
                      standalone MCP clients such as Claude Desktop.
 
-  plugin            — registers only the skip-based schematic editing tools
-                     (netlist, symbol, component, wire/junction). No resources,
-                     no prompts, no kicad-cli-dependent tools. Intended for the
-                     KiCad plugin integration where the plugin supplies project
-                     context directly and the LLM drives editing via tool calls.
+  plugin            — registers the skip-based schematic/PCB editing tools
+                     plus the ``get_project_structure`` query tool. No
+                     resources, no prompts, no kicad-cli-dependent tools.
+                     Intended for the KiCad plugin integration where the
+                     plugin supplies project context directly and the LLM
+                     drives editing via tool calls.
 """
 
 import atexit
@@ -40,6 +41,7 @@ from kcaa.tools.pcb_query_tools import register_pcb_query_tools
 from kcaa.tools.pcb_routing_tools import register_pcb_routing_tools
 from kcaa.tools.pcb_zone_tools import register_pcb_zone_tools
 from kcaa.tools.placement_helpers import register_placement_helpers
+from kcaa.tools.project_tools import register_project_tools
 from kcaa.tools.schematic_group_tools import register_schematic_group_tools
 from kcaa.tools.sheet_tools import register_sheet_tools
 from kcaa.tools.skill_tools import register_skill_tools
@@ -110,9 +112,12 @@ def register_signal_handlers(server: FastMCP) -> None:
 
 
 def _register_plugin_profile(mcp: FastMCP) -> None:
-    """Register only the skip-based schematic/PCB editing tools + IPC-based tools for the plugin profile."""
+    """Register the skip-based schematic/PCB editing tools + IPC-based tools for the plugin profile."""
     logging.info("Registering plugin profile: schematic + PCB tools")
     register_netlist_tools(mcp)
+    # Project structure query for the plugin LLM; keep full-profile
+    # management tools (list_projects/open_project) out of this profile.
+    register_project_tools(mcp, tools=("get_project_structure",))
     register_symbol_tools(mcp)
     register_symbol_edit_tools(mcp)
     register_sheet_tools(mcp)
@@ -205,8 +210,9 @@ def create_server(profile: ServerProfile = "full") -> FastMCP:
     Args:
         profile: Server capability profile.
             "full"   — all tools, resources, and prompts (default; for Claude Desktop etc.)
-            "plugin" — plugin-facing profile: 26 skip-based schematic editing tools only,
-                       no resources, no prompts, no kicad-cli-dependent tools.
+            "plugin" — plugin-facing profile: skip-based schematic/PCB editing
+                       tools plus the get_project_structure query tool; no
+                       resources, no prompts, no kicad-cli-dependent tools.
                        Override via KICAD_MCP_PROFILE env var.
     """
     # Allow env var to override the profile argument; strip whitespace/case variants

{kcaa-0.2.2 → kcaa-0.2.4}/kcaa/tools/export_tools.py

@@ -99,15 +99,6 @@ def register_export_tools(mcp: FastMCP) -> None:
                 await ctx.info(f"Error: {str(e)}")
             return None
 
-    @mcp.tool()
-    async def generate_project_thumbnail(project_path: str, ctx: Context | None):
-        """Generate a thumbnail of a KiCad project's PCB layout (Alias for generate_pcb_thumbnail)."""
-        # This function now just calls the main CLI-based thumbnail generator
-        print(
-            f"generate_project_thumbnail called, redirecting to generate_pcb_thumbnail for {project_path}"
-        )
-        return await generate_pcb_thumbnail(project_path, ctx)
-
 
 # Helper functions for thumbnail generation
 async def generate_thumbnail_with_cli(pcb_file: str, ctx: Context | None):

{kcaa-0.2.2 → kcaa-0.2.4}/kcaa/tools/netlist_tools.py

@@ -19,66 +19,6 @@ def register_netlist_tools(mcp: FastMCP) -> None:
         mcp: The FastMCP server instance
     """
 
-    @mcp.tool()
-    async def extract_project_netlist(project_path: str, ctx: Context | None) -> dict[str, Any]:
-        """Extract netlist from a KiCad project's schematic.
-
-        This tool finds the schematic associated with a KiCad project
-        and extracts its netlist information.
-
-        Args:
-            project_path: Path to the KiCad project file (.kicad_pro)
-            ctx: MCP context for progress reporting
-
-        Returns:
-            Dictionary with netlist information
-        """
-        print(f"Extracting netlist for project: {project_path}")
-
-        if not os.path.exists(project_path):
-            print(f"Project not found: {project_path}")
-            if ctx:
-                ctx.info(f"Project not found: {project_path}")
-            return {"success": False, "error": f"Project not found: {project_path}"}
-
-        # Report progress
-        if ctx:
-            await ctx.report_progress(10, 100)
-
-        # Get the schematic file
-        try:
-            files = get_project_files(project_path)
-
-            if "schematic" not in files:
-                print("Schematic file not found in project")
-                if ctx:
-                    ctx.info("Schematic file not found in project")
-                return {"success": False, "error": "Schematic file not found in project"}
-
-            schematic_path = files["schematic"]
-            print(f"Found schematic file: {schematic_path}")
-            if ctx:
-                ctx.info(f"Found schematic file: {os.path.basename(schematic_path)}")
-
-            # Extract netlist
-            if ctx:
-                await ctx.report_progress(20, 100)
-
-            # Call the schematic netlist extraction
-            result = await extract_schematic_netlist(schematic_path, ctx=ctx)
-
-            # Add project path to result
-            if "success" in result and result["success"]:
-                result["project_path"] = project_path
-
-            return result
-
-        except Exception as e:
-            print(f"Error extracting project netlist: {str(e)}")
-            if ctx:
-                ctx.info(f"Error extracting project netlist: {str(e)}")
-            return {"success": False, "error": str(e)}
-
     @mcp.tool()
     async def extract_schematic_netlist(
         schematic_path: str,

{kcaa-0.2.2 → kcaa-0.2.4}/kcaa/tools/pattern_tools.py

@@ -7,7 +7,6 @@ from typing import Any
 
 from fastmcp import Context, FastMCP
 
-from kcaa.utils.file_utils import get_project_files
 from kcaa.utils.netlist_parser import extract_netlist
 from kcaa.utils.pattern_recognition import (
     identify_amplifiers,
@@ -155,51 +154,3 @@ def register_pattern_tools(mcp: FastMCP) -> None:
             if ctx:
                 ctx.info(f"Error identifying circuit patterns: {str(e)}")
             return {"success": False, "error": str(e)}
-
-    @mcp.tool()
-    async def analyze_project_circuit_patterns(
-        project_path: str, ctx: Context | None
-    ) -> dict[str, Any]:
-        """Identify circuit patterns in a KiCad project's schematic.
-
-        Args:
-            project_path: Path to the KiCad project file (.kicad_pro)
-            ctx: MCP context for progress reporting
-
-        Returns:
-            Dictionary with identified circuit patterns
-        """
-        if not os.path.exists(project_path):
-            if ctx:
-                ctx.info(f"Project not found: {project_path}")
-            return {"success": False, "error": f"Project not found: {project_path}"}
-
-        # Report progress
-        if ctx:
-            await ctx.report_progress(10, 100)
-
-        # Get the schematic file
-        try:
-            files = get_project_files(project_path)
-
-            if "schematic" not in files:
-                if ctx:
-                    ctx.info("Schematic file not found in project")
-                return {"success": False, "error": "Schematic file not found in project"}
-
-            schematic_path = files["schematic"]
-            if ctx:
-                ctx.info(f"Found schematic file: {os.path.basename(schematic_path)}")
-
-            # Identify patterns in the schematic
-            result = await identify_circuit_patterns(schematic_path, ctx)
-
-            # Add project path to result
-            if "success" in result and result["success"]:
-                result["project_path"] = project_path
-
-            return result
-
-        except Exception as e:
-            ctx.info(f"Error analyzing project circuit patterns: {str(e)}")
-            return {"success": False, "error": str(e)}

{kcaa-0.2.2 → kcaa-0.2.4}/kcaa/tools/pcb_edit_tools.py

@@ -309,47 +309,120 @@ def register_pcb_edit_tools(mcp: FastMCP) -> None:
     @mcp.tool()
     async def set_footprint_property(
         pcb_path: str,
-        reference: str,
-        property_name: str,
-        value: str,
+        items: list[dict[str, Any]],
         ctx: Context | None,
-    ) -> dict[str, str]:
-        """Update a property of a footprint on the PCB board.
+    ) -> dict[str, Any]:
+        """Update a property on footprints of the PCB board.
 
         Common property names: ``Reference``, ``Value``, ``Datasheet``,
         ``Description``.  Custom user fields are also supported.
 
+        Each item in *items* carries its own property and value
+        (``{"reference": ..., "property_name": ..., "value": ...}``).
+        All items are processed in one parse + one save (single ``.bak``).
+        Partial-apply: a footprint that cannot be found or lacks the
+        property keeps its own error in ``results`` while the remaining
+        footprints are still applied and saved.  Empty, duplicate, or
+        malformed items are rejected up front.
+
         A .kicad_pcb.bak backup is created before writing.
+
+        Args:
+            pcb_path: Absolute path to the .kicad_pcb file.
+            items: List of per-footprint specs, e.g. ``[{"reference":
+                "R1", "property_name": "Value", "value": "22k"}]``.
+                Keys: ``reference`` (str, required, unique),
+                ``property_name`` (str, required),
+                ``value`` (str, required).
+
+        Returns:
+            dict with: results (per-footprint {reference, property_name,
+            previous_value, new_value} or {reference, error}),
+            success (all applied), count, applied_count, failure_count,
+            backup_path, pcb_path.
         """
+        _ITEM_KEYS = {"reference", "property_name", "value"}
+        if not items:
+            return {"error": "items must not be empty"}
+        for item in items:
+            if not isinstance(item, dict):
+                return {"error": "each item must be a dict with reference, property_name, value"}
+            unknown = set(item) - _ITEM_KEYS
+            if unknown:
+                return {
+                    "error": f"Unknown item fields: {sorted(unknown)}. Valid: {sorted(_ITEM_KEYS)}"
+                }
+            ref = item.get("reference")
+            if not isinstance(ref, str) or not ref:
+                return {"error": "items must not contain empty or missing references"}
+            if not isinstance(item.get("property_name"), str) or not item["property_name"]:
+                return {"error": "items must contain a non-empty property_name"}
+            if not isinstance(item.get("value"), str):
+                return {"error": "items must contain a string value"}
+        refs = [item["reference"] for item in items]
+        if len(set(refs)) != len(refs):
+            return {"error": "items must not contain duplicate references"}
+
         data = load_pcb(pcb_path)
-        try:
-            fp = find_footprint(data, reference)
-        except KeyError as exc:
-            return {"error": str(exc)}
 
-        old_value = get_fp_property(fp, property_name)
-        if old_value is None:
+        def apply_one(item: dict[str, Any]) -> dict[str, Any]:
+            ref = item["reference"]
+            name = item["property_name"]
+            val = item["value"]
+            try:
+                fp = find_footprint(data, ref)
+            except KeyError as exc:
+                return {"error": str(exc), "reference": ref}
+
+            old_value = get_fp_property(fp, name)
+            if old_value is None:
+                return {
+                    "error": (
+                        f"Property '{name}' not found on footprint '{ref}'. "
+                        f"Use get_footprint to see available properties."
+                    ),
+                    "reference": ref,
+                }
+
+            updated = set_fp_property(fp, name, val)
+            if not updated:
+                return {
+                    "error": f"Failed to update property '{name}' on '{ref}'.",
+                    "reference": ref,
+                }
+
             return {
-                "error": (
-                    f"Property '{property_name}' not found on footprint '{reference}'. "
-                    f"Use get_footprint to see available properties."
-                )
+                "success": True,
+                "reference": ref,
+                "property_name": name,
+                "previous_value": old_value,
+                "new_value": val,
             }
 
-        updated = set_fp_property(fp, property_name, value)
-        if not updated:
-            return {"error": f"Failed to update property '{property_name}' on '{reference}'."}
+        results: list[dict[str, Any]] = []
+        for item in items:
+            ref = item["reference"]
+            try:
+                results.append(apply_one(item))
+            except Exception as exc:
+                log.warning("set_footprint_property: reference %r failed: %s", ref, exc)
+                results.append({"error": f"{ref}: {exc}", "reference": ref})
 
-        try:
-            backup_path = save_pcb(pcb_path, data)
-        except OSError as exc:
-            return {"error": f"Failed to write PCB file: {exc}"}
+        applied_count = sum(1 for r in results if r.get("success"))
+
+        backup_path: str | None = None
+        if applied_count > 0:
+            try:
+                backup_path = save_pcb(pcb_path, data)
+            except OSError as exc:
+                return {"error": f"Failed to write PCB file: {exc}"}
 
         return {
-            "reference": reference,
-            "property_name": property_name,
-            "previous_value": old_value,
-            "new_value": value,
+            "success": applied_count == len(results) and len(results) > 0,
+            "results": results,
+            "count": len(results),
+            "applied_count": applied_count,
+            "failure_count": len(results) - applied_count,
             "backup_path": backup_path,
             "pcb_path": pcb_path,
         }