solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/tools/template_management.py

@@ -0,0 +1,367 @@
+"""Template Management tools for SolidWorks MCP Server.
+
+Provides tools for managing SolidWorks templates including extraction, application,
+comparison, and library management.
+"""
+
+from typing import Any
+
+from fastmcp import FastMCP
+from pydantic import BaseModel, Field
+
+from ..adapters.base import SolidWorksAdapter
+from .file_facts import file_fact_snapshot
+from .input_compat import CompatInput
+from .tool_boundary import (
+    ToolOperationError,
+    UnsupportedOperationError,
+    require_capability,
+    require_success,
+    with_tool_boundary,
+)
+
+# Input schemas for template management
+
+
+class TemplateExtractionInput(BaseModel):
+    """Input schema for extracting template from model.
+
+    Attributes:
+        include_custom_properties (bool): The include custom properties value.
+        include_dimensions (bool): The include dimensions value.
+        save_path (str): The save path value.
+        source_model (str): The source model value.
+        template_name (str): The template name value.
+        template_type (str): The template type value.
+    """
+
+    source_model: str = Field(description="Path to source model file")
+    template_name: str = Field(description="Name for the extracted template")
+    template_type: str = Field(description="Template type (part, assembly, drawing)")
+    save_path: str = Field(description="Path to save the template file")
+    include_custom_properties: bool = Field(
+        default=True, description="Include custom properties"
+    )
+    include_dimensions: bool = Field(default=True, description="Include dimensions")
+
+
+class TemplateApplicationInput(BaseModel):
+    """Input schema for applying template to model.
+
+    Attributes:
+        apply_dimensions (bool): The apply dimensions value.
+        apply_materials (bool): The apply materials value.
+        overwrite_existing (bool): The overwrite existing value.
+        target_model (str): The target model value.
+        template_path (str): The template path value.
+    """
+
+    template_path: str = Field(description="Path to template file")
+    target_model: str = Field(description="Path to target model")
+    overwrite_existing: bool = Field(
+        default=False, description="Overwrite existing properties"
+    )
+    apply_dimensions: bool = Field(
+        default=True, description="Apply dimension formatting"
+    )
+    apply_materials: bool = Field(default=True, description="Apply material settings")
+
+
+class TemplateBatchInput(BaseModel):
+    """Input schema for batch template operations.
+
+    Attributes:
+        backup_originals (bool): The backup originals value.
+        file_pattern (str): The file pattern value.
+        recursive (bool): The recursive value.
+        source_folder (str): The source folder value.
+        template_path (str): The template path value.
+    """
+
+    template_path: str = Field(description="Path to template file")
+    source_folder: str = Field(description="Folder containing target models")
+    file_pattern: str = Field(default="*.sldprt", description="File pattern to match")
+    recursive: bool = Field(default=True, description="Process subfolders")
+    backup_originals: bool = Field(default=True, description="Create backup copies")
+
+
+class TemplateComparisonInput(CompatInput):
+    """Input schema for comparing templates.
+
+    Attributes:
+        comparison_depth (str): The comparison depth value.
+        comparison_type (str): The comparison type value.
+        generate_report (bool): The generate report value.
+        include_dimensions (bool): The include dimensions value.
+        include_materials (bool): The include materials value.
+        include_properties (bool): The include properties value.
+        template1_path (str): The template1 path value.
+        template2_path (str): The template2 path value.
+    """
+
+    template1_path: str = Field(description="Path to first template")
+    template2_path: str = Field(description="Path to second template")
+    comparison_type: str = Field(
+        default="full", description="Comparison type (full, properties, dimensions)"
+    )
+    comparison_depth: str = Field(default="full", description="Comparison depth alias")
+    include_properties: bool = Field(default=True, description="Include properties")
+    include_dimensions: bool = Field(default=True, description="Include dimensions")
+    include_materials: bool = Field(default=True, description="Include materials")
+    generate_report: bool = Field(
+        default=True, description="Generate comparison report"
+    )
+
+
+async def register_template_management_tools(
+    mcp: FastMCP, adapter: SolidWorksAdapter, config: Any
+) -> int:
+    """Register template management tools with FastMCP.
+
+    Args:
+        mcp (FastMCP): The mcp value.
+        adapter (SolidWorksAdapter): Adapter instance used for the operation.
+        config (Any): Configuration values for the operation.
+
+    Returns:
+        int: The computed numeric result.
+
+    Example:
+                        >>> tool_count = await register_template_management_tools(mcp, adapter, config)
+    """
+    mcp = with_tool_boundary(mcp)
+    tool_count = 0
+
+    @mcp.tool()
+    async def extract_template(input_data: TemplateExtractionInput) -> dict[str, Any]:
+        """Extract template from existing SolidWorks model.
+
+        Args:
+            input_data (TemplateExtractionInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await extract_template(extraction_input)
+        """
+        require_capability(
+            adapter,
+            "extract_template",
+            "Active adapter does not support extract_template; no "
+            f"template was extracted from {input_data.source_model}.",
+        )
+        result = await adapter.extract_template(input_data.model_dump())
+        require_success(result, "Failed to extract template")
+        return {
+            "status": "success",
+            "message": f"Template '{input_data.template_name}' extracted from {input_data.source_model}",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def apply_template(input_data: TemplateApplicationInput) -> dict[str, Any]:
+        """Apply a template to an existing SolidWorks model.
+
+        This tool applies saved template settings including properties, dimensions, and
+        formatting to the target model.
+
+        Args:
+            input_data (TemplateApplicationInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await apply_template(application_input)
+        """
+        require_capability(
+            adapter,
+            "apply_template",
+            "Active adapter does not support apply_template; "
+            f"{input_data.target_model} was not changed.",
+        )
+        result = await adapter.apply_template(input_data.model_dump())
+        require_success(result, "Failed to apply template")
+        return {
+            "status": "success",
+            "message": f"Template applied to {input_data.target_model}",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def batch_apply_template(input_data: TemplateBatchInput) -> dict[str, Any]:
+        """Apply template to multiple models in batch.
+
+        This tool processes multiple SolidWorks files and applies the same template
+        configuration to all matching files.
+
+        Args:
+            input_data (TemplateBatchInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await batch_apply_template(batch_input)
+        """
+        require_capability(
+            adapter,
+            "batch_apply_template",
+            "Active adapter does not support batch_apply_template; "
+            f"no files in {input_data.source_folder} were changed.",
+        )
+        result = await adapter.batch_apply_template(input_data.model_dump())
+        require_success(result, "Failed batch template application")
+        return {
+            "status": "success",
+            "message": "Batch template application completed",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def compare_templates(input_data: TemplateComparisonInput) -> dict[str, Any]:
+        """Compare two templates and generate difference report.
+
+        This tool analyzes differences between templates to help understand variations in
+        formatting and properties.
+
+        Args:
+            input_data (TemplateComparisonInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await compare_templates(comparison_input)
+
+        Note:
+            When no adapter can parse template internals, this falls back to
+            a filesystem-level comparison only (existence, size, modified
+            time, byte-identical check) — it does not report property,
+            dimension, or formatting differences it cannot actually read.
+        """
+        if hasattr(adapter, "compare_templates"):
+            result = await adapter.compare_templates(input_data.model_dump())
+            require_success(result, "Failed to compare templates")
+            return {
+                "status": "success",
+                "message": "Template comparison completed",
+                "data": result.data,
+                "execution_time": result.execution_time,
+            }
+
+        file_1 = file_fact_snapshot(input_data.template1_path)
+        file_2 = file_fact_snapshot(input_data.template2_path)
+
+        missing = [
+            path
+            for path, snapshot in (
+                (input_data.template1_path, file_1),
+                (input_data.template2_path, file_2),
+            )
+            if snapshot is None
+        ]
+        if missing:
+            raise ToolOperationError(
+                "Cannot compare templates; file(s) not found on "
+                f"disk: {', '.join(missing)}. No template-property "
+                "diff was performed."
+            )
+
+        assert file_1 is not None
+        assert file_2 is not None
+        identical = file_1["sha256"] == file_2["sha256"]
+
+        return {
+            "status": "success",
+            "message": (
+                "Template files are byte-identical"
+                if identical
+                else "Template files differ on disk"
+            ),
+            "comparison": {
+                "file_1": file_1,
+                "file_2": file_2,
+                "identical": identical,
+                "size_delta_bytes": file_2["size_bytes"] - file_1["size_bytes"],
+            },
+            "note": (
+                "This is a filesystem-level comparison only; template "
+                "properties, dimensions, and formatting were not "
+                "analyzed."
+            ),
+        }
+
+    @mcp.tool()
+    async def save_to_template_library(input_data: dict[str, Any]) -> dict[str, Any]:
+        """Save template to the organization's template library.
+
+        This tool manages a centralized template library with categorization and version
+        control.
+
+        Args:
+            input_data (dict[str, Any]): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await save_to_template_library(library_input)
+        """
+
+        if hasattr(adapter, "save_to_template_library"):
+            result = await adapter.save_to_template_library(input_data)
+            require_success(result, "Failed to save to library")
+            return {
+                "status": "success",
+                "message": "Template saved to library",
+                "data": result.data,
+                "execution_time": result.execution_time,
+            }
+
+        template_name = input_data.get("template_name", "")
+
+        raise UnsupportedOperationError(
+            "Active adapter does not support save_to_template_library; "
+            f"'{template_name}' was not saved to any library. There is "
+            "no local template registry — this tool needs a real "
+            "adapter-backed library service."
+        )
+
+    @mcp.tool()
+    async def list_template_library(input_data: dict[str, Any]) -> dict[str, Any]:
+        """List available templates from the template library.
+
+        This tool provides browsing and searching capabilities for the organization's template
+        library.
+
+        Args:
+            input_data (dict[str, Any]): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> result = await list_template_library(list_input)
+        """
+        require_capability(
+            adapter,
+            "list_template_library",
+            "Active adapter does not support list_template_library; "
+            "there is no local template registry to list.",
+        )
+        result = await adapter.list_template_library(input_data)
+        require_success(result, "Failed to list template library")
+        return {
+            "status": "success",
+            "message": "Template library listed successfully",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    tool_count = 6  # Template management tools
+    return tool_count

solidworks_mcp/tools/tool_boundary.py

@@ -0,0 +1,280 @@
+"""The single error boundary every MCP tool runs inside (spec: tools/error-boundary).
+
+Tools contain business logic only. They:
+
+* parse input with :func:`normalize_input` (raises :class:`InvalidInputError`),
+* check adapter results with :func:`require_success` (raises
+  :class:`ToolOperationError`), and
+* return their success payload.
+
+:func:`tool_boundary` turns anything raised into the uniform error payload -
+``status``, ``message``, ``error_type``, ``hint`` and ``execution_time`` (the
+adapter's timing, else the tool's own wall time) - using :class:`ErrorClassifier` to name the failure.
+:class:`ToolRegistrar` applies the boundary to every tool at registration, so no
+tool can forget it.
+"""
+
+from __future__ import annotations
+
+import functools
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+from loguru import logger
+from pydantic import BaseModel, ValidationError
+
+from ..adapters.base import AdapterResult
+from .error_classifier import (
+    INTERNAL,
+    INVALID_INPUT,
+    NOT_SUPPORTED,
+    NOT_SUPPORTED_HINT,
+    Classification,
+    ErrorClassifier,
+)
+
+_INVALID_INPUT_HINT = (
+    "Fix the named field(s) and call the tool again; see the tool's input "
+    "schema for the expected types and units."
+)
+_CLASSIFIER = ErrorClassifier()
+
+
+class InvalidInputError(ValueError):
+    """The tool's input failed validation; the adapter was not called."""
+
+
+class ToolOperationError(Exception):
+    """An adapter operation reported failure.
+
+    Attributes:
+        execution_time: The adapter's timing for the failed call, if any.
+        data: Diagnostic data that explains the failure (e.g. rebuild errors),
+            returned to the caller under ``data``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        execution_time: float | None = None,
+        data: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.execution_time = execution_time
+        self.data = data
+
+
+class UnsupportedOperationError(Exception):
+    """The active adapter has no capability for the requested operation."""
+
+
+def require_capability(adapter: Any, method: str, message: str) -> None:
+    """Raise :class:`UnsupportedOperationError` unless ``adapter`` has ``method``.
+
+    Args:
+        adapter: The active SolidWorks adapter.
+        method: The adapter method the tool needs.
+        message: What was not done, and what to do instead.
+    """
+    if not hasattr(adapter, method):
+        raise UnsupportedOperationError(message)
+
+
+def normalize_input[TModel: BaseModel](
+    input_data: Any, model_type: type[TModel]
+) -> TModel:
+    """Validate ``input_data`` as ``model_type``.
+
+    Args:
+        input_data: A ``model_type`` instance, a mapping of its fields, another
+            pydantic model (converted through ``model_dump``), or ``None`` for
+            a tool whose fields all have defaults.
+        model_type: The tool's pydantic input model.
+
+    Returns:
+        TModel: The validated model.
+
+    Raises:
+        InvalidInputError: Naming the offending field(s).
+    """
+    if isinstance(input_data, model_type):
+        return input_data
+    if input_data is None:
+        input_data = {}
+    elif not isinstance(input_data, dict) and hasattr(input_data, "model_dump"):
+        input_data = input_data.model_dump()
+    try:
+        return model_type.model_validate(input_data)
+    except ValidationError as exc:  # also wraps ValueErrors from validators
+        raise InvalidInputError(describe_validation_error(exc)) from exc
+
+
+def describe_validation_error(exc: ValidationError) -> str:
+    """Render a pydantic error as ``field: problem; field: problem``."""
+    parts = []
+    for error in exc.errors():
+        field = ".".join(str(p) for p in error.get("loc", ())) or "input"
+        parts.append(f"{field}: {error.get('msg', 'invalid')}")
+    return "; ".join(parts)
+
+
+def require_success[TResult](
+    result: AdapterResult[TResult],
+    failure_message: str = "Operation failed",
+    *,
+    context: str | None = None,
+    with_data: bool = False,
+) -> AdapterResult[TResult]:
+    """Return ``result`` when it succeeded; raise otherwise.
+
+    Mirrors the ``if result.is_success: ... else: error`` the tools used before
+    the boundary, so anything that is not a success - including a warning - is
+    reported as a failure. Tools that treat a warning as success check
+    ``result.status`` themselves before calling this.
+
+    Args:
+        result: The adapter result to check.
+        failure_message: Message used when the adapter gave none.
+        context: Prefix naming what failed, e.g. ``"Failed to create part"``,
+            giving ``"<context>: <adapter error>"``.
+        with_data: Return the adapter's ``data`` with the error, for tools whose
+            failure data is the diagnosis (e.g. ``rebuild_model``).
+
+    Raises:
+        ToolOperationError: Carrying the adapter's message and timing.
+    """
+    if not result.is_success:
+        message = str(result.error or failure_message)
+        raise ToolOperationError(
+            f"{context}: {message}" if context else message,
+            result.execution_time,
+            result.data if with_data else None,
+        )
+    return result
+
+
+def error_payload(
+    message: str,
+    classification: Classification,
+    execution_time: float | None = None,
+    data: Any = None,
+) -> dict[str, Any]:
+    """Build the spec's error payload."""
+    payload: dict[str, Any] = {
+        "status": "error",
+        "message": message,
+        "error_type": classification.error_type,
+        "hint": classification.hint,
+    }
+    payload["execution_time"] = execution_time
+    if data is not None:
+        payload["data"] = data
+    return payload
+
+
+def tool_boundary(
+    fn: Callable[..., Awaitable[dict[str, Any]]],
+    classifier: ErrorClassifier = _CLASSIFIER,
+) -> Callable[..., Awaitable[dict[str, Any]]]:
+    """Wrap an async tool so every failure becomes an error payload.
+
+    ``functools.wraps`` keeps the signature, so FastMCP builds the same input
+    schema for the wrapped tool.
+    """
+    tool_name = fn.__name__
+
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> dict[str, Any]:
+        started = time.perf_counter()
+
+        def elapsed() -> float:
+            return time.perf_counter() - started
+
+        try:
+            return await fn(*args, **kwargs)
+        except InvalidInputError as exc:
+            return error_payload(
+                f"Invalid input: {exc}",
+                Classification(INVALID_INPUT, _INVALID_INPUT_HINT),
+                elapsed(),
+            )
+        except ValidationError as exc:
+            return error_payload(
+                f"Invalid input: {describe_validation_error(exc)}",
+                Classification(INVALID_INPUT, _INVALID_INPUT_HINT),
+                elapsed(),
+            )
+        except UnsupportedOperationError as exc:
+            return error_payload(
+                str(exc),
+                Classification(NOT_SUPPORTED, NOT_SUPPORTED_HINT),
+                elapsed(),
+            )
+        except ToolOperationError as exc:
+            message = str(exc)
+            # Adapter guards (wrong document type, no active model) reject a
+            # call before timing it; fall back to the tool's own wall time.
+            timing = exc.execution_time if exc.execution_time is not None else elapsed()
+            return error_payload(
+                message, classifier.classify(message), timing, exc.data
+            )
+        except Exception as exc:
+            logger.exception("Tool {} raised", tool_name)
+            message = f"{tool_name} failed: {type(exc).__name__}: {exc}"
+            return error_payload(
+                message,
+                classifier.classify(str(exc), exc, fallback=INTERNAL),
+                elapsed(),
+            )
+
+    wrapper.__tool_boundary__ = True  # type: ignore[attr-defined]
+    return wrapper
+
+
+def has_tool_boundary(fn: Any) -> bool:
+    """True when ``fn`` was wrapped by :func:`tool_boundary`."""
+    return bool(getattr(fn, "__tool_boundary__", False))
+
+
+class ToolRegistrar:
+    """A FastMCP stand-in whose ``tool()`` applies :func:`tool_boundary` first.
+
+    Everything else is forwarded to the wrapped server unchanged.
+    """
+
+    def __init__(self, mcp: Any, classifier: ErrorClassifier = _CLASSIFIER) -> None:
+        self._mcp = mcp
+        self._classifier = classifier
+
+    @classmethod
+    def of(cls, mcp: Any) -> ToolRegistrar:
+        """Wrap ``mcp`` unless it already is a registrar (idempotent).
+
+        Every ``register_<area>_tools`` starts with ``mcp = ToolRegistrar.of(mcp)``
+        so its tools get the boundary however the module is registered.
+        """
+        return mcp if isinstance(mcp, cls) else cls(mcp)
+
+    def tool(self, *args: Any, **kwargs: Any) -> Any:
+        """Same contract as ``FastMCP.tool``, with the boundary applied."""
+        if args and callable(args[0]) and len(args) == 1 and not kwargs:
+            return self._mcp.tool()(tool_boundary(args[0], self._classifier))
+        register = self._mcp.tool(*args, **kwargs)
+
+        def decorator(fn: Callable[..., Awaitable[dict[str, Any]]]) -> Any:
+            return register(tool_boundary(fn, self._classifier))
+
+        return decorator
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._mcp, name)
+
+
+def with_tool_boundary[TServer](mcp: TServer) -> TServer:
+    """Return ``mcp`` wrapped in a :class:`ToolRegistrar` (typed as ``mcp``).
+
+    The registrar duck-types the FastMCP surface the tool modules use
+    (``tool()`` plus attribute forwarding), so modules keep their annotations.
+    """
+    return cast(TServer, ToolRegistrar.of(mcp))