Polarsteps MCP Server

Instructions

Implementation Reference

• src/polarsteps_mcp/tools.py:25-34 (handler)

  Implements the core logic of the get_user_profile tool by fetching the user via _get_user helper and returning profile text content or error message.

  def get_user_profile(
      polarsteps_client: PolarstepsClient, input: GetUserProfile
  ) -> list[TextContent]:
      user = _get_user(polarsteps_client, input.username)
      if user.id == -1:
          return single_text_content(
              f"User not found: No Polarsteps user exists with username={input.username}. Please verify the username is correct and the user's profile is public."
          )
      return single_text_content(user.to_profile())

• src/polarsteps_mcp/tools.py:18-22 (schema)

  Pydantic BaseModel defining the input parameters for the get_user_profile tool: username field.

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

• src/polarsteps_mcp/tools.py:202-206 (registration)

  Registers the 'get_user_profile' tool in the PolarstepsTool enum with name, description, and schema reference.

  USER_PROFILE = (
      "get_user_profile",
      "Get a users' profile overview including their living location and their number of countries visited & trips.",
      GetUserProfile,
  )

• src/polarsteps_mcp/server.py:44-47 (registration)

  Dispatches calls to the get_user_profile handler in the server's call_tool method.

  case PolarstepsTool.USER_PROFILE:
      input = GetUserProfile(**args)
      return get_user_profile(client, input)

• src/polarsteps_mcp/utils.py:72-79 (helper)

  Helper function _get_user that retrieves the user from Polarsteps API by username, returns dummy User if not found.

  def _get_user(polarsteps_client: PolarstepsClient, username: str) -> User:
      api_response = polarsteps_client.get_user_by_username(username)
      if api_response.is_error or api_response.user is None:
          return User(
              id=-1, uuid="00000000-0000-4000-8000-000000000000", username="unknown"
          )
      return api_response.user