KMB Bus MCP Server

Instructions

Args:
    route: The bus route number (e.g., "1A", "6", "960")

Implementation Reference

• kmb_mcp.py:226-279 (handler)

  The main handler function for the 'get_route_stops_info' MCP tool. It orchestrates fetching route details, route stops, and individual stop details for all directions of the given route, then formats and returns a string list of stops.

  @mcp.tool()
  async def get_route_stops_info(route: str) -> str:
      """Get all stops along a specified bus route.
      
      Args:
          route: The bus route number (e.g., "1A", "6", "960")
      """
      # Get all directions for this route
      route_details = await get_route_details(route)
      
      if not route_details:
          return f"Could not find information for route {route}"
      
      results = []
      
      for direction_info in route_details:
          direction = direction_info["bound"]
          service_type = direction_info["service_type"]
          origin = direction_info.get("orig_en", "Unknown")
          destination = direction_info.get("dest_en", "Unknown")
          
          direction_text = "Inbound" if direction == "I" else "Outbound"
          results.append(f"Route {route} {direction_text} from {origin} to {destination}:")
          
          # Get stops for this direction
          stops_data = await get_route_stops(route, direction, service_type)
          
          if not stops_data:
              results.append("  No stop information available")
              continue
          
          # Sort stops by sequence
          stops_data.sort(key=lambda x: x.get("seq", 0))
          
          # Get full stop details for each stop
          stop_details = []
          for stop_data in stops_data:
              stop_id = stop_data["stop"]
              stop_info = await get_stop_details(stop_id)
              
              if "data" in stop_info:
                  stop_details.append({
                      "seq": stop_data.get("seq", 0),
                      "stop_id": stop_id,
                      "name": stop_info["data"].get("name_en", "Unknown"),
                      "lat": stop_info["data"].get("lat", 0),
                      "long": stop_info["data"].get("long", 0)
                  })
          
          # Add stop information to results
          for i, stop in enumerate(stop_details, 1):
              results.append(f"  {i}. {stop['name']} (ID: {stop['stop_id']})")
      
      return "\n\n".join(results)

• utils/handle.py:104-118 (helper)

  Core helper function that fetches the list of stops for a specific route, direction, and service type by calling the route-stop API endpoint.

  async def get_route_stops(
      route: str,
      direction: str,
      service_type: str,
      *,
      fetch_api_func: Callable[[str], Awaitable[Dict]],
      route_stop_url: str,
  ) -> List:
      direction_full = "inbound" if direction == "I" else "outbound"
      url = f"{route_stop_url}/{route}/{direction_full}/{service_type}"
      response = await fetch_api_func(url)
      if "data" in response:
          return response["data"]
      return []

• utils/handle.py:94-102 (helper)

  Helper function to retrieve detailed information for a specific stop ID by querying the stop API endpoint.

  async def get_stop_details(
      stop_id: str,
      *,
      fetch_api_func: Callable[[str], Awaitable[Dict]],
      stop_url: str,
  ) -> Dict:
      url = f"{stop_url}/{stop_id}"
      return await fetch_api_func(url)

• utils/handle.py:76-92 (helper)

  Helper function to get route details, including all directions if none specified, used to determine directions and service types for the route.

  async def get_route_details(
      route: str,
      direction: Optional[str],
      service_type: str,
      *,
      get_route_list_func: Callable[[], Awaitable[List]],
      fetch_api_func: Callable[[str], Awaitable[Dict]],
      route_url: str,
  ) -> Any:
      if direction is None:
          routes = await get_route_list_func()
          route_data = [r for r in routes if r["route"] == route]
          return route_data
  
      url = f"{route_url}/{route}/{direction}/{service_type}"
      return await fetch_api_func(url)

• kmb_mcp.py:226-226 (registration)

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

  @mcp.tool()