Polarsteps MCP Server

Instructions

Implementation Reference

• src/polarsteps_mcp/tools.py:85-92 (handler)

  Main handler function for the 'get_trip' tool. Validates input, fetches trip data using _get_trip utility, handles errors, and returns formatted TextContent response.

  def get_trip(
      polarsteps_client: PolarstepsClient, input: GetTripInput
  ) -> list[TextContent]:
      trip = _get_trip(polarsteps_client, input.trip_id)
      if trip.id == -1:
          return single_text_content(f"Could not find trip with ID: {input.trip_id}")
      return single_text_content(trip.to_detailed_summary(input.n_steps))

• src/polarsteps_mcp/tools.py:72-83 (schema)

  Pydantic input schema/model for the 'get_trip' tool, defining required trip_id and optional n_steps parameters with descriptions and validation.

  class GetTripInput(BaseModel):
      trip_id: int = Field(
          ...,
          description="The unique numerical identifier of a Polarsteps trip (typically 7+ digits)",
          ge=1_000_000,
      )
      n_steps: int = Field(
          5,
          ge=0,
          description="Maximum number of trip steps/locations to include in the response (each step contains photos and descriptions from specific locations).",
      )

• src/polarsteps_mcp/tools.py:217-221 (registration)

  PolarstepsTool.TRIP enum entry registering the 'get_trip' tool with its name, description, and input schema reference. Used by server.list_tools().

  TRIP = (
      "get_trip",
      "Get comprehensive details about a specific trip including summary, timeline, route information, individual steps/locations, weather data, and engagement metrics. Use after get_trip_log when you need detailed information about specific locations or comprehensive trip data.",
      GetTripInput,
  )

• src/polarsteps_mcp/utils.py:81-86 (helper)

  Low-level utility function that calls the Polarsteps API to retrieve trip data and handles error cases by returning a dummy Trip object.

  def _get_trip(polarsteps_client: PolarstepsClient, trip_id: int) -> Trip:
      api_response = polarsteps_client.get_trip(str(trip_id))
      if api_response.is_error or api_response.trip is None:
          return Trip(id=-1, uuid="00000000-0000-4000-8000-000000000000")
      return api_response.trip

• src/polarsteps_mcp/server.py:56-58 (handler)

  Dispatch handler in MCP server's call_tool method that matches on tool name, parses args into input model, and invokes the get_trip function.

  case PolarstepsTool.TRIP:
      input = GetTripInput(**args)
      return get_trip(client, input)