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

solidworks_mcp/tools/engineering_data.py

@@ -0,0 +1,466 @@
+"""Engineering-data tools: dimensions, measurement, material, properties, flat pattern.
+
+These read and edit the data a drawing, BOM or analysis is built from. Every tool
+calls a real adapter method (``adapters/solidworks/documentation.py``) and returns
+the adapter's own result - nothing here is simulated.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+from ..adapters.base import AdapterResult, SolidWorksAdapter
+from .input_compat import CompatInput
+from .tool_boundary import (
+    normalize_input,
+    require_capability,
+    require_success,
+    with_tool_boundary,
+)
+
+# Formats ExportToDWG2 writes a flat pattern to.
+_FLAT_PATTERN_SUFFIXES = (".dxf", ".dwg")
+
+
+class ListModelDimensionsInput(CompatInput):
+    """Input schema for listing model dimensions.
+
+    Attributes:
+        feature_name (str | None): Only this feature's dimensions.
+    """
+
+    feature_name: str | None = Field(
+        default=None,
+        description="Only list this feature's dimensions, e.g. 'Boss-Extrude1'. "
+        "Omit to list every dimension in the model.",
+    )
+
+
+class MeasureEntitiesInput(CompatInput):
+    """Input schema for measuring entities.
+
+    Attributes:
+        entities (list[str]): One or two entity specs.
+    """
+
+    entities: list[str] = Field(
+        description=(
+            "One or two entities to measure. Each is 'face:x,y,z' (a point inside "
+            "the face), 'edge:x,y,z', 'vertex:x,y,z', a bare 'x,y,z' (nearest "
+            "edge) or a topology name like 'Edge<1>'. Coordinates are in metres. "
+            "One face gives area/perimeter; one edge gives length/radius; two "
+            "entities give distance and angle."
+        ),
+        min_length=1,
+        max_length=2,
+    )
+
+
+class GetMaterialInput(CompatInput):
+    """Input schema for reading a part's material.
+
+    Attributes:
+        configuration (str | None): Configuration name.
+    """
+
+    configuration: str | None = Field(
+        default=None, description="Configuration; the active one when omitted"
+    )
+
+
+class SetMaterialInput(CompatInput):
+    """Input schema for assigning a material.
+
+    Attributes:
+        material_name (str): Exact library material name.
+        database (str | None): Material library name.
+        configuration (str | None): Configuration name.
+    """
+
+    material_name: str = Field(
+        description="Exact library name, e.g. 'AISI 1020', '6061-T6 (SS)', 'ABS'. "
+        "Use list_available_materials to find it.",
+        min_length=1,
+    )
+    database: str | None = Field(
+        default=None, description="Library; 'SOLIDWORKS Materials' when omitted"
+    )
+    configuration: str | None = Field(
+        default=None, description="Configuration; all configurations when omitted"
+    )
+
+
+class ListMaterialsInput(CompatInput):
+    """Input schema for listing materials.
+
+    Attributes:
+        search (str | None): Substring filter.
+    """
+
+    search: str | None = Field(
+        default=None,
+        description="Case-insensitive filter on material name or classification, "
+        "e.g. 'steel' or '6061'",
+    )
+
+
+class CustomPropertiesInput(CompatInput):
+    """Input schema for reading custom properties.
+
+    Attributes:
+        configuration (str | None): Configuration name.
+    """
+
+    configuration: str | None = Field(
+        default=None,
+        description="Configuration-specific properties; file-level (what title "
+        "blocks usually read) when omitted",
+    )
+
+
+class SetCustomPropertyInput(CompatInput):
+    """Input schema for writing one custom property.
+
+    Attributes:
+        name (str): Property name.
+        value (str): Property value.
+        configuration (str | None): Configuration name.
+    """
+
+    name: str = Field(
+        description="Property name, e.g. 'PartNo', 'Description', 'DrawnBy'",
+        min_length=1,
+    )
+    value: str = Field(description='Text value; may be a $PRP:"SW-Mass" style link')
+    configuration: str | None = Field(
+        default=None, description="Configuration; file-level when omitted"
+    )
+
+
+class ExportFlatPatternInput(CompatInput):
+    """Input schema for sheet-metal flat-pattern export.
+
+    Attributes:
+        file_path (str): Output .dxf or .dwg path.
+    """
+
+    file_path: str = Field(description="Output path ending in .dxf or .dwg")
+
+    def model_post_init(self, __context: Any) -> None:
+        """Refuse an output path that is not a DXF or DWG file.
+
+        Args:
+            __context (Any): The context value.
+
+        Returns:
+            None: None.
+
+        Raises:
+            ValueError: When ``file_path`` does not end in ``.dxf`` or ``.dwg``.
+        """
+        if not self.file_path.lower().endswith(_FLAT_PATTERN_SUFFIXES):
+            raise ValueError(
+                f"file_path must end in .dxf or .dwg, got {self.file_path!r}"
+            )
+
+
+def _success(result: AdapterResult[Any], message: str) -> dict[str, Any]:
+    """Shape a successful adapter result as the standard tool response.
+
+    Args:
+        result: The adapter's successful result.
+        message: What was done, for the ``message`` field.
+
+    Returns:
+        dict[str, Any]: ``status``, ``message``, ``data`` and ``execution_time``.
+    """
+    return {
+        "status": "success",
+        "message": message,
+        "data": result.data,
+        "execution_time": result.execution_time,
+    }
+
+
+async def register_engineering_data_tools(
+    mcp: FastMCP, adapter: SolidWorksAdapter, config: dict[str, Any]
+) -> int:
+    """Register engineering-data tools with FastMCP.
+
+    Args:
+        mcp (FastMCP): The MCP server.
+        adapter (SolidWorksAdapter): Adapter used by every tool.
+        config (dict[str, Any]): Server configuration (unused).
+
+    Returns:
+        int: Number of tools registered.
+    """
+
+    mcp = with_tool_boundary(mcp)
+
+    def _supports(method: str) -> None:
+        require_capability(
+            adapter,
+            method,
+            f"The active adapter does not support {method}; nothing was done.",
+        )
+
+    @mcp.tool()
+    async def list_model_dimensions(
+        input_data: ListModelDimensionsInput | None = None,
+    ) -> dict[str, Any]:
+        """List every dimension in the active part or assembly with its full name.
+
+        Read-only. Each entry's ``full_name`` (e.g. ``"D1@Sketch1"``) is the
+        name ``set_dimension`` / ``get_dimension`` accept, so this is how to
+        find and edit any driving dimension in an existing model. Pass
+        ``feature_name`` to list one feature's dimensions only.
+
+        Args:
+            input_data (ListModelDimensionsInput | None): ``feature_name`` to
+                list one feature only; omit for every dimension.
+
+        Returns:
+            dict[str, Any]: ``data`` is a list of ``{full_name, feature, value
+            (document units), system_value (metres or radians), read_only}``.
+            ``not_found`` when ``feature_name`` has no dimensions;
+            ``wrong_document_type`` on a drawing.
+
+        Example:
+            ```python
+            await list_model_dimensions()
+            await list_model_dimensions({"feature_name": "Boss-Extrude1"})
+            ```
+        """
+        input_data = normalize_input(input_data, ListModelDimensionsInput)
+        _supports("list_model_dimensions")
+        result = await adapter.list_model_dimensions(input_data.feature_name)
+        require_success(result, context="Failed to list model dimensions")
+        return _success(result, f"Listed {len(result.data or [])} dimension(s)")
+
+    @mcp.tool()
+    async def measure_entities(input_data: MeasureEntitiesInput) -> dict[str, Any]:
+        """Measure faces, edges or vertices with SolidWorks' Measure tool.
+
+        One face gives its area and perimeter; one edge its length (and radius
+        and diameter for an arc); two entities give the distance and angle
+        between them. Entity coordinates are in metres. Clears the selection
+        afterwards.
+
+        Args:
+            input_data (MeasureEntitiesInput): One or two entity specs.
+
+        Returns:
+            dict[str, Any]: ``data`` holds ``selected`` plus whichever of
+            ``distance_m``, ``center_distance_m``, ``angle_rad``, ``radius_m``,
+            ``diameter_m``, ``length_m``, ``arc_length_m``, ``area_m2``,
+            ``perimeter_m``, ``delta_x_m``/``_y_m``/``_z_m`` and (for two
+            entities) ``is_parallel`` apply to the selection. ``not_found``
+            when an entity cannot be selected.
+
+        Example:
+            ```python
+            # Area of the face through (15, 15, 0) mm.
+            await measure_entities({"entities": ["face:0.015,0.015,0.0"]})
+            # Distance and angle between two faces.
+            await measure_entities(
+                {"entities": ["face:0.015,0.015,0.0", "face:0.015,0.015,-0.015"]}
+            )
+            ```
+        """
+        input_data = normalize_input(input_data, MeasureEntitiesInput)
+        _supports("measure_entities")
+        result = await adapter.measure_entities(input_data.entities)
+        require_success(result, context="Failed to measure")
+        return _success(result, f"Measured {', '.join(input_data.entities)}")
+
+    @mcp.tool()
+    async def get_material(
+        input_data: GetMaterialInput | None = None,
+    ) -> dict[str, Any]:
+        """Read the material assigned to the active part.
+
+        Read-only. Parts only (``wrong_document_type`` otherwise).
+
+        Args:
+            input_data (GetMaterialInput | None): ``configuration``; the active
+                one when omitted.
+
+        Returns:
+            dict[str, Any]: ``data`` is ``{material, database, configuration}``;
+            ``material`` is ``None`` when none is assigned.
+
+        Example:
+            ```python
+            await get_material()
+            ```
+        """
+        input_data = normalize_input(input_data, GetMaterialInput)
+        _supports("get_material")
+        result = await adapter.get_material(input_data.configuration)
+        require_success(result, context="Failed to read the material")
+        material = (result.data or {}).get("material")
+        return _success(
+            result, f"Material: {material}" if material else "No material assigned"
+        )
+
+    @mcp.tool()
+    async def set_material(input_data: SetMaterialInput) -> dict[str, Any]:
+        """Assign a library material to the active part.
+
+        The material drives mass properties (``get_mass_properties``) and what
+        a title block's Material field shows. The name must match the library
+        exactly; find it with ``list_available_materials``. The material is
+        read back after assignment, so success means it really applied.
+
+        Args:
+            input_data (SetMaterialInput): ``material_name``, plus optional
+                ``database`` and ``configuration``.
+
+        Returns:
+            dict[str, Any]: ``data`` is ``{material, database, configuration}``
+            as read back from the part. ``not_found`` when the library does
+            not hold that name (the part is left unchanged).
+
+        Example:
+            ```python
+            await set_material({"material_name": "AISI 1020"})
+            ```
+        """
+        input_data = normalize_input(input_data, SetMaterialInput)
+        _supports("set_material")
+        result = await adapter.set_material(
+            input_data.material_name, input_data.database, input_data.configuration
+        )
+        require_success(result, context="Failed to assign the material")
+        return _success(result, f"Assigned {input_data.material_name}")
+
+    @mcp.tool()
+    async def list_available_materials(
+        input_data: ListMaterialsInput | None = None,
+    ) -> dict[str, Any]:
+        """List materials in the installed SolidWorks material libraries.
+
+        Read-only; parses every ``.sldmat`` library SolidWorks is configured
+        to use. Filter with ``search`` (name or classification substring, e.g.
+        ``"steel"`` or ``"6061"``) and pass the exact ``name`` to
+        ``set_material``.
+
+        Args:
+            input_data (ListMaterialsInput | None): ``search`` to filter;
+                omit for every material.
+
+        Returns:
+            dict[str, Any]: ``data`` is a list of ``{name, classification,
+            database}``; ``message`` says how many of the libraries' materials
+            matched and which folders were read.
+
+        Example:
+            ```python
+            await list_available_materials({"search": "1020"})
+            ```
+        """
+        input_data = normalize_input(input_data, ListMaterialsInput)
+        _supports("list_available_materials")
+        result = await adapter.list_available_materials(input_data.search)
+        require_success(result, context="Failed to list materials")
+        searched = result.metadata or {}
+        found = len(result.data or [])
+        message = f"Found {found} material(s)"
+        if "total" in searched:
+            message += (
+                f" of {searched['total']} in {'; '.join(searched.get('folders', []))}"
+            )
+        return _success(result, message)
+
+    @mcp.tool()
+    async def get_custom_properties(
+        input_data: CustomPropertiesInput | None = None,
+    ) -> dict[str, Any]:
+        """Read the active document's custom properties.
+
+        Read-only. File-level properties (the default) are what drawing title
+        blocks and BOMs usually link to; pass ``configuration`` for
+        configuration-specific ones.
+
+        Args:
+            input_data (CustomPropertiesInput | None): ``configuration``;
+                file-level properties when omitted.
+
+        Returns:
+            dict[str, Any]: ``data`` is ``{configuration, properties}``, where
+            ``properties`` maps each name to ``{value, resolved}`` (``value``
+            may be a ``$PRP:`` link; ``resolved`` is what it evaluates to).
+
+        Example:
+            ```python
+            await get_custom_properties()
+            ```
+        """
+        input_data = normalize_input(input_data, CustomPropertiesInput)
+        _supports("get_custom_properties")
+        result = await adapter.get_custom_properties(input_data.configuration)
+        require_success(result, context="Failed to read custom properties")
+        count = len((result.data or {}).get("properties", {}))
+        return _success(result, f"Read {count} custom propert(ies)")
+
+    @mcp.tool()
+    async def set_custom_property(input_data: SetCustomPropertyInput) -> dict[str, Any]:
+        """Create or overwrite one text custom property on the active document.
+
+        Typical names: ``PartNo``, ``Description``, ``DrawnBy``, ``Revision``.
+        The value is read back after writing, so success means it was stored.
+
+        Args:
+            input_data (SetCustomPropertyInput): ``name`` and ``value``, plus
+                an optional ``configuration``.
+
+        Returns:
+            dict[str, Any]: ``data`` is ``{name, value, resolved,
+            configuration}`` as read back.
+
+        Example:
+            ```python
+            await set_custom_property({"name": "PartNo", "value": "LIVE-001"})
+            ```
+        """
+        input_data = normalize_input(input_data, SetCustomPropertyInput)
+        _supports("set_custom_property")
+        result = await adapter.set_custom_property(
+            input_data.name, input_data.value, input_data.configuration
+        )
+        require_success(result, context="Failed to set the custom property")
+        return _success(result, f"Set custom property {input_data.name}")
+
+    @mcp.tool()
+    async def export_flat_pattern(input_data: ExportFlatPatternInput) -> dict[str, Any]:
+        """Export the active sheet-metal part's flat pattern to DXF or DWG.
+
+        Exports the flat-pattern geometry only (no bend lines or sketches),
+        for laser or waterjet cutting. A part without a sheet-metal body is
+        refused (``not_found``) and nothing is written.
+
+        Args:
+            input_data (ExportFlatPatternInput): ``file_path`` ending in
+                ``.dxf`` or ``.dwg``.
+
+        Returns:
+            dict[str, Any]: ``data`` is ``{file_path, size_bytes}`` of the
+            written file.
+
+        Example:
+            ```python
+            await export_flat_pattern({"file_path": "C:/cut/bracket.dxf"})
+            ```
+        """
+        input_data = normalize_input(input_data, ExportFlatPatternInput)
+        _supports("export_flat_pattern")
+        result = await adapter.export_flat_pattern(input_data.file_path)
+        require_success(result, context="Failed to export the flat pattern")
+        written = (result.data or {}).get("file_path")
+        return _success(result, f"Exported the flat pattern to {written}")
+
+    return 8

solidworks_mcp/tools/error_classifier.py

@@ -0,0 +1,232 @@
+"""Classify tool failures into actionable error categories.
+
+The MCP tool error boundary (``tool_boundary``) asks this module what kind of
+failure it is looking at, so the payload can carry an ``error_type`` and a
+``hint`` telling the caller what to do next instead of an opaque message.
+
+Adapter errors usually arrive as *strings* - ``_handle_com_operation`` flattens
+COM exceptions to ``"COM error in <op>: (<hresult>, '<text>', ...)"`` - so every
+rule can match on the message text, and COM rules also on the HRESULT taken
+from either a ``com_error`` exception or that text.
+
+Rules are evaluated in order; the first match wins. Add a category by
+appending a rule - callers never change.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# HRESULTs (signed 32-bit, as pywin32 reports them).
+RPC_E_DISCONNECTED = -2147417848  # 0x80010108
+RPC_S_SERVER_UNAVAILABLE = -2147023174  # 0x800706BA
+RPC_S_CALL_FAILED = -2147023170  # 0x800706BE
+DISP_E_MEMBERNOTFOUND = -2147352573  # 0x80020003
+DISP_E_TYPEMISMATCH = -2147352571  # 0x80020005
+
+_HRESULT_IN_TEXT = re.compile(r"\((-\d{9,10}),")
+
+OPERATION_FAILED = "operation_failed"
+INTERNAL = "internal"
+INVALID_INPUT = "invalid_input"
+NOT_SUPPORTED = "not_supported"
+NOT_SUPPORTED_HINT = (
+    "The active adapter cannot perform this operation. Use the real SolidWorks "
+    "adapter, another tool, or do this step in SolidWorks directly."
+)
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The category of a failure and the next step to suggest."""
+
+    error_type: str
+    hint: str
+
+
+@dataclass(frozen=True)
+class ErrorRule:
+    """Matches a failure by HRESULT and/or a case-insensitive message pattern."""
+
+    error_type: str
+    hint: str
+    hresults: frozenset[int] = field(default_factory=frozenset)
+    patterns: tuple[str, ...] = ()
+
+    def matches(self, message: str, hresult: int | None) -> bool:
+        """Return True when the HRESULT or any pattern matches."""
+        if hresult is not None and hresult in self.hresults:
+            return True
+        return any(re.search(p, message, re.IGNORECASE) for p in self.patterns)
+
+
+DEFAULT_RULES: tuple[ErrorRule, ...] = (
+    ErrorRule(
+        error_type="solidworks_unavailable",
+        hint=(
+            "SolidWorks is not reachable - it was closed or crashed. Restart "
+            "SolidWorks (and the MCP server if it still fails), then retry."
+        ),
+        hresults=frozenset(
+            {RPC_E_DISCONNECTED, RPC_S_SERVER_UNAVAILABLE, RPC_S_CALL_FAILED}
+        ),
+        patterns=(
+            r"rpc server is unavailable",
+            r"object invoked has disconnected",
+            r"not connected to solidworks",
+            r"solidworks (application )?(is )?not connected",
+            r"solidworks is not running",
+        ),
+    ),
+    ErrorRule(
+        error_type="com_wrong_thread",
+        hint=(
+            "A SolidWorks call ran off the thread that connected - a server "
+            "bug. Report the tool name; restart the MCP server to recover."
+        ),
+        patterns=(r"belong to the thread that called connect",),
+    ),
+    ErrorRule(
+        error_type="circuit_open",
+        hint=(
+            "Calls to this operation are paused after repeated failures. Fix "
+            "the underlying error, then retry after the breaker timeout."
+        ),
+        patterns=(r"circuit breaker is (open|half[_-]open)",),
+    ),
+    ErrorRule(
+        error_type="com_member_not_found",
+        hint=(
+            "SolidWorks could not resolve this API member. Usually a server "
+            "bug: a method called without being flagged as one (report the "
+            "tool name). After a SolidWorks upgrade it can be a stale type "
+            "cache: delete %TEMP%\\gen_py and restart the MCP server."
+        ),
+        hresults=frozenset({DISP_E_MEMBERNOTFOUND}),
+        patterns=(r"member not found",),
+    ),
+    ErrorRule(
+        error_type="com_type_mismatch",
+        hint=(
+            "SolidWorks rejected an argument's COM type. This is a server bug; "
+            "report the tool name and arguments."
+        ),
+        hresults=frozenset({DISP_E_TYPEMISMATCH}),
+        patterns=(r"type mismatch",),
+    ),
+    ErrorRule(
+        error_type=NOT_SUPPORTED,
+        hint=NOT_SUPPORTED_HINT,
+        patterns=(
+            r"does not support",
+            r"no adapter capability",
+            r"only available on windows",
+            r"not available",
+        ),
+    ),
+    ErrorRule(
+        error_type="wrong_document_type",
+        hint=(
+            "The active document is the wrong kind for this tool. Create or "
+            "activate the right one (create_part, create_assembly, "
+            "create_drawing or activate_document), then retry."
+        ),
+        patterns=(
+            r"(requires|needs) an? (active )?(part|assembly|drawing)"
+            r"( or (part|assembly|drawing))? document",
+        ),
+    ),
+    ErrorRule(
+        error_type="no_active_sketch",
+        hint="Create or open a sketch first (create_sketch), then retry.",
+        patterns=(r"no active sketch",),
+    ),
+    ErrorRule(
+        error_type="no_active_document",
+        hint=(
+            "Open or create a document first (open_model / create_part), or "
+            "activate one with activate_document, then retry."
+        ),
+        patterns=(r"no active (model|document)",),
+    ),
+    ErrorRule(
+        error_type="feature_not_built",
+        hint=(
+            "SolidWorks accepted the call but the geometry gave it nothing to "
+            "build. For a cut: the profile must be a closed loop that overlaps "
+            "the solid within the depth; one-direction cuts already try both "
+            "directions, so change the sketch, its plane, the depth or use "
+            "end_condition 'ThroughAll' rather than retrying as is."
+        ),
+        patterns=(r"built no feature",),
+    ),
+    ErrorRule(
+        error_type="not_found",
+        hint=(
+            "Check the name or path - list what exists first (list_features, "
+            "list_open_documents, list_drawing_views) and use an exact name."
+        ),
+        patterns=(
+            r"\bnot found\b",
+            r"does not exist",
+            r"\bno such\b",
+            r"\bno [\w.-]+( \w+)? found\b",
+            r"\bhas no (\w+ )?(edges|faces)\b",
+            r"\bhas no [\w-]+ body\b",
+            r"\bno view named\b",
+        ),
+    ),
+)
+
+_FALLBACK_HINTS = {
+    OPERATION_FAILED: (
+        "The SolidWorks operation failed. Read the message for the cause, "
+        "adjust the inputs, and retry."
+    ),
+    INTERNAL: (
+        "Unexpected server error - this is a bug, not a modelling problem. "
+        "Report the tool name, arguments and this message."
+    ),
+}
+
+
+def extract_hresult(message: str, exc: BaseException | None = None) -> int | None:
+    """Return the COM HRESULT from a ``com_error`` or from flattened text."""
+    if exc is not None:
+        args = getattr(exc, "args", ())
+        if args and isinstance(args[0], int):
+            return args[0]
+    match = _HRESULT_IN_TEXT.search(message)
+    return int(match.group(1)) if match else None
+
+
+class ErrorClassifier:
+    """Map a failure to a :class:`Classification` using ordered rules."""
+
+    def __init__(self, rules: tuple[ErrorRule, ...] = DEFAULT_RULES) -> None:
+        self._rules = rules
+
+    def classify(
+        self,
+        message: str,
+        exc: BaseException | None = None,
+        *,
+        fallback: str = OPERATION_FAILED,
+    ) -> Classification:
+        """Classify ``message`` (and ``exc`` when there is one).
+
+        Args:
+            message: The error text the caller will see.
+            exc: The exception, when the failure was raised rather than returned.
+            fallback: Category for an unrecognised failure: ``operation_failed``
+                for adapter errors, ``internal`` for unexpected exceptions.
+
+        Returns:
+            Classification: The first matching rule, else the fallback.
+        """
+        hresult = extract_hresult(message, exc)
+        for rule in self._rules:
+            if rule.matches(message, hresult):
+                return Classification(rule.error_type, rule.hint)
+        return Classification(fallback, _FALLBACK_HINTS[fallback])