publicTransitRoutes

Instructions

Implementation Reference

• src/mcp_tmap/server.py:26-74 (handler)

  The main handler function for the 'publicTransitRoutes' tool. It defines the input schema via type hints and docstring, is registered via @mcp.tool() decorator, and delegates to TmapClient.getTransitRoutes for the API call.

  @mcp.tool()
  async def publicTransitRoutes(
    startLon: str,
    startLat: str,
    destLon: str,
    destLat: str,
    language: int = 0,
    searchTime: Optional[str] = None,
  ) -> Dict:
    """Retrieves public transportation routes from start to destination.
  
    Args:
      startLon (str): longitude of the starting point (WSG84).
      startLat (str): latitude of the starting point (WSG84).
      destLon (str): longitude of the destination (WSG84).
      destLat (str): latitude of the destination (WSG84).
      language (int): language of the route; 0 for Korean and 1 for English.
      searchTime (str, optional): Sets the time for the route to be searched.
        Used as information to indicate whether transportation is in operation.
        See [service] in the response for the operation status.
  
    Returns:
      route information
      - itineraries: route details
        - fare: total fare
        - totalTime: in seconds
        - transferCount:
        - totalWalkDistance: in meters
        - totalDistance: in meters
        - totalWalkTime: in seconds
        - legs: legs in the route
          - distance: in meters
          - sectionTime: in seconds
          - mode: transportation mode
          - route: transportation route
          - start: starting point of the leg
          - end: destination of the leg
    """
    assert (language == 0 or language == 1)
    try:
      return await tmap_client.getTransitRoutes(
        startLon, startLat,
        destLon, destLat,
        language,
        searchTime=searchTime,
      )
    except Exception as ex:
      return { "success": False, "error": str(ex) }

• src/mcp_tmap/tmap_client.py:21-45 (helper)

  Supporting utility in TmapClient class that makes the HTTP POST request to the SK Open API for public transit routes.

  async def getTransitRoutes(
    self,
    startLon: str,
    startLat: str,
    destLon: str,
    destLat: str,
    language: int,
    count: int = 10,
    searchTime: Optional[str] = None,
  ) -> Dict:
    path = f"{self.BASE_URL}/transit/routes"
    body = {
      "startX": startLon,
      "startY": startLat,
      "endX": destLon,
      "endY": destLat,
      "lang": language,
      "count": count,
      "format": "json",
    }
    if searchTime is not None:
      body["searchDttm"] = searchTime
  
    return (await self._post(path, body)).get("metaData", {}).get("plan", {})

• src/mcp_tmap/server.py:24-24 (registration)

  Creation of the FastMCP server instance where tools are registered via decorators.

  mcp = FastMCP("mcp_tmap", instructions=INSTRUCTIONS)

• src/mcp_tmap/server.py:10-22 (schema)

  MCP instructions string describing the tool's purpose, input/output structure, and usage notes.

  INSTRUCTIONS = """
  TMAP MCP provides tools for accessing the mobility platform provided by TMAP in South Korea.
  
  - publicTransitRoutes: Retrieves public transit routes between two places.
    The response contains [legs], which are legs of the retrieved route.
    Use [start.name] in each leg to return a chain of legs.
    The underlying API is often rate-limited, so you have to ask a user if they really want to proceed with this tool.
  - fullTextAddressGeocoding: Converts an address in full text into coordinates.
    The response contains a list of coordinates, which are ordered by the relevancy.
    If the entered address is not accurate, the response contains coordinates of a similar location.
    Use the first item in the response to return the coordinates.
    [newLat] is the latitude and [newLon] is the longitude.
  """.strip()