get_phase_diagram

Instructions

Get phase diagram data for a chemical system.

Args:
    elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)

Returns:
    JSON with phase diagram entries including stable phases, formation energies, and decomposition products

Implementation Reference

• src/mcp_materials/server.py:470-546 (handler)

  The main handler function for the 'get_phase_diagram' tool. It uses the Materials Project API to retrieve phase diagram data for a given list of elements, constructs a PhaseDiagram object, and returns JSON with stable and unstable phases including formation energies and decomposition information.

  @mcp.tool()
  def get_phase_diagram(
      elements: list[str],
  ) -> str:
      """
      Get phase diagram data for a chemical system.
  
      Args:
          elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)
  
      Returns:
          JSON with phase diagram entries including stable phases, formation energies, and decomposition products
      """
      has_key, key_or_error = check_api_key()
      if not has_key:
          return json.dumps({"error": key_or_error})
  
      try:
          from mp_api.client import MPRester
          from pymatgen.analysis.phase_diagram import PhaseDiagram
  
          with MPRester(key_or_error) as mpr:
              # Get all entries in the chemical system
              chemsys = "-".join(sorted(elements))
              entries = mpr.get_entries_in_chemsys(elements)
  
              if not entries:
                  return json.dumps({
                      "error": f"No entries found for chemical system: {chemsys}",
                      "chemical_system": chemsys,
                  })
  
              # Build phase diagram
              pd = PhaseDiagram(entries)
  
              # Get stable entries
              stable_entries = []
              for entry in pd.stable_entries:
                  stable_entries.append({
                      "material_id": str(entry.entry_id) if hasattr(entry, 'entry_id') else None,
                      "formula": entry.composition.reduced_formula,
                      "energy_per_atom_eV": entry.energy_per_atom,
                      "formation_energy_per_atom_eV": pd.get_form_energy_per_atom(entry),
                  })
  
              # Get unstable entries with decomposition info
              unstable_entries = []
              for entry in pd.unstable_entries:
                  decomp, e_above_hull = pd.get_decomp_and_e_above_hull(entry)
                  decomp_products = [p.composition.reduced_formula for p in decomp.keys()]
                  unstable_entries.append({
                      "material_id": str(entry.entry_id) if hasattr(entry, 'entry_id') else None,
                      "formula": entry.composition.reduced_formula,
                      "energy_above_hull_eV": e_above_hull,
                      "decomposes_to": decomp_products,
                  })
  
              return json.dumps({
                  "chemical_system": chemsys,
                  "num_elements": len(elements),
                  "total_entries": len(entries),
                  "stable_phases": {
                      "count": len(stable_entries),
                      "entries": stable_entries,
                  },
                  "unstable_phases": {
                      "count": len(unstable_entries),
                      "entries": unstable_entries[:20],  # Limit to first 20
                  },
              }, indent=2)
  
      except ImportError:
          return json.dumps({"error": "mp-api or pymatgen not installed"})
      except Exception as e:
          return json.dumps({"error": str(e)})

• src/mcp_materials/server.py:470-470 (registration)

  The @mcp.tool() decorator registers the get_phase_diagram function as an MCP tool.

  @mcp.tool()

• src/mcp_materials/server.py:471-482 (schema)

  Input schema defined by function signature (elements: list[str]) and comprehensive docstring describing parameters and return format.

  def get_phase_diagram(
      elements: list[str],
  ) -> str:
      """
      Get phase diagram data for a chemical system.
  
      Args:
          elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)
  
      Returns:
          JSON with phase diagram entries including stable phases, formation energies, and decomposition products
      """

• src/mcp_materials/server.py:30-36 (helper)

  Helper function check_api_key() used by get_phase_diagram to validate Materials Project API key presence.

  def check_api_key() -> tuple[bool, str]:
      """Check if API key is configured."""
      key = get_mp_api_key()
      if not key:
          return False, "MP_API_KEY environment variable not set. Get your key at https://materialsproject.org/api"
      return True, key