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

solidworks_mcp/tools/analysis.py

@@ -0,0 +1,723 @@
+"""Analysis tools for SolidWorks MCP Server.
+
+Use these after a model or assembly already exists. Recommended order:
+calculate_mass_properties or get_mass_properties, then check_interference, then
+analyze_geometry, then get_material_properties. These tools are for validation and
+inspection, not for creating geometry. verify_model checks the finished model
+against expected values in one call.
+"""
+
+from typing import Any
+
+from fastmcp import FastMCP
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..adapters.base import SolidWorksAdapter
+from .input_compat import CompatInput
+from .tool_boundary import (
+    InvalidInputError,
+    normalize_input,
+    require_capability,
+    require_success,
+    with_tool_boundary,
+)
+
+# Input schemas using Python 3.14 built-in types
+
+
+class MassPropertiesInput(CompatInput):
+    """Input schema for mass properties analysis.
+
+    Attributes:
+        include_hidden (bool): The include hidden value.
+        model_path (str | None): The model path value.
+        reference_coordinate_system (str | None): The reference coordinate system value.
+        units (str): The units value.
+    """
+
+    model_path: str | None = Field(default=None, description="Path to the model file")
+    units: str = Field(default="metric", description="Units for mass properties")
+    include_hidden: bool = Field(default=False, description="Include hidden components")
+    reference_coordinate_system: str | None = Field(
+        default=None, description="Reference coordinate system alias"
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        """Provide model post init support for the mass properties input.
+
+        Args:
+            __context (Any): The context value.
+
+        Returns:
+            None: None.
+
+        Raises:
+            ValueError: If the operation cannot be completed.
+        """
+        valid_units = {"metric", "kg", "g", "lb"}
+        if self.units not in valid_units:
+            raise ValueError(f"units must be one of {sorted(valid_units)}")
+
+
+class InterferenceCheckInput(CompatInput):
+    """Input schema for interference checking.
+
+    Attributes:
+        assembly_path (str | None): The assembly path value.
+        check_all_components (bool): The check all components value.
+        components (list[str]): The components value.
+        include_hidden (bool): The include hidden value.
+        tolerance (float): The tolerance value.
+    """
+
+    assembly_path: str | None = Field(default=None, description="Assembly path alias")
+    check_all_components: bool = Field(
+        default=False, description="Check all components alias"
+    )
+    include_hidden: bool = Field(default=False, description="Include hidden components")
+    components: list[str] = Field(
+        default_factory=list,
+        description="List of component names to check for interference",
+    )
+    tolerance: float = Field(
+        default=0.001, description="Interference detection tolerance in mm"
+    )
+
+
+class GeometryAnalysisInput(BaseModel):
+    """Input schema for geometry analysis.
+
+    Attributes:
+        analysis_type (str): The analysis type value.
+        parameters (dict[str, Any] | None): The parameters value.
+    """
+
+    analysis_type: str = Field(
+        description="Type of analysis (curvature, draft, thickness, etc.)"
+    )
+    parameters: dict[str, Any] | None = Field(
+        default=None, description="Analysis-specific parameters"
+    )
+
+
+class VerifyModelInput(BaseModel):
+    """Expectations for ``verify_model``; every field is optional.
+
+    Unknown fields are rejected so a misspelt expectation (``volume`` for
+    ``volume_mm3``) fails loudly instead of silently not being checked.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    mass_kg: float | None = Field(
+        default=None, description="Expected mass in kg (depends on the material)"
+    )
+    volume_mm3: float | None = Field(default=None, description="Expected volume, mm³")
+    bounding_box_mm: tuple[float, float, float] | None = Field(
+        default=None,
+        description="Expected overall size [x, y, z] in mm, in model axes",
+    )
+    feature_count: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Expected number of modelling features (extrudes, cuts, fillets, "
+            "patterns...); sketches, the origin, folders and the three "
+            "default planes are not counted"
+        ),
+    )
+    solid_body_count: int | None = Field(
+        default=None, ge=0, description="Expected number of solid bodies (parts)"
+    )
+    component_count: int | None = Field(
+        default=None, ge=0, description="Expected top-level components (assemblies)"
+    )
+    mate_count: int | None = Field(
+        default=None, ge=0, description="Expected unsuppressed mates (assemblies)"
+    )
+    no_interference: bool | None = Field(
+        default=None,
+        description="true to require that no components overlap (assemblies)",
+    )
+    relative_tolerance: float = Field(
+        default=0.01,
+        ge=0,
+        description="Allowed relative error for mass and volume (0.01 = 1 %)",
+    )
+    length_tolerance_mm: float = Field(
+        default=0.1, ge=0, description="Allowed error per bounding-box axis, mm"
+    )
+
+
+#: Assembly-only expectations; asking for them on a part is a caller mistake.
+_ASSEMBLY_ONLY = ("component_count", "mate_count", "no_interference")
+
+#: ``GetTypeName2`` values that are tree furniture, not modelling features.
+_NON_MODELLING_TYPES = frozenset(
+    {
+        "ProfileFeature",
+        "3DProfileFeature",
+        "OriginProfileFeature",
+        "DetailCabinet",
+        "MateGroup",
+        "MateReferenceGroup",
+        "MaterialFolder",
+    }
+)
+
+#: SolidWorks always puts the three default planes first in the tree.
+_DEFAULT_PLANE_COUNT = 3
+
+
+def _count_modelling_features(descriptors: list[dict[str, Any]]) -> list[str]:
+    """Return the names of the document's own modelling features.
+
+    Skips component features, sketches, the origin, folders, the mate group
+    and the first three reference planes (the default ones, matched by
+    position so it works in any SolidWorks language).
+
+    Args:
+        descriptors: ``list_features`` rows.
+
+    Returns:
+        list[str]: Counted feature names, in tree order.
+    """
+    names: list[str] = []
+    planes_seen = 0
+    for row in descriptors:
+        if row.get("component") is not None:
+            continue
+        kind = str(row.get("type") or "")
+        if kind == "RefPlane":
+            planes_seen += 1
+            if planes_seen <= _DEFAULT_PLANE_COUNT:
+                continue
+        if kind in _NON_MODELLING_TYPES or kind.endswith("Folder"):
+            continue
+        names.append(str(row.get("name") or ""))
+    return names
+
+
+def _check(
+    name: str,
+    expected: Any,
+    actual: Any,
+    unit: str | None,
+    passed: bool | None,
+    tolerance: Any = None,
+    note: str | None = None,
+) -> dict[str, Any]:
+    """Build one ``checks`` entry."""
+    entry: dict[str, Any] = {
+        "name": name,
+        "expected": expected,
+        "actual": actual,
+        "tolerance": tolerance,
+        "unit": unit,
+        "passed": passed,
+    }
+    if note:
+        entry["note"] = note
+    elif passed is None:
+        entry["note"] = "Could not be measured"
+    return entry
+
+
+def _relative_check(
+    name: str, expected: float, actual: Any, tolerance: float, unit: str
+) -> dict[str, Any]:
+    """Compare within a relative tolerance; ``None`` actual is unmeasured."""
+    if not isinstance(actual, (int, float)):
+        return _check(name, expected, None, unit, None, tolerance)
+    passed = abs(actual - expected) <= tolerance * abs(expected)
+    return _check(name, expected, actual, unit, passed, tolerance)
+
+
+def _exact_check(name: str, expected: int, actual: Any, unit: str) -> dict[str, Any]:
+    """Compare a count exactly; ``None`` actual is unmeasured."""
+    if not isinstance(actual, int):
+        return _check(name, expected, None, unit, None)
+    return _check(name, expected, actual, unit, actual == expected)
+
+
+def _box_check(
+    expected: tuple[float, float, float], box: Any, tolerance: float
+) -> dict[str, Any]:
+    """Compare bounding-box size per axis.
+
+    When the axes fail but the sorted sizes match, the note says so: the part
+    is right but was built in a different orientation than expected.
+    """
+    want = list(expected)
+    size = box.get("size") if isinstance(box, dict) else None
+    if not isinstance(size, list) or len(size) != 3:
+        return _check("bounding_box_mm", want, None, "mm", None, tolerance)
+    passed = all(abs(a - e) <= tolerance for a, e in zip(size, want, strict=True))
+    note = None
+    if not passed and all(
+        abs(a - e) <= tolerance for a, e in zip(sorted(size), sorted(want), strict=True)
+    ):
+        note = (
+            "Sizes match with the axes reordered: the part is the right size "
+            "but oriented differently (check which plane each sketch is on)"
+        )
+    return _check("bounding_box_mm", want, size, "mm", passed, tolerance, note)
+
+
+def _verdict(checks: list[dict[str, Any]]) -> str:
+    """Overall verdict: fail beats inconclusive beats pass."""
+    if not checks:
+        return "report_only"
+    outcomes = [check["passed"] for check in checks]
+    if False in outcomes:
+        return "fail"
+    if None in outcomes:
+        return "inconclusive"
+    return "pass"
+
+
+def _verdict_message(verdict: str, checks: list[dict[str, Any]], doc: str) -> str:
+    """One-line summary naming the checks that need attention."""
+    total = len(checks)
+    passed = sum(1 for check in checks if check["passed"] is True)
+    failed = [check["name"] for check in checks if check["passed"] is False]
+    unknown = [check["name"] for check in checks if check["passed"] is None]
+    if verdict == "report_only":
+        return f"Measured the active {doc}; no expectations were given"
+    if verdict == "pass":
+        return f"Verification passed: {passed} of {total} checks passed"
+    if verdict == "fail":
+        return (
+            f"Verification failed: {passed} of {total} checks passed "
+            f"(failed: {', '.join(failed)})"
+        )
+    return (
+        f"Verification inconclusive: {passed} of {total} checks passed, "
+        f"could not measure: {', '.join(unknown)}"
+    )
+
+
+async def register_analysis_tools(
+    mcp: FastMCP, adapter: SolidWorksAdapter, config: dict[str, Any]
+) -> int:
+    """Register analysis tools with FastMCP.
+
+    Registers comprehensive analysis tools for SolidWorks model evaluation including mass
+    properties, interference checking, geometry analysis, and material properties. These
+    tools provide critical engineering data for design validation and optimization.
+
+    Args:
+        mcp (FastMCP): The mcp value.
+        adapter (SolidWorksAdapter): Adapter instance used for the operation.
+        config (dict[str, Any]): Configuration values for the operation.
+
+    Returns:
+        int: The computed numeric result.
+
+    Example:
+                        ```python
+                        from solidworks_mcp.tools.analysis import register_analysis_tools
+
+                        tool_count = await register_analysis_tools(mcp, adapter, config)
+                        print(f"Registered {tool_count} analysis tools")
+                        ```
+
+                    Note:
+                        Analysis tools require an active SolidWorks document with geometry.
+                        Some analyses may require specific material assignments for accurate results.
+    """
+    mcp = with_tool_boundary(mcp)
+    tool_count = 0
+
+    @mcp.tool()
+    async def calculate_mass_properties(
+        input_data: MassPropertiesInput,
+    ) -> dict[str, Any]:
+        """Get mass properties of the current SolidWorks model.
+
+        Calculates and returns comprehensive mass properties for the active model including
+        volume, surface area, mass, center of mass, and moments of inertia. Essential for
+        engineering analysis, weight calculations, and structural design.
+
+        Args:
+            input_data (MassPropertiesInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            ```python
+                            result = await get_mass_properties()
+
+                            if result["status"] == "success":
+                                props = result["mass_properties"]
+                                print(f"Volume: {props['volume']['value']} {props['volume']['units']}")
+                                print(f"Mass: {props['mass']['value']} {props['mass']['units']}")
+
+                                com = props['center_of_mass']
+                                print(f"Center of Mass: ({com['x']}, {com['y']}, {com['z']}) mm")
+
+                                moi = props['moments_of_inertia']
+                                print(f"Moment of Inertia Ixx: {moi['Ixx']} kg·mm²")
+                            ```
+
+                        Note:
+                            - Requires active SolidWorks model with geometry
+                            - Material assignment affects mass calculations
+                            - Uses model units and coordinate system
+                            - Includes both geometric and inertial properties
+        """
+        if hasattr(adapter, "calculate_mass_properties"):
+            result = await adapter.calculate_mass_properties(input_data.model_dump())
+            require_success(result, context="Failed to calculate mass properties")
+            return {
+                "status": "success",
+                "message": "Mass properties calculated successfully",
+                "data": result.data,
+                "execution_time": result.execution_time,
+            }
+
+        result = await adapter.get_mass_properties()
+
+        require_success(result, context="Failed to calculate mass properties")
+        props = result.data
+        assert props is not None
+        return {
+            "status": "success",
+            "message": "Mass properties calculated successfully",
+            "mass_properties": {
+                "volume": {"value": props.volume, "units": "mm³"},
+                "surface_area": {"value": props.surface_area, "units": "mm²"},
+                "mass": {"value": props.mass, "units": "kg"},
+                "center_of_mass": {
+                    "x": props.center_of_mass[0],
+                    "y": props.center_of_mass[1],
+                    "z": props.center_of_mass[2],
+                    "units": "mm",
+                },
+                "moments_of_inertia": {
+                    "Ixx": props.moments_of_inertia["Ixx"],
+                    "Iyy": props.moments_of_inertia["Iyy"],
+                    "Izz": props.moments_of_inertia["Izz"],
+                    "Ixy": props.moments_of_inertia["Ixy"],
+                    "Ixz": props.moments_of_inertia["Ixz"],
+                    "Iyz": props.moments_of_inertia["Iyz"],
+                    "units": "kg·mm²",
+                },
+                "principal_axes": props.principal_axes,
+            },
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def get_mass_properties(
+        input_data: MassPropertiesInput | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Backward-compatible alias for calculate_mass_properties.
+
+        Args:
+            input_data (MassPropertiesInput | dict[str, Any] | None): The input data value.
+                                                                      Defaults to None.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+        """
+        if input_data is None:
+            normalized_input = MassPropertiesInput()
+        elif isinstance(input_data, MassPropertiesInput):
+            normalized_input = input_data
+        else:
+            normalized_input = MassPropertiesInput.model_validate(input_data)
+        return await calculate_mass_properties(normalized_input)
+
+    @mcp.tool()
+    async def check_interference(input_data: InterferenceCheckInput) -> dict[str, Any]:
+        """Check for interference between components in an assembly.
+
+        Analyzes specified components for geometric interference (overlapping volumes) and
+        provides detailed interference detection results. Critical for assembly validation and
+        identifying design conflicts before manufacturing.
+
+        Args:
+            input_data (InterferenceCheckInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            ```python
+                            # Check specific components
+                            result = await check_interference({
+                                "components": ["Bracket-1", "Shaft-1", "Bearing-1"],
+                                "tolerance": 0.01
+                            })
+
+                            # Check all components with default tolerance
+                            result = await check_interference({
+                                "components": [],
+                                "tolerance": 0.001
+                            })
+
+                            if result["status"] == "success":
+                                results = result["interference_results"]
+                                print(f"Found {results['total_interferences']} interferences")
+
+                                for interference in results["interference_details"]:
+                                    print(f"Interference between {interference['component_1']} and {interference['component_2']}")
+                                    print(f"Volume: {interference['volume']} mm³")
+                            ```
+        """
+        require_capability(
+            adapter,
+            "check_interference",
+            "Active adapter does not support check_interference; no "
+            "interference analysis was performed. Use SolidWorks "
+            "directly (Tools > Interference Detection) to check this "
+            "assembly.",
+        )
+        result = await adapter.check_interference(input_data.model_dump())
+        require_success(result, "Interference check failed")
+        return {
+            "status": "success",
+            "message": "Interference check completed",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def analyze_geometry(input_data: GeometryAnalysisInput) -> dict[str, Any]:
+        """Handle analyze geometry.
+
+        This tool provides various geometry analysis capabilities like curvature analysis, draft
+        analysis, thickness analysis, etc.
+
+        Args:
+            input_data (GeometryAnalysisInput): The input data value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+        """
+        require_capability(
+            adapter,
+            "analyze_geometry",
+            f"Active adapter does not support analyze_geometry; no "
+            f"{input_data.analysis_type} analysis was performed.",
+        )
+        result = await adapter.analyze_geometry(input_data.model_dump())
+        require_success(result, "Failed to analyze geometry")
+        return {
+            "status": "success",
+            "message": f"Geometry analysis ({input_data.analysis_type}) completed",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def get_material_properties() -> dict[str, Any]:
+        """Get material properties of the current model.
+
+        This tool retrieves the material properties assigned to the model including density,
+        elastic modulus, yield strength, etc.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+        """
+        require_capability(
+            adapter,
+            "get_material_properties",
+            "Active adapter does not support get_material_properties",
+        )
+        result = await adapter.get_material_properties()
+        require_success(result, "Failed to get material properties")
+        return {
+            "status": "success",
+            "message": "Material properties retrieved successfully",
+            "data": result.data,
+            "execution_time": result.execution_time,
+        }
+
+    @mcp.tool()
+    async def verify_model(
+        input_data: VerifyModelInput | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Check the active part or assembly against what you meant to build.
+
+        Call this as the last step of a build (and whenever a step looks
+        suspicious). A modelling tool returning success does not prove the
+        geometry is right; this reads the model back and compares it with
+        your expectations. Give only the expectations you know; each becomes
+        one check. With no expectations it just reports what it measured.
+
+        Units: mm, mm³ and kg. ``bounding_box_mm`` is the overall size
+        ``[x, y, z]`` in model axes (a sketch on the Front Plane extrudes
+        along z). Widen ``relative_tolerance`` when your hand calculation
+        ignores fillets or chamfers, and ``length_tolerance_mm`` when
+        ``measured.bounding_box_method`` is ``assembly_box`` (SolidWorks'
+        assembly box can be slightly larger than the parts). Mass depends on
+        the assigned material; without one SolidWorks uses a default density.
+
+        Each check reports ``expected``, ``actual``, ``tolerance`` and
+        ``passed``: ``true``, ``false``, or ``null`` when the value could not
+        be measured (never counted as a pass). ``verdict`` is ``pass``,
+        ``fail``, ``inconclusive`` (nothing failed, something unmeasured) or
+        ``report_only``. ``status`` stays ``success`` when the model does not
+        match: the tool worked, the model is what failed.
+
+        Args:
+            input_data (VerifyModelInput | dict[str, Any] | None): Expectations
+                and tolerances. Defaults to None (report only).
+
+        Returns:
+            dict[str, Any]: ``verdict``, ``checks``, ``measured`` and the usual
+            ``status``/``message``/``execution_time``.
+
+        Example:
+            ```python
+            await verify_model({
+                "volume_mm3": 50000,
+                "bounding_box_mm": [100, 50, 10],
+                "feature_count": 1,
+                "solid_body_count": 1,
+            })
+            ```
+        """
+        expectations = normalize_input(input_data, VerifyModelInput)
+        require_capability(
+            adapter,
+            "get_model_geometry_summary",
+            "Active adapter cannot read the model back, so nothing was verified.",
+        )
+        summary_result = await adapter.get_model_geometry_summary()
+        require_success(summary_result, context="Failed to read the model back")
+        summary = dict(summary_result.data or {})
+        is_assembly = summary.get("document_type") == "assembly"
+
+        if not is_assembly:
+            misplaced = [
+                name
+                for name in _ASSEMBLY_ONLY
+                if getattr(expectations, name) is not None
+            ]
+            if misplaced:
+                raise InvalidInputError(
+                    f"{', '.join(misplaced)} only apply to assemblies; the active "
+                    "document is a part"
+                )
+
+        measured: dict[str, Any] = dict(summary)
+        checks: list[dict[str, Any]] = []
+        rel = expectations.relative_tolerance
+
+        if expectations.mass_kg is not None:
+            mass_result = await adapter.get_mass_properties()
+            mass = (
+                mass_result.data.mass
+                if mass_result.is_success and mass_result.data
+                else None
+            )
+            material_result = await adapter.get_material()
+            material = (
+                (material_result.data or {}).get("material")
+                if material_result.is_success
+                else None
+            )
+            measured["mass_kg"] = mass
+            measured["material"] = material
+            check = _relative_check("mass_kg", expectations.mass_kg, mass, rel, "kg")
+            if check["passed"] is False:
+                check["note"] = (
+                    f"Material: {material}"
+                    if material
+                    else "No material assigned; SolidWorks used a default density"
+                )
+            checks.append(check)
+
+        if expectations.volume_mm3 is not None:
+            checks.append(
+                _relative_check(
+                    "volume_mm3",
+                    expectations.volume_mm3,
+                    summary.get("volume_mm3"),
+                    rel,
+                    "mm³",
+                )
+            )
+
+        if expectations.bounding_box_mm is not None:
+            checks.append(
+                _box_check(
+                    expectations.bounding_box_mm,
+                    summary.get("bounding_box_mm"),
+                    expectations.length_tolerance_mm,
+                )
+            )
+
+        if expectations.feature_count is not None:
+            features_result = await adapter.list_features()
+            names = (
+                _count_modelling_features(features_result.data or [])
+                if features_result.is_success
+                else None
+            )
+            measured["features"] = names
+            checks.append(
+                _exact_check(
+                    "feature_count",
+                    expectations.feature_count,
+                    None if names is None else len(names),
+                    "features",
+                )
+            )
+
+        for name, unit in (
+            ("solid_body_count", "bodies"),
+            ("component_count", "components"),
+            ("mate_count", "mates"),
+        ):
+            expected = getattr(expectations, name)
+            if expected is not None:
+                checks.append(_exact_check(name, expected, summary.get(name), unit))
+
+        if expectations.no_interference is not None:
+            interference = await adapter.check_interference({})
+            found = (
+                (interference.data or {}).get("interference_found")
+                if interference.is_success
+                else None
+            )
+            measured["interference"] = (
+                interference.data if interference.is_success else None
+            )
+            clear = None if found is None else not found
+            checks.append(
+                _check(
+                    "no_interference",
+                    expectations.no_interference,
+                    clear,
+                    None,
+                    None if clear is None else clear == expectations.no_interference,
+                    note=None if interference.is_success else interference.error,
+                )
+            )
+
+        verdict = _verdict(checks)
+        return {
+            "status": "success",
+            "message": _verdict_message(
+                verdict, checks, str(summary.get("document_type") or "document")
+            ),
+            "verdict": verdict,
+            "checks": checks,
+            "measured": measured,
+            "execution_time": summary_result.execution_time,
+        }
+
+    # Future analysis tools:
+    # - perform_fea_analysis (if FEA capabilities are available)
+    # - analyze_flow (computational fluid dynamics)
+    # - thermal_analysis
+    # - vibration_analysis
+    # - stress_concentration_analysis
+
+    tool_count = 4  # Keep legacy reported count expected by tests
+    return tool_count