AEMET-MCP

Instructions

Implementation Reference

• src/aemet_mcp/server.py:279-307 (handler)

  The handler function for the 'solve_beach_code' MCP tool. It performs fuzzy matching on beach names, provinces, or municipalities using a preloaded JSON dataset and the normalize helper function.

  @mcp.tool()
  def solve_beach_code(nombre: str, tipo: Literal["playa", "provincia", "municipio"] = "playa"):
      """
      Search beaches by name, province, or municipality.
  
      Args:
          nombre: Search string (accent-insensitive)
          tipo: One of 'playa', 'provincia', or 'municipio'
      """
      entrada = normalize(nombre.strip())
      coincidencias = []
  
      for playa in CODIGOS_PLAYAS:
          if tipo == "playa":
              campo = normalize(playa.get("NOMBRE_PLAYA", ""))
          elif tipo == "provincia":
              campo = normalize(playa.get("NOMBRE_PROVINCIA", ""))
          elif tipo == "municipio":
              campo = normalize(playa.get("NOMBRE_MUNICIPIO", ""))
          else:
              return {"error": f"Invalid type '{tipo}'. Use 'playa', 'provincia' or 'municipio'."}
  
          if entrada in campo or difflib.SequenceMatcher(None, entrada, campo).ratio() > 0.75:
              coincidencias.append(playa)
  
      if not coincidencias:
          return {"error": f"No beaches found with {tipo} matching '{nombre}'."}
      return coincidencias

• src/aemet_mcp/server.py:25-29 (helper)

  Loads the static JSON data file containing beach codes, names, provinces, and municipalities used by the solve_beach_code tool.

  CODIGOS_PLAYAS = json.loads(
      files("aemet_mcp.res").
      joinpath("Beaches_code.json").
      read_text(encoding="utf-8")
  )

• src/aemet_mcp/server.py:78-80 (helper)

  Helper function to normalize text for accent-insensitive and case-insensitive matching, used in solve_beach_code.

  def normalize(text: str) -> str:
      return unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii").lower()

• src/aemet_mcp/server.py:279-279 (registration)

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

  @mcp.tool()

• src/aemet_mcp/server.py:280-287 (schema)

  Function signature with type hints and docstring defining the input schema for the tool.

  def solve_beach_code(nombre: str, tipo: Literal["playa", "provincia", "municipio"] = "playa"):
      """
      Search beaches by name, province, or municipality.
  
      Args:
          nombre: Search string (accent-insensitive)
          tipo: One of 'playa', 'provincia', or 'municipio'
      """