Polarsteps MCP Server

Instructions

Implementation Reference

• src/polarsteps_mcp/tools.py:61-70 (handler)

  The core handler function that implements the get_user_stats tool logic. It retrieves the user via _get_user helper and returns their stats as TextContent or an error message if none available.

  def get_user_stats(
      polarsteps_client: PolarstepsClient, input: GetUserStats
  ) -> list[TextContent]:
      user = _get_user(polarsteps_client, input.username)
      if user.stats is None:
          return single_text_content(
              f"No travel stats found for username={input.username}"
          )
      return single_text_content(user.stats)

• src/polarsteps_mcp/tools.py:54-58 (schema)

  Pydantic schema/model for the input parameters of the get_user_stats tool, defining the required 'username' field.

  class GetUserStats(BaseModel):
      username: str = Field(
          ...,
          description="The username of the Polarstep user to look for.",
      )

• src/polarsteps_mcp/tools.py:212-216 (registration)

  Registration of the 'get_user_stats' tool within the PolarstepsTool Enum, specifying the tool name, description, and input schema class.

  USER_STATS = (
      "get_user_stats",
      "Get available travel statistics and metrics for a Polarsteps user, including countries visited, total distance traveled, trip counts, and detailed travel analytics. Perfect for getting a complete picture of someone's travel history and achievements.",
      GetUserStats,
  )

• src/polarsteps_mcp/server.py:52-54 (registration)

  Dispatch/handling case in the MCP server's call_tool method that invokes the get_user_stats implementation from tools.py.

  case PolarstepsTool.USER_STATS:
      input = GetUserStats(**args)
      return get_user_stats(client, input)