compare_materials

Instructions

Compare properties of multiple materials side by side.

Args:
    material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])

Returns:
    JSON table comparing key properties across materials

Implementation Reference

• src/mcp_materials/server.py:210-262 (handler)

  The core handler function for the 'compare_materials' tool. It fetches material summaries from Materials Project API using MPRester, compares key properties like formula, band gap, stability, etc., and returns a JSON-formatted comparison table. Includes error handling for invalid IDs and API issues.

  @mcp.tool()
  def compare_materials(
      material_ids: list[str],
  ) -> str:
      """
      Compare properties of multiple materials side by side.
  
      Args:
          material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])
  
      Returns:
          JSON table comparing key properties across materials
      """
      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
  
          comparison = []
  
          with MPRester(key_or_error) as mpr:
              for mid in material_ids:
                  try:
                      doc = mpr.materials.summary.get_data_by_id(mid)
                      crystal_system = None
                      if doc.symmetry and doc.symmetry.crystal_system:
                          crystal_system = str(doc.symmetry.crystal_system.value) if hasattr(doc.symmetry.crystal_system, 'value') else str(doc.symmetry.crystal_system)
                      comparison.append({
                          "material_id": str(doc.material_id),
                          "formula": doc.formula_pretty,
                          "band_gap_eV": doc.band_gap,
                          "formation_energy_eV": doc.formation_energy_per_atom,
                          "energy_above_hull_eV": doc.energy_above_hull,
                          "density_g_cm3": doc.density,
                          "is_stable": doc.is_stable,
                          "is_metal": doc.is_metal,
                          "crystal_system": crystal_system,
                      })
                  except Exception as e:
                      comparison.append({
                          "material_id": mid,
                          "error": str(e),
                      })
  
          return json.dumps({
              "count": len(comparison),
              "comparison": comparison,
          }, indent=2)
  
      except Exception as e:
          return json.dumps({"error": str(e)})

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

  The @mcp.tool() decorator registers the compare_materials function as an MCP tool, automatically generating schema from type hints and docstring.

  @mcp.tool()

• src/mcp_materials/server.py:211-222 (schema)

  Input schema defined by type hint 'material_ids: list[str]' and comprehensive docstring describing parameters and return format (JSON comparison table).

  def compare_materials(
      material_ids: list[str],
  ) -> str:
      """
      Compare properties of multiple materials side by side.
  
      Args:
          material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])
  
      Returns:
          JSON table comparing key properties across materials
      """

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

  Shared helper function used by compare_materials (and other tools) to validate Materials Project API key presence before making API calls.

  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

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

  The main() function initializes and runs the FastMCP server instance (created at line 19), which scans and registers all @mcp.tool() decorated functions including compare_materials.

  def main():
      """Run the MCP server."""
      mcp.run()