mcp-server-mcsa 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

mcp_server_mcsa/__init__.py

@@ -1,37 +1,37 @@
-"""MCP Server for Motor Current Signature Analysis (MCSA).
-
-Run as a CLI:
-    mcp-server-mcsa
-
-Or via Python:
-    python -m mcp_server_mcsa
-"""
-
-from __future__ import annotations
-
-__version__ = "0.1.0"
-
-
-def main() -> None:
-    """CLI entry point for the MCSA MCP server."""
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        prog="mcp-server-mcsa",
-        description="MCP server for Motor Current Signature Analysis (MCSA)",
-    )
-    parser.add_argument(
-        "--transport",
-        choices=["stdio"],
-        default="stdio",
-        help="MCP transport (default: stdio)",
-    )
-    args = parser.parse_args()
-
-    from mcp_server_mcsa.server import serve
-
-    serve(transport=args.transport)
-
-
-if __name__ == "__main__":
-    main()
+"""MCP Server for Motor Current Signature Analysis (MCSA).
+
+Run as a CLI:
+    mcp-server-mcsa
+
+Or via Python:
+    python -m mcp_server_mcsa
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+def main() -> None:
+    """CLI entry point for the MCSA MCP server."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="mcp-server-mcsa",
+        description="MCP server for Motor Current Signature Analysis (MCSA)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio"],
+        default="stdio",
+        help="MCP transport (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    from mcp_server_mcsa.server import serve
+
+    serve(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

mcp_server_mcsa/__main__.py

@@ -1,5 +1,5 @@
-"""Allow running as ``python -m mcp_server_mcsa``."""
-
-from mcp_server_mcsa import main
-
-main()
+"""Allow running as ``python -m mcp_server_mcsa``."""
+
+from mcp_server_mcsa import main
+
+main()

mcp_server_mcsa/analysis/__init__.py

@@ -1,19 +1,19 @@
-"""MCSA analysis library — core signal processing and fault detection modules."""
-
-from mcp_server_mcsa.analysis.motor import (
-    MotorParameters,
-    calculate_motor_parameters,
-)
-from mcp_server_mcsa.analysis.bearing import (
-    BearingGeometry,
-    BearingDefectFrequencies,
-    calculate_bearing_defect_frequencies,
-)
-
-__all__ = [
-    "MotorParameters",
-    "calculate_motor_parameters",
-    "BearingGeometry",
-    "BearingDefectFrequencies",
-    "calculate_bearing_defect_frequencies",
-]
+"""MCSA analysis library — core signal processing and fault detection modules."""
+
+from mcp_server_mcsa.analysis.bearing import (
+    BearingDefectFrequencies,
+    BearingGeometry,
+    calculate_bearing_defect_frequencies,
+)
+from mcp_server_mcsa.analysis.motor import (
+    MotorParameters,
+    calculate_motor_parameters,
+)
+
+__all__ = [
+    "MotorParameters",
+    "calculate_motor_parameters",
+    "BearingGeometry",
+    "BearingDefectFrequencies",
+    "calculate_bearing_defect_frequencies",
+]

mcp_server_mcsa/analysis/bearing.py

@@ -1,147 +1,147 @@
-"""Bearing defect frequency calculations.
-
-Computes characteristic defect frequencies (BPFO, BPFI, BSF, FTF) from
-bearing geometry and shaft speed, plus their expected sidebands in the
-stator‑current spectrum.
-"""
-
-from __future__ import annotations
-
-import math
-from dataclasses import asdict, dataclass
-
-
-@dataclass(frozen=True)
-class BearingGeometry:
-    """Physical geometry of a rolling‑element bearing.
-
-    Attributes:
-        n_balls: Number of rolling elements.
-        ball_dia_mm: Ball (roller) diameter in mm.
-        pitch_dia_mm: Pitch (cage) diameter in mm.
-        contact_angle_deg: Contact angle in degrees.
-    """
-
-    n_balls: int
-    ball_dia_mm: float
-    pitch_dia_mm: float
-    contact_angle_deg: float = 0.0
-
-
-@dataclass(frozen=True)
-class BearingDefectFrequencies:
-    """Characteristic defect frequencies normalised to shaft speed.
-
-    All values are multiples of the shaft rotational frequency f_r.
-    Multiply by f_r (Hz) to get absolute frequencies.
-
-    Attributes:
-        bpfo: Ball Pass Frequency — Outer race.
-        bpfi: Ball Pass Frequency — Inner race.
-        bsf: Ball Spin Frequency.
-        ftf: Fundamental Train (cage) Frequency.
-    """
-
-    bpfo: float
-    bpfi: float
-    bsf: float
-    ftf: float
-
-    def to_dict(self) -> dict:
-        return asdict(self)
-
-    def absolute(self, shaft_freq_hz: float) -> dict:
-        """Return absolute frequencies in Hz given shaft speed."""
-        return {
-            "bpfo_hz": self.bpfo * shaft_freq_hz,
-            "bpfi_hz": self.bpfi * shaft_freq_hz,
-            "bsf_hz": self.bsf * shaft_freq_hz,
-            "ftf_hz": self.ftf * shaft_freq_hz,
-        }
-
-
-def calculate_bearing_defect_frequencies(
-    geometry: BearingGeometry,
-) -> BearingDefectFrequencies:
-    """Compute bearing defect frequencies (normalised to shaft speed).
-
-    Standard kinematic equations for rolling‑element bearings.
-
-    Args:
-        geometry: Bearing physical dimensions.
-
-    Returns:
-        Normalised defect frequencies (multiply by f_rotor to get Hz).
-
-    Raises:
-        ValueError: If geometry parameters are physically invalid.
-    """
-    n = geometry.n_balls
-    d = geometry.ball_dia_mm
-    D = geometry.pitch_dia_mm
-    alpha = math.radians(geometry.contact_angle_deg)
-
-    if n < 1:
-        raise ValueError(f"Number of balls must be ≥ 1, got {n}")
-    if d <= 0 or D <= 0:
-        raise ValueError("Ball and pitch diameters must be > 0")
-    if d >= D:
-        raise ValueError("Ball diameter must be < pitch diameter")
-
-    cos_alpha = math.cos(alpha)
-    ratio = d / D
-
-    # Fundamental Train Frequency (cage speed / shaft speed)
-    ftf = 0.5 * (1.0 - ratio * cos_alpha)
-
-    # Ball Pass Frequency — Outer race
-    bpfo = n * ftf
-
-    # Ball Pass Frequency — Inner race
-    bpfi = 0.5 * n * (1.0 + ratio * cos_alpha)
-
-    # Ball Spin Frequency
-    bsf = (D / (2.0 * d)) * (1.0 - (ratio * cos_alpha) ** 2)
-
-    return BearingDefectFrequencies(bpfo=bpfo, bpfi=bpfi, bsf=bsf, ftf=ftf)
-
-
-def bearing_current_sidebands(
-    defect_freqs: BearingDefectFrequencies,
-    shaft_freq_hz: float,
-    supply_freq_hz: float,
-    harmonics: int = 2,
-) -> dict:
-    """Compute expected stator‑current sidebands from bearing defects.
-
-    Bearing defects modulate motor torque, producing sidebands in the
-    stator current at f_supply ± k · f_defect.
-
-    Args:
-        defect_freqs: Normalised bearing defect frequencies.
-        shaft_freq_hz: Shaft rotational frequency in Hz.
-        supply_freq_hz: Supply (line) frequency in Hz.
-        harmonics: Number of sideband orders.
-
-    Returns:
-        Dictionary mapping defect type → list of sideband frequencies.
-    """
-    abs_freqs = defect_freqs.absolute(shaft_freq_hz)
-    fs = supply_freq_hz
-
-    result = {}
-    for name, fdef in abs_freqs.items():
-        label = name.replace("_hz", "")
-        sidebands = []
-        for k in range(1, harmonics + 1):
-            sidebands.append({
-                "order": k,
-                "lower_hz": fs - k * fdef,
-                "upper_hz": fs + k * fdef,
-            })
-        result[label] = {
-            "defect_frequency_hz": fdef,
-            "current_sidebands": sidebands,
-        }
-
-    return result
+"""Bearing defect frequency calculations.
+
+Computes characteristic defect frequencies (BPFO, BPFI, BSF, FTF) from
+bearing geometry and shaft speed, plus their expected sidebands in the
+stator‑current spectrum.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class BearingGeometry:
+    """Physical geometry of a rolling‑element bearing.
+
+    Attributes:
+        n_balls: Number of rolling elements.
+        ball_dia_mm: Ball (roller) diameter in mm.
+        pitch_dia_mm: Pitch (cage) diameter in mm.
+        contact_angle_deg: Contact angle in degrees.
+    """
+
+    n_balls: int
+    ball_dia_mm: float
+    pitch_dia_mm: float
+    contact_angle_deg: float = 0.0
+
+
+@dataclass(frozen=True)
+class BearingDefectFrequencies:
+    """Characteristic defect frequencies normalised to shaft speed.
+
+    All values are multiples of the shaft rotational frequency f_r.
+    Multiply by f_r (Hz) to get absolute frequencies.
+
+    Attributes:
+        bpfo: Ball Pass Frequency — Outer race.
+        bpfi: Ball Pass Frequency — Inner race.
+        bsf: Ball Spin Frequency.
+        ftf: Fundamental Train (cage) Frequency.
+    """
+
+    bpfo: float
+    bpfi: float
+    bsf: float
+    ftf: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def absolute(self, shaft_freq_hz: float) -> dict:
+        """Return absolute frequencies in Hz given shaft speed."""
+        return {
+            "bpfo_hz": self.bpfo * shaft_freq_hz,
+            "bpfi_hz": self.bpfi * shaft_freq_hz,
+            "bsf_hz": self.bsf * shaft_freq_hz,
+            "ftf_hz": self.ftf * shaft_freq_hz,
+        }
+
+
+def calculate_bearing_defect_frequencies(
+    geometry: BearingGeometry,
+) -> BearingDefectFrequencies:
+    """Compute bearing defect frequencies (normalised to shaft speed).
+
+    Standard kinematic equations for rolling‑element bearings.
+
+    Args:
+        geometry: Bearing physical dimensions.
+
+    Returns:
+        Normalised defect frequencies (multiply by f_rotor to get Hz).
+
+    Raises:
+        ValueError: If geometry parameters are physically invalid.
+    """
+    n = geometry.n_balls
+    d = geometry.ball_dia_mm
+    D = geometry.pitch_dia_mm
+    alpha = math.radians(geometry.contact_angle_deg)
+
+    if n < 1:
+        raise ValueError(f"Number of balls must be ≥ 1, got {n}")
+    if d <= 0 or D <= 0:
+        raise ValueError("Ball and pitch diameters must be > 0")
+    if d >= D:
+        raise ValueError("Ball diameter must be < pitch diameter")
+
+    cos_alpha = math.cos(alpha)
+    ratio = d / D
+
+    # Fundamental Train Frequency (cage speed / shaft speed)
+    ftf = 0.5 * (1.0 - ratio * cos_alpha)
+
+    # Ball Pass Frequency — Outer race
+    bpfo = n * ftf
+
+    # Ball Pass Frequency — Inner race
+    bpfi = 0.5 * n * (1.0 + ratio * cos_alpha)
+
+    # Ball Spin Frequency
+    bsf = (D / (2.0 * d)) * (1.0 - (ratio * cos_alpha) ** 2)
+
+    return BearingDefectFrequencies(bpfo=bpfo, bpfi=bpfi, bsf=bsf, ftf=ftf)
+
+
+def bearing_current_sidebands(
+    defect_freqs: BearingDefectFrequencies,
+    shaft_freq_hz: float,
+    supply_freq_hz: float,
+    harmonics: int = 2,
+) -> dict:
+    """Compute expected stator‑current sidebands from bearing defects.
+
+    Bearing defects modulate motor torque, producing sidebands in the
+    stator current at f_supply ± k · f_defect.
+
+    Args:
+        defect_freqs: Normalised bearing defect frequencies.
+        shaft_freq_hz: Shaft rotational frequency in Hz.
+        supply_freq_hz: Supply (line) frequency in Hz.
+        harmonics: Number of sideband orders.
+
+    Returns:
+        Dictionary mapping defect type → list of sideband frequencies.
+    """
+    abs_freqs = defect_freqs.absolute(shaft_freq_hz)
+    fs = supply_freq_hz
+
+    result = {}
+    for name, fdef in abs_freqs.items():
+        label = name.replace("_hz", "")
+        sidebands = []
+        for k in range(1, harmonics + 1):
+            sidebands.append({
+                "order": k,
+                "lower_hz": fs - k * fdef,
+                "upper_hz": fs + k * fdef,
+            })
+        result[label] = {
+            "defect_frequency_hz": fdef,
+            "current_sidebands": sidebands,
+        }
+
+    return result

mcp_server_mcsa/analysis/envelope.py

@@ -1,97 +1,96 @@
-"""Envelope (demodulation) analysis for MCSA.
-
-Hilbert‑transform‑based amplitude demodulation to extract low‑frequency
-modulation patterns caused by mechanical faults (bearing defects,
-eccentricity, load oscillations).
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from numpy.typing import NDArray
-from scipy import signal as sig
-
-
-def hilbert_envelope(
-    x: NDArray[np.floating],
-) -> NDArray[np.floating]:
-    """Compute the amplitude envelope of a signal via the Hilbert transform.
-
-    Args:
-        x: Input signal (real‑valued).
-
-    Returns:
-        Instantaneous amplitude (envelope) array.
-    """
-    analytic = sig.hilbert(x)
-    return np.abs(analytic)
-
-
-def instantaneous_frequency(
-    x: NDArray[np.floating],
-    fs: float,
-) -> NDArray[np.floating]:
-    """Compute instantaneous frequency via the Hilbert transform.
-
-    Args:
-        x: Input signal.
-        fs: Sampling frequency in Hz.
-
-    Returns:
-        Instantaneous frequency array in Hz (length = len(x) - 1).
-    """
-    analytic = sig.hilbert(x)
-    phase = np.unwrap(np.angle(analytic))
-    inst_freq = np.diff(phase) / (2.0 * np.pi) * fs
-    return inst_freq
-
-
-def envelope_spectrum(
-    x: NDArray[np.floating],
-    fs: float,
-    bandpass: tuple[float, float] | None = None,
-    filter_order: int = 5,
-) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
-    """Compute the spectrum of the signal envelope.
-
-    Typical workflow for bearing / mechanical fault detection:
-      1. Optional bandpass to isolate a resonance band
-      2. Hilbert envelope
-      3. Remove DC of envelope
-      4. FFT of envelope → low‑frequency modulation spectrum
-
-    Args:
-        x: Input current signal.
-        fs: Sampling frequency in Hz.
-        bandpass: Optional (low, high) bandpass range in Hz before
-                  computing the envelope (e.g. to isolate a resonance).
-        filter_order: Butterworth filter order for bandpass.
-
-    Returns:
-        (frequencies, amplitudes) of the envelope spectrum.
-    """
-    y = x.copy()
-
-    # Optional bandpass
-    if bandpass is not None:
-        nyq = fs / 2.0
-        low, high = bandpass
-        if 0 < low < high < nyq:
-            sos = sig.butter(filter_order, [low / nyq, high / nyq], btype="bandpass", output="sos")
-            y = sig.sosfiltfilt(sos, y)
-
-    # Envelope
-    env = hilbert_envelope(y)
-
-    # Remove DC from envelope
-    env = env - np.mean(env)
-
-    # FFT of envelope
-    n = len(env)
-    n_pos = n // 2 + 1
-    freqs = np.fft.rfftfreq(n, d=1.0 / fs)
-    X = np.fft.rfft(env)
-    amps = (2.0 / n) * np.abs(X)
-    amps[0] /= 2.0
-
-    return freqs, amps
+"""Envelope (demodulation) analysis for MCSA.
+
+Hilbert‑transform‑based amplitude demodulation to extract low‑frequency
+modulation patterns caused by mechanical faults (bearing defects,
+eccentricity, load oscillations).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import signal as sig
+
+
+def hilbert_envelope(
+    x: NDArray[np.floating],
+) -> NDArray[np.floating]:
+    """Compute the amplitude envelope of a signal via the Hilbert transform.
+
+    Args:
+        x: Input signal (real‑valued).
+
+    Returns:
+        Instantaneous amplitude (envelope) array.
+    """
+    analytic: NDArray[np.complexfloating] = sig.hilbert(x)  # type: ignore[assignment]
+    return np.abs(analytic)
+
+
+def instantaneous_frequency(
+    x: NDArray[np.floating],
+    fs: float,
+) -> NDArray[np.floating]:
+    """Compute instantaneous frequency via the Hilbert transform.
+
+    Args:
+        x: Input signal.
+        fs: Sampling frequency in Hz.
+
+    Returns:
+        Instantaneous frequency array in Hz (length = len(x) - 1).
+    """
+    analytic: NDArray[np.complexfloating] = sig.hilbert(x)  # type: ignore[assignment]
+    phase = np.unwrap(np.angle(analytic))
+    inst_freq = np.diff(phase) / (2.0 * np.pi) * fs
+    return inst_freq
+
+
+def envelope_spectrum(
+    x: NDArray[np.floating],
+    fs: float,
+    bandpass: tuple[float, float] | None = None,
+    filter_order: int = 5,
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+    """Compute the spectrum of the signal envelope.
+
+    Typical workflow for bearing / mechanical fault detection:
+      1. Optional bandpass to isolate a resonance band
+      2. Hilbert envelope
+      3. Remove DC of envelope
+      4. FFT of envelope → low‑frequency modulation spectrum
+
+    Args:
+        x: Input current signal.
+        fs: Sampling frequency in Hz.
+        bandpass: Optional (low, high) bandpass range in Hz before
+                  computing the envelope (e.g. to isolate a resonance).
+        filter_order: Butterworth filter order for bandpass.
+
+    Returns:
+        (frequencies, amplitudes) of the envelope spectrum.
+    """
+    y = x.copy()
+
+    # Optional bandpass
+    if bandpass is not None:
+        nyq = fs / 2.0
+        low, high = bandpass
+        if 0 < low < high < nyq:
+            sos = sig.butter(filter_order, [low / nyq, high / nyq], btype="bandpass", output="sos")
+            y = sig.sosfiltfilt(sos, y)
+
+    # Envelope
+    env = hilbert_envelope(y)
+
+    # Remove DC from envelope
+    env = env - np.mean(env)
+
+    # FFT of envelope
+    n = len(env)
+    freqs = np.fft.rfftfreq(n, d=1.0 / fs)
+    X = np.fft.rfft(env)
+    amps = (2.0 / n) * np.abs(X)
+    amps[0] /= 2.0
+
+    return freqs, amps