Update phonopy/mcp_output/mcp_plugin/mcp_service.py

phonopy/mcp_output/mcp_plugin/mcp_service.py

@@ -1,131 +1,1153 @@
+import os
+import sys
+from typing import List, Optional
+
+# Add the local source directory to sys.path
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+if source_path not in sys.path:
+    sys.path.insert(0, source_path)
+
 from fastmcp import FastMCP
+import numpy as np
+from phonopy.api_phonopy import Phonopy
+from phonopy.structure.atoms import PhonopyAtoms
 
 # Create the FastMCP service application
 mcp = FastMCP("phonopy_service")
 
-@mcp.tool(name="calculate_phonon_band_structure", description="Calculate phonon band structure using Phonopy")
-def calculate_phonon_band_structure(cell: dict, supercell_matrix: list, band_paths: list) -> dict:
+
+# ============================================================================
+# Utility functions
+# ============================================================================
+
+def _create_phonopy_from_structure(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    primitive_matrix: Optional[str] = None
+) -> Phonopy:
+    """Helper to create Phonopy instance from structure data."""
+    cell = PhonopyAtoms(
+        cell=np.array(lattice),
+        scaled_positions=np.array(positions),
+        numbers=np.array(numbers)
+    )
+    sc_matrix = supercell_matrix if supercell_matrix else [[2, 0, 0], [0, 2, 0], [0, 0, 2]]
+    p_matrix = primitive_matrix if primitive_matrix else "auto"
+    return Phonopy(cell, supercell_matrix=sc_matrix, primitive_matrix=p_matrix)
+
+
+# ============================================================================
+# Core Displacement and Force Constants Tools
+# ============================================================================
+
+@mcp.tool(name="generate_displacements", description="Generate atomic displacements for phonon calculations with customizable parameters.")
+def generate_displacements(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    distance: float = 0.01,
+    is_plusminus: str = "auto",
+    is_diagonal: bool = True
+) -> dict:
     """
-    Calculate the phonon band structure using Phonopy.
+    Generate atomic displacements for phonon calculations.
 
     Parameters:
-    - cell: A dictionary representing the unit cell.
-    - supercell_matrix: A list defining the supercell matrix.
-    - band_paths: A list of paths in reciprocal space for band structure calculation.
+    - lattice: 3x3 lattice vectors in Angstrom.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - supercell_matrix: Supercell transformation matrix (default 2x2x2).
+    - distance: Displacement distance in Angstrom (default 0.01).
+    - is_plusminus: 'auto', 'True', or 'False' for displacement directions.
+    - is_diagonal: Whether to use diagonal displacements.
 
     Returns:
-    - dict: Phonon band structure data.
+    - dict: Displacement dataset information.
     """
     try:
-        from phonopy import Phonopy
-        from phonopy.structure.atoms import PhonopyAtoms
-        
-        unitcell = PhonopyAtoms(**cell)
-        phonon = Phonopy(unitcell, supercell_matrix)
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.generate_displacements(
+            distance=distance,
+            is_plusminus=is_plusminus,
+            is_diagonal=is_diagonal
+        )
+        dataset = phonon.dataset
+        result = {
+            "num_displacements": len(dataset.get("first_atoms", [])) if "first_atoms" in dataset else len(dataset.get("displacements", [])),
+            "supercell_atoms": len(phonon.supercell),
+            "primitive_atoms": len(phonon.primitive)
+        }
+        if "first_atoms" in dataset:
+            result["displacements"] = [
+                {"atom_index": d["number"], "displacement": d["displacement"].tolist()}
+                for d in dataset["first_atoms"]
+            ]
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="calculate_force_constants", description="Calculate force constants from displacement-force datasets.")
+def calculate_force_constants(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    displacements: List[dict],
+    forces: List[List[List[float]]],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    fc_calculator: Optional[str] = None
+) -> dict:
+    """
+    Calculate force constants from displacement-force datasets.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - displacements: List of displacement data.
+    - forces: Forces on atoms for each displacement.
+    - supercell_matrix: Supercell transformation matrix.
+    - fc_calculator: External calculator ('symfc', 'alm', or None for traditional).
+
+    Returns:
+    - dict: Force constants calculation status and shape.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
         phonon.generate_displacements()
-        phonon.set_band_structure(band_paths)
-        band_structure = phonon.get_band_structure()
-        
+        phonon.forces = np.array(forces)
+        phonon.produce_force_constants(fc_calculator=fc_calculator)
+        fc = phonon.force_constants
         return {
             "success": True,
-            "band_structure": band_structure
+            "result": {
+                "force_constants_shape": list(fc.shape),
+                "message": "Force constants calculated successfully"
+            }
         }
     except Exception as e:
         return {"success": False, "error": str(e)}
 
-@mcp.tool(name="compute_thermal_properties", description="Compute thermal properties using Phonopy")
-def compute_thermal_properties(cell: dict, supercell_matrix: list, temperature_range: list) -> dict:
+
+@mcp.tool(name="symmetrize_force_constants", description="Symmetrize force constants by translational and permutation symmetry.")
+def symmetrize_force_constants(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    level: int = 1
+) -> dict:
     """
-    Compute thermal properties using Phonopy.
+    Symmetrize force constants.
 
     Parameters:
-    - cell: A dictionary representing the unit cell.
-    - supercell_matrix: A list defining the supercell matrix.
-    - temperature_range: A list of temperatures for thermal property calculation.
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - supercell_matrix: Supercell transformation matrix.
+    - level: Number of symmetrization iterations.
 
     Returns:
-    - dict: Thermal properties data.
+    - dict: Symmetrized force constants shape.
     """
     try:
-        from phonopy import Phonopy
-        from phonopy.structure.atoms import PhonopyAtoms
-        
-        unitcell = PhonopyAtoms(**cell)
-        phonon = Phonopy(unitcell, supercell_matrix)
-        phonon.generate_displacements()
-        phonon.set_thermal_properties(temperature_range)
-        thermal_properties = phonon.get_thermal_properties()
-        
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.symmetrize_force_constants(level=level)
         return {
             "success": True,
-            "thermal_properties": thermal_properties
+            "result": {
+                "message": "Force constants symmetrized successfully",
+                "shape": list(phonon.force_constants.shape)
+            }
         }
     except Exception as e:
         return {"success": False, "error": str(e)}
 
-@mcp.tool(name="generate_force_constants", description="Generate force constants using Phonopy")
-def generate_force_constants(cell: dict, supercell_matrix: list, force_sets: list) -> dict:
+
+# ============================================================================
+# Phonon Frequency Calculation Tools
+# ============================================================================
+
+@mcp.tool(name="get_frequencies", description="Calculate phonon frequencies at a given q-point.")
+def get_frequencies(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_point: List[float],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
     """
-    Generate force constants using Phonopy.
+    Calculate phonon frequencies at a given q-point.
 
     Parameters:
-    - cell: A dictionary representing the unit cell.
-    - supercell_matrix: A list defining the supercell matrix.
-    - force_sets: A list of force sets for the calculation.
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_point: Q-point in reduced coordinates [qx, qy, qz].
+    - supercell_matrix: Supercell transformation matrix.
 
     Returns:
-    - dict: Force constants data.
+    - dict: Phonon frequencies at the q-point.
     """
     try:
-        from phonopy import Phonopy
-        from phonopy.structure.atoms import PhonopyAtoms
-        
-        unitcell = PhonopyAtoms(**cell)
-        phonon = Phonopy(unitcell, supercell_matrix)
-        phonon.set_displacement_dataset(force_sets)
-        phonon.produce_force_constants()
-        force_constants = phonon.get_force_constants()
-        
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        frequencies = phonon.get_frequencies(q_point)
         return {
             "success": True,
-            "force_constants": force_constants
+            "result": {
+                "q_point": q_point,
+                "frequencies_THz": frequencies.tolist(),
+                "num_bands": len(frequencies)
+            }
         }
     except Exception as e:
         return {"success": False, "error": str(e)}
 
-@mcp.tool(name="plot_phonon_dos", description="Plot phonon density of states using Phonopy")
-def plot_phonon_dos(cell: dict, supercell_matrix: list, mesh: list) -> dict:
+
+@mcp.tool(name="get_frequencies_with_eigenvectors", description="Calculate phonon frequencies and eigenvectors at a q-point.")
+def get_frequencies_with_eigenvectors(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_point: List[float],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
     """
-    Plot phonon density of states using Phonopy.
+    Calculate phonon frequencies and eigenvectors at a q-point.
 
     Parameters:
-    - cell: A dictionary representing the unit cell.
-    - supercell_matrix: A list defining the supercell matrix.
-    - mesh: A list defining the mesh for DOS calculation.
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_point: Q-point in reduced coordinates.
+    - supercell_matrix: Supercell transformation matrix.
 
     Returns:
-    - dict: Phonon DOS plot data.
+    - dict: Frequencies and eigenvector information.
     """
     try:
-        from phonopy import Phonopy
-        from phonopy.structure.atoms import PhonopyAtoms
-        
-        unitcell = PhonopyAtoms(**cell)
-        phonon = Phonopy(unitcell, supercell_matrix)
-        phonon.set_mesh(mesh)
-        phonon.set_total_DOS()
-        dos = phonon.get_total_DOS()
-        
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        frequencies, eigenvectors = phonon.get_frequencies_with_eigenvectors(q_point)
+        return {
+            "success": True,
+            "result": {
+                "q_point": q_point,
+                "frequencies_THz": frequencies.tolist(),
+                "eigenvectors_shape": list(eigenvectors.shape),
+                "num_bands": len(frequencies)
+            }
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="get_dynamical_matrix_at_q", description="Calculate dynamical matrix at a given q-point.")
+def get_dynamical_matrix_at_q(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_point: List[float],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
+    """
+    Calculate dynamical matrix at a given q-point.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_point: Q-point in reduced coordinates.
+    - supercell_matrix: Supercell transformation matrix.
+
+    Returns:
+    - dict: Dynamical matrix shape and properties.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        dm = phonon.get_dynamical_matrix_at_q(q_point)
+        return {
+            "success": True,
+            "result": {
+                "q_point": q_point,
+                "dynamical_matrix_shape": list(dm.shape),
+                "is_hermitian": np.allclose(dm, dm.conj().T)
+            }
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Band Structure Tools
+# ============================================================================
+
+@mcp.tool(name="run_band_structure", description="Run phonon band structure calculation along specified paths.")
+def run_band_structure(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    paths: List[List[List[float]]],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    with_eigenvectors: bool = False,
+    with_group_velocities: bool = False,
+    labels: Optional[List[str]] = None
+) -> dict:
+    """
+    Run phonon band structure calculation.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - paths: List of q-point paths, each path is a list of q-points.
+    - supercell_matrix: Supercell transformation matrix.
+    - with_eigenvectors: Calculate eigenvectors.
+    - with_group_velocities: Calculate group velocities.
+    - labels: Labels for special points.
+
+    Returns:
+    - dict: Band structure calculation results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_band_structure(
+            paths,
+            with_eigenvectors=with_eigenvectors,
+            with_group_velocities=with_group_velocities,
+            labels=labels
+        )
+        bs_dict = phonon.get_band_structure_dict()
+        result = {
+            "num_paths": len(bs_dict["qpoints"]),
+            "frequencies_ranges": [
+                {"min": float(np.min(f)), "max": float(np.max(f))}
+                for f in bs_dict["frequencies"]
+            ],
+            "has_eigenvectors": bs_dict["eigenvectors"] is not None,
+            "has_group_velocities": bs_dict["group_velocities"] is not None
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="auto_band_structure", description="Automatically calculate band structure using standard high-symmetry paths.")
+def auto_band_structure(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    npoints: int = 101
+) -> dict:
+    """
+    Automatically calculate band structure using seekpath.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - supercell_matrix: Supercell transformation matrix.
+    - npoints: Number of points per path segment.
+
+    Returns:
+    - dict: Auto band structure results with high-symmetry path labels.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.auto_band_structure(npoints=npoints)
+        bs_dict = phonon.get_band_structure_dict()
+        result = {
+            "num_paths": len(bs_dict["qpoints"]),
+            "total_qpoints": sum(len(q) for q in bs_dict["qpoints"]),
+            "frequency_range": {
+                "min_THz": float(min(np.min(f) for f in bs_dict["frequencies"])),
+                "max_THz": float(max(np.max(f) for f in bs_dict["frequencies"]))
+            }
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Mesh Sampling Tools
+# ============================================================================
+
+@mcp.tool(name="run_mesh", description="Run phonon calculation on a mesh grid in reciprocal space.")
+def run_mesh(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    shift: Optional[List[float]] = None,
+    is_mesh_symmetry: bool = True,
+    with_eigenvectors: bool = False,
+    with_group_velocities: bool = False,
+    is_gamma_center: bool = False
+) -> dict:
+    """
+    Run mesh sampling phonon calculation.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers [n1, n2, n3].
+    - supercell_matrix: Supercell transformation matrix.
+    - shift: Mesh shift.
+    - is_mesh_symmetry: Use symmetry to reduce mesh points.
+    - with_eigenvectors: Store eigenvectors.
+    - with_group_velocities: Calculate group velocities.
+    - is_gamma_center: Use gamma-centered mesh.
+
+    Returns:
+    - dict: Mesh sampling results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(
+            mesh=mesh,
+            shift=shift,
+            is_mesh_symmetry=is_mesh_symmetry,
+            with_eigenvectors=with_eigenvectors,
+            with_group_velocities=with_group_velocities,
+            is_gamma_center=is_gamma_center
+        )
+        mesh_dict = phonon.get_mesh_dict()
+        result = {
+            "mesh": mesh,
+            "num_irreducible_qpoints": len(mesh_dict["qpoints"]),
+            "total_mesh_points": int(np.prod(mesh)),
+            "frequency_range": {
+                "min_THz": float(np.min(mesh_dict["frequencies"])),
+                "max_THz": float(np.max(mesh_dict["frequencies"]))
+            },
+            "has_eigenvectors": mesh_dict["eigenvectors"] is not None,
+            "has_group_velocities": mesh_dict["group_velocities"] is not None
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# DOS (Density of States) Tools
+# ============================================================================
+
+@mcp.tool(name="run_total_dos", description="Calculate total phonon density of states.")
+def run_total_dos(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    sigma: Optional[float] = None,
+    freq_min: Optional[float] = None,
+    freq_max: Optional[float] = None,
+    freq_pitch: Optional[float] = None,
+    use_tetrahedron_method: bool = True
+) -> dict:
+    """
+    Calculate total phonon density of states.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers for sampling.
+    - supercell_matrix: Supercell transformation matrix.
+    - sigma: Smearing width (None for tetrahedron method).
+    - freq_min/freq_max/freq_pitch: Frequency range and step.
+    - use_tetrahedron_method: Use tetrahedron method.
+
+    Returns:
+    - dict: DOS results with frequency points and DOS values.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh)
+        phonon.run_total_dos(
+            sigma=sigma,
+            freq_min=freq_min,
+            freq_max=freq_max,
+            freq_pitch=freq_pitch,
+            use_tetrahedron_method=use_tetrahedron_method
+        )
+        dos_dict = phonon.get_total_dos_dict()
+        result = {
+            "frequency_range_THz": {
+                "min": float(dos_dict["frequency_points"][0]),
+                "max": float(dos_dict["frequency_points"][-1])
+            },
+            "num_frequency_points": len(dos_dict["frequency_points"]),
+            "dos_max": float(np.max(dos_dict["total_dos"])),
+            "integrated_dos": float(np.trapezoid(dos_dict["total_dos"], dos_dict["frequency_points"]))
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="run_projected_dos", description="Calculate projected phonon density of states.")
+def run_projected_dos(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    sigma: Optional[float] = None,
+    use_tetrahedron_method: bool = True,
+    xyz_projection: bool = False
+) -> dict:
+    """
+    Calculate projected phonon density of states (PDOS).
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - sigma: Smearing width.
+    - use_tetrahedron_method: Use tetrahedron method.
+    - xyz_projection: Project along Cartesian directions.
+
+    Returns:
+    - dict: PDOS results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh, is_mesh_symmetry=False, with_eigenvectors=True)
+        phonon.run_projected_dos(
+            sigma=sigma,
+            use_tetrahedron_method=use_tetrahedron_method,
+            xyz_projection=xyz_projection
+        )
+        pdos_dict = phonon.get_projected_dos_dict()
+        result = {
+            "num_projections": len(pdos_dict["projected_dos"]),
+            "num_frequency_points": len(pdos_dict["frequency_points"]),
+            "frequency_range_THz": {
+                "min": float(pdos_dict["frequency_points"][0]),
+                "max": float(pdos_dict["frequency_points"][-1])
+            }
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="get_debye_frequency", description="Calculate Debye frequency from total DOS.")
+def get_debye_frequency(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    freq_max_fit: Optional[float] = None
+) -> dict:
+    """
+    Calculate Debye frequency from total DOS.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - freq_max_fit: Maximum frequency for fitting.
+
+    Returns:
+    - dict: Debye frequency in THz.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh)
+        phonon.run_total_dos()
+        phonon.set_Debye_frequency(freq_max_fit=freq_max_fit)
+        debye_freq = phonon.get_Debye_frequency()
         return {
             "success": True,
-            "dos": dos
+            "result": {
+                "debye_frequency_THz": float(debye_freq) if debye_freq else None
+            }
         }
     except Exception as e:
         return {"success": False, "error": str(e)}
 
+
+# ============================================================================
+# Thermal Properties Tools
+# ============================================================================
+
+@mcp.tool(name="run_thermal_properties", description="Calculate thermal properties at constant volume.")
+def run_thermal_properties(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    t_min: float = 0,
+    t_max: float = 1000,
+    t_step: float = 10,
+    cutoff_frequency: Optional[float] = None,
+    classical: bool = False
+) -> dict:
+    """
+    Calculate thermal properties (free energy, entropy, heat capacity).
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - t_min/t_max/t_step: Temperature range and step (K).
+    - cutoff_frequency: Cutoff for imaginary frequencies.
+    - classical: Use classical statistics.
+
+    Returns:
+    - dict: Thermal properties at temperature points.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh)
+        phonon.run_thermal_properties(
+            t_min=t_min,
+            t_max=t_max,
+            t_step=t_step,
+            cutoff_frequency=cutoff_frequency,
+            classical=classical
+        )
+        tp_dict = phonon.get_thermal_properties_dict()
+        result = {
+            "temperature_range_K": {"min": t_min, "max": t_max, "step": t_step},
+            "num_temperature_points": len(tp_dict["temperatures"]),
+            "free_energy_range_kJ_mol": {
+                "min": float(np.min(tp_dict["free_energy"])),
+                "max": float(np.max(tp_dict["free_energy"]))
+            },
+            "entropy_range_J_K_mol": {
+                "min": float(np.min(tp_dict["entropy"])),
+                "max": float(np.max(tp_dict["entropy"]))
+            },
+            "heat_capacity_range_J_K_mol": {
+                "min": float(np.min(tp_dict["heat_capacity"])),
+                "max": float(np.max(tp_dict["heat_capacity"]))
+            },
+            "sample_values_at_300K": None
+        }
+        # Find values at 300K if available
+        temps = tp_dict["temperatures"]
+        idx_300 = np.argmin(np.abs(temps - 300))
+        if abs(temps[idx_300] - 300) < t_step:
+            result["sample_values_at_300K"] = {
+                "temperature_K": float(temps[idx_300]),
+                "free_energy_kJ_mol": float(tp_dict["free_energy"][idx_300]),
+                "entropy_J_K_mol": float(tp_dict["entropy"][idx_300]),
+                "heat_capacity_J_K_mol": float(tp_dict["heat_capacity"][idx_300])
+            }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="run_thermal_displacements", description="Calculate thermal displacements of atoms.")
+def run_thermal_displacements(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    t_min: float = 0,
+    t_max: float = 1000,
+    t_step: float = 10,
+    direction: Optional[List[float]] = None
+) -> dict:
+    """
+    Calculate thermal displacements of atoms.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - t_min/t_max/t_step: Temperature range and step.
+    - direction: Projection direction in reduced coordinates.
+
+    Returns:
+    - dict: Thermal displacement results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh, is_mesh_symmetry=False, with_eigenvectors=True)
+        phonon.run_thermal_displacements(
+            t_min=t_min,
+            t_max=t_max,
+            t_step=t_step,
+            direction=direction
+        )
+        td_dict = phonon.get_thermal_displacements_dict()
+        result = {
+            "num_atoms": len(td_dict["thermal_displacements"][0]) if len(td_dict["thermal_displacements"]) > 0 else 0,
+            "num_temperature_points": len(td_dict["temperatures"]),
+            "temperature_range_K": {"min": t_min, "max": t_max}
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="run_thermal_displacement_matrices", description="Calculate thermal displacement matrices (U tensors).")
+def run_thermal_displacement_matrices(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    t_min: float = 0,
+    t_max: float = 1000,
+    t_step: float = 10
+) -> dict:
+    """
+    Calculate thermal displacement matrices for CIF output.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - t_min/t_max/t_step: Temperature range and step.
+
+    Returns:
+    - dict: Thermal displacement matrix results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh, is_mesh_symmetry=False, with_eigenvectors=True)
+        phonon.run_thermal_displacement_matrices(t_min=t_min, t_max=t_max, t_step=t_step)
+        tdm_dict = phonon.get_thermal_displacement_matrices_dict()
+        result = {
+            "num_temperature_points": len(tdm_dict["temperatures"]),
+            "matrix_shape": list(tdm_dict["thermal_displacement_matrices"][0].shape) if len(tdm_dict["thermal_displacement_matrices"]) > 0 else [],
+            "has_cif_format": tdm_dict["thermal_displacement_matrices_cif"] is not None
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Q-points Calculation Tools
+# ============================================================================
+
+@mcp.tool(name="run_qpoints", description="Calculate phonon properties at specific q-points.")
+def run_qpoints(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_points: List[List[float]],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    with_eigenvectors: bool = False,
+    with_group_velocities: bool = False,
+    with_dynamical_matrices: bool = False
+) -> dict:
+    """
+    Calculate phonon properties at specified q-points.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_points: List of q-points in reduced coordinates.
+    - supercell_matrix: Supercell transformation matrix.
+    - with_eigenvectors: Store eigenvectors.
+    - with_group_velocities: Calculate group velocities.
+    - with_dynamical_matrices: Store dynamical matrices.
+
+    Returns:
+    - dict: Phonon properties at q-points.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_qpoints(
+            q_points,
+            with_eigenvectors=with_eigenvectors,
+            with_group_velocities=with_group_velocities,
+            with_dynamical_matrices=with_dynamical_matrices
+        )
+        qp_dict = phonon.get_qpoints_dict()
+        result = {
+            "num_qpoints": len(q_points),
+            "frequencies_shape": list(qp_dict["frequencies"].shape),
+            "has_eigenvectors": qp_dict["eigenvectors"] is not None,
+            "has_group_velocities": qp_dict["group_velocities"] is not None,
+            "has_dynamical_matrices": qp_dict["dynamical_matrices"] is not None,
+            "frequency_summary": [
+                {"q_point": q_points[i], "frequencies_THz": qp_dict["frequencies"][i].tolist()}
+                for i in range(min(3, len(q_points)))
+            ]
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="get_group_velocity_at_q", description="Calculate phonon group velocity at a q-point.")
+def get_group_velocity_at_q(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_point: List[float],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
+    """
+    Calculate phonon group velocity at a q-point.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_point: Q-point in reduced coordinates.
+    - supercell_matrix: Supercell transformation matrix.
+
+    Returns:
+    - dict: Group velocities for all bands at the q-point.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        gv = phonon.get_group_velocity_at_q(q_point)
+        result = {
+            "q_point": q_point,
+            "group_velocities": gv.tolist(),
+            "num_bands": len(gv),
+            "velocity_magnitudes": np.linalg.norm(gv, axis=1).tolist()
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Modulation and Animation Tools
+# ============================================================================
+
+@mcp.tool(name="run_modulations", description="Generate atomic modulations for phonon modes.")
+def run_modulations(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    dimension: List[int],
+    phonon_modes: List[dict],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
+    """
+    Generate atomic modulations for specified phonon modes.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - dimension: Supercell dimension [n1, n2, n3].
+    - phonon_modes: List of mode specifications. Each has:
+        - q_point: [qx, qy, qz]
+        - band_index: Integer band index (0-based)
+        - amplitude: Float amplitude
+        - phase: Float phase factor
+    - supercell_matrix: Supercell transformation matrix.
+
+    Returns:
+    - dict: Modulation results.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        modes = [
+            [m["q_point"], m["band_index"], m["amplitude"], m.get("phase", 0)]
+            for m in phonon_modes
+        ]
+        phonon.run_modulations(dimension, modes)
+        modulated_cells = phonon.get_modulated_supercells()
+        result = {
+            "num_modulated_cells": len(modulated_cells),
+            "supercell_dimension": dimension,
+            "atoms_per_cell": len(modulated_cells[0]) if modulated_cells else 0
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Irreducible Representations Tools
+# ============================================================================
+
+@mcp.tool(name="set_irreps", description="Calculate irreducible representations at a q-point.")
+def set_irreps(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    q_point: List[float],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    is_little_cogroup: bool = False
+) -> dict:
+    """
+    Calculate irreducible representations of phonon modes.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - q_point: Q-point in reduced coordinates.
+    - supercell_matrix: Supercell transformation matrix.
+    - is_little_cogroup: Use little co-group.
+
+    Returns:
+    - dict: Irreducible representation information.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.set_irreps(q_point, is_little_cogroup=is_little_cogroup)
+        result = {
+            "q_point": q_point,
+            "irreps_calculated": True,
+            "is_little_cogroup": is_little_cogroup
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Moment Calculation Tools
+# ============================================================================
+
+@mcp.tool(name="run_moment", description="Calculate phonon frequency moment.")
+def run_moment(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    force_constants: List[List[List[List[float]]]],
+    mesh: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None,
+    order: int = 1,
+    freq_min: Optional[float] = None,
+    freq_max: Optional[float] = None
+) -> dict:
+    """
+    Calculate phonon frequency moment.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - force_constants: Force constants array.
+    - mesh: Mesh grid numbers.
+    - supercell_matrix: Supercell transformation matrix.
+    - order: Moment order (1, 2, etc.).
+    - freq_min/freq_max: Frequency range.
+
+    Returns:
+    - dict: Moment calculation result.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        phonon.force_constants = np.array(force_constants)
+        phonon.run_mesh(mesh=mesh)
+        phonon.run_moment(order=order, freq_min=freq_min, freq_max=freq_max)
+        moment = phonon.get_moment()
+        result = {
+            "order": order,
+            "moment": float(moment) if isinstance(moment, (int, float, np.floating)) else moment.tolist() if moment is not None else None
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# ============================================================================
+# Structure Information Tools
+# ============================================================================
+
+@mcp.tool(name="get_structure_info", description="Get structure information from phonopy setup.")
+def get_structure_info(
+    lattice: List[List[float]],
+    positions: List[List[float]],
+    numbers: List[int],
+    supercell_matrix: Optional[List[List[int]]] = None
+) -> dict:
+    """
+    Get structure information including symmetry.
+
+    Parameters:
+    - lattice: 3x3 lattice vectors.
+    - positions: Fractional atomic positions.
+    - numbers: Atomic numbers.
+    - supercell_matrix: Supercell transformation matrix.
+
+    Returns:
+    - dict: Structure and symmetry information.
+    """
+    try:
+        phonon = _create_phonopy_from_structure(lattice, positions, numbers, supercell_matrix)
+        unitcell = phonon.unitcell
+        supercell = phonon.supercell
+        primitive = phonon.primitive
+        symmetry = phonon.symmetry
+        result = {
+            "unitcell": {
+                "num_atoms": len(unitcell),
+                "lattice_parameters": {
+                    "a": float(np.linalg.norm(unitcell.cell[0])),
+                    "b": float(np.linalg.norm(unitcell.cell[1])),
+                    "c": float(np.linalg.norm(unitcell.cell[2]))
+                },
+                "volume_angstrom3": float(np.linalg.det(unitcell.cell))
+            },
+            "supercell": {
+                "num_atoms": len(supercell),
+                "volume_angstrom3": float(np.linalg.det(supercell.cell))
+            },
+            "primitive": {
+                "num_atoms": len(primitive),
+                "volume_angstrom3": float(np.linalg.det(primitive.cell))
+            },
+            "symmetry": {
+                "num_operations": len(symmetry.symmetry_operations["rotations"]),
+                "international_symbol": symmetry.international_symbol if hasattr(symmetry, 'international_symbol') else None
+            }
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="get_unit_conversion_factor", description="Get phonopy unit conversion factor.")
+def get_unit_conversion_factor(calculator: Optional[str] = None) -> dict:
+    """
+    Get phonopy unit conversion factor.
+
+    Parameters:
+    - calculator: Calculator name ('vasp', 'qe', etc.) or None for default.
+
+    Returns:
+    - dict: Unit conversion factor information.
+    """
+    try:
+        from phonopy.interface.calculator import get_calculator_physical_units
+        from phonopy.physical_units import get_physical_units
+        
+        if calculator:
+            units = get_calculator_physical_units(interface_mode=calculator)
+            factor = units.get("factor", None)
+        else:
+            factor = get_physical_units().DefaultToTHz
+        
+        result = {
+            "calculator": calculator if calculator else "default",
+            "factor_to_THz": float(factor) if factor else None,
+            "description": "Converts sqrt(eV/Angstrom^2/AMU) to THz"
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@mcp.tool(name="get_phonopy_info", description="Get phonopy version and capability information.")
+def get_phonopy_info() -> dict:
+    """
+    Get phonopy version and available features.
+
+    Returns:
+    - dict: Version and capability information.
+    """
+    try:
+        from phonopy.version import __version__
+        
+        result = {
+            "version": __version__,
+            "capabilities": [
+                "Phonon band structure calculation",
+                "Density of states (total and projected)",
+                "Thermal properties (free energy, entropy, heat capacity)",
+                "Thermal displacements",
+                "Group velocity calculation",
+                "Irreducible representations",
+                "Modulation and animation",
+                "Force constants symmetrization",
+                "Mesh sampling",
+                "Q-point calculations"
+            ],
+            "supported_calculators": [
+                "vasp", "qe", "abinit", "siesta", "elk", "wien2k",
+                "crystal", "turbomole", "cp2k", "dftbp", "lammps"
+            ],
+            "fc_calculators": ["traditional", "symfc", "alm"]
+        }
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
 def create_app() -> FastMCP:
     """
-    Create and return the FastMCP application instance.
+    Creates and returns the FastMCP application instance.
 
     Returns:
     - FastMCP: The FastMCP application instance.