get_similar_structures

Instructions

Find materials with similar crystal structures.

Args:
    material_id: Materials Project ID to find similar structures for
    max_results: Maximum number of similar structures (default: 5)

Returns:
    JSON with structurally similar materials

Implementation Reference

• src/mcp_materials/server.py:399-468 (handler)

  The primary handler function for the 'get_similar_structures' tool. Decorated with @mcp.tool() for automatic schema generation from type hints/docstring and registration with the MCP server. Retrieves the space group of the input material and searches for other materials with the same space group using the Materials Project API, excluding the reference material itself.

  @mcp.tool()
  def get_similar_structures(
      material_id: str,
      max_results: int = 5,
  ) -> str:
      """
      Find materials with similar crystal structures.
  
      Args:
          material_id: Materials Project ID to find similar structures for
          max_results: Maximum number of similar structures (default: 5)
  
      Returns:
          JSON with structurally similar 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
  
          with MPRester(key_or_error) as mpr:
              # Get the reference material
              ref_doc = mpr.materials.summary.get_data_by_id(material_id)
              space_group = ref_doc.symmetry.number if ref_doc.symmetry else None
  
              if not space_group:
                  return json.dumps({"error": "Could not determine space group for reference material"})
  
              # Search for materials with same space group
              docs = mpr.materials.summary.search(
                  spacegroup_number=space_group,
                  fields=[
                      "material_id",
                      "formula_pretty",
                      "symmetry",
                      "nsites",
                      "volume",
                  ],
                  num_chunks=1,
                  chunk_size=max_results + 1,  # +1 to exclude self
              )
  
              results = []
              for doc in docs:
                  if str(doc.material_id) == material_id:
                      continue
                  if len(results) >= max_results:
                      break
                  results.append({
                      "material_id": str(doc.material_id),
                      "formula": doc.formula_pretty,
                      "space_group": doc.symmetry.symbol if doc.symmetry else None,
                      "nsites": doc.nsites,
                      "volume_A3": doc.volume,
                  })
  
              return json.dumps({
                  "reference": {
                      "material_id": material_id,
                      "formula": ref_doc.formula_pretty,
                      "space_group": ref_doc.symmetry.symbol if ref_doc.symmetry else None,
                  },
                  "similar_structures": results,
              }, indent=2)
  
      except Exception as e:
          return json.dumps({"error": str(e)})

• src/mcp_materials/server.py:404-412 (schema)

  The docstring and function signature provide the input schema (material_id: str, max_results: int=5) and output description (JSON with reference and similar_structures list), used by FastMCP to generate JSON Schema for the tool.

  """
  Find materials with similar crystal structures.
  
  Args:
      material_id: Materials Project ID to find similar structures for
      max_results: Maximum number of similar structures (default: 5)
  
  Returns:
      JSON with structurally similar materials

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

  The @mcp.tool() decorator registers the function as an MCP tool, handling tool exposure to clients.

  @mcp.tool()

• src/mcp_materials/server.py:777-790 (helper)

  An MCP prompt template that recommends using the get_similar_structures tool as part of material analysis workflow.

  @mcp.prompt()
  def analyze_material(material_id: str) -> str:
      """Generate a prompt for comprehensive material analysis."""
      return f"""Analyze the material with ID {material_id} from the Materials Project database.
  
  Please:
  1. First, use the get_properties tool to retrieve all properties for {material_id}
  2. Summarize the key characteristics (composition, structure, stability)
  3. Discuss the electronic properties (band gap, metallic/insulating)
  4. Assess thermodynamic stability based on energy above hull
  5. Suggest potential applications based on the properties
  6. Recommend similar materials to compare using get_similar_structures
  
  Provide a comprehensive analysis suitable for a materials scientist."""