list_curated

Instructions

Implementation Reference

• src/au_weather_mcp/server.py:519-549 (handler)

  The MCP tool handler for list_curated. Decorated with @mcp.tool, it returns the sorted list of curated location IDs by delegating to curated_mod.list_ids().

  @mcp.tool
  def list_curated() -> list[str]:
      """List the 21 curated Australian location IDs supported by this MCP.
  
      The curated set covers all 8 state/territory capitals plus 13 major
      regional centres:
          - 8 capitals: sydney, melbourne, brisbane, perth, adelaide, hobart,
            darwin, canberra
          - 5 NSW regional: newcastle, wollongong (NSW capitals as above)
          - 5 QLD regional: gold_coast, sunshine_coast, cairns, townsville, mackay
          - 3 VIC regional: geelong, ballarat, bendigo
          - 1 TAS regional: launceston
          - 2 remote: alice_springs (NT), broome (WA)
  
      Example:
          ids = list_curated()
          # → ['adelaide', 'alice_springs', 'ballarat', 'bendigo', 'brisbane',
          #    'broome', 'cairns', 'canberra', 'darwin', 'geelong', 'gold_coast',
          #    'hobart', 'launceston', 'mackay', 'melbourne', 'newcastle',
          #    'perth', 'sunshine_coast', 'sydney', 'townsville', 'wollongong']
  
      When to use:
          - You want to know which locations have first-class support
          - You're building a UI that shows the supported set up front
          - You want to plan a multi-location dashboard call
  
      Returns:
          Sorted list of location IDs. Always 21 entries today; adding a
          location is a YAML edit, not a code change.
      """
      return curated_mod.list_ids()

• src/au_weather_mcp/curated.py:89-94 (helper)

  The list_ids() helper function that loads the curated registry (cached in _REGISTRY) and returns sorted keys. This is the actual data-loading logic behind list_curated.

  def list_ids() -> list[str]:
      """Return all curated location ids, sorted alphabetically."""
      global _REGISTRY
      if _REGISTRY is None:
          _REGISTRY = _load()
      return sorted(_REGISTRY.keys())

• src/au_weather_mcp/curated.py:36-36 (helper)

  Module-level _REGISTRY cache variable that stores the loaded CuratedLocation dict.

  _REGISTRY: dict[str, CuratedLocation] | None = None

• src/au_weather_mcp/curated.py:58-78 (helper)

  The _load() function that reads locations.yaml and parses it into the CuratedLocation dict. The YAML is the source of truth for the 21 curated locations.

  def _load() -> dict[str, CuratedLocation]:
      raw = yaml.safe_load(_yaml_path().read_text(encoding="utf-8"))
      locs = raw.get("locations") or {}
      out: dict[str, CuratedLocation] = {}
      for loc_id, fields in locs.items():
          if not _LOCATION_ID_PATTERN.match(loc_id):
              raise ValueError(
                  f"Location id {loc_id!r} must match {_LOCATION_ID_PATTERN.pattern}"
              )
          out[loc_id] = CuratedLocation(
              id=loc_id,
              name=str(fields["name"]),
              state=str(fields["state"]),
              description=fields.get("description"),
              latitude=float(fields["latitude"]),
              longitude=float(fields["longitude"]),
              timezone=str(fields["timezone"]),
              elevation_m=(float(fields["elevation_m"]) if "elevation_m" in fields else None),
              nearest_bom_station=fields.get("nearest_bom_station"),
          )
      return out

• src/au_weather_mcp/models.py:30-35 (schema)

  The LocationSummary model used for both search_locations and list_curated results (surface-level location info).

  class LocationSummary(BaseModel):
      """A curated AU location — surface for search_locations and list_curated."""
      id: str
      name: str
      state: str  # NSW, VIC, etc.
      description: str | None = None