KMB Bus MCP Server

Instructions

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()