KMB Bus MCP Server

Instructions

Args:
    stop_name: Full or partial name of the bus stop to search for

Implementation Reference

• kmb_mcp.py:281-309 (handler)

  The main handler function for the 'find_stop_by_name' tool. It uses the helper to find matching stops and formats the output as a readable string including IDs and locations.

  @mcp.tool()
  async def find_stop_by_name(stop_name: str) -> str:
      """Find bus stops matching a name or partial name.
      
      Args:
          stop_name: Full or partial name of the bus stop to search for
      """
      stops = await find_stops_by_name(stop_name)
      
      if not stops:
          return f"Could not find any stops matching '{stop_name}'"
      
      results = [f"Found {len(stops)} stops matching '{stop_name}':"]
      
      for i, stop in enumerate(stops, 1):
          stop_id = stop["stop"]
          name_en = stop["name_en"]
          name_tc = stop.get("name_tc", "")
          lat = stop.get("lat", 0)
          lng = stop.get("long", 0)
          
          if name_tc:
              results.append(f"{i}. {name_en} ({name_tc})")
          else:
              results.append(f"{i}. {name_en}")
          results.append(f"   ID: {stop_id}")
          results.append(f"   Location: {lat}, {lng}")
      
      return "\n".join(results)

• utils/handle.py:140-155 (helper)

  Core helper function that performs case-insensitive partial matching on English and Chinese stop names from the full stop list.

  async def find_stops_by_name(
      name: str,
      *,
      get_stop_list_func: Callable[[], Awaitable[List]],
  ) -> List:
      stops = await get_stop_list_func()
      matching_stops: List[Dict[str, Any]] = []
  
      for stop in stops:
          if (
              name.lower() in stop["name_en"].lower()
              or (stop.get("name_tc") and name.lower() in stop["name_tc"].lower())
          ):
              matching_stops.append(stop)
  
      return matching_stops

• kmb_mcp.py:281-281 (registration)

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

  @mcp.tool()

• kmb_mcp.py:122-128 (helper)

  Thin wrapper in kmb_mcp.py that delegates to the utils helper, maintaining compatibility for tests.

  async def find_stops_by_name(name: str) -> List:
      """Delegate to shared implementation; keep signature for tests."""
      return await handle_utils.find_stops_by_name(
          name,
          get_stop_list_func=get_stop_list,
      )