Wakapi MCP Server

Instructions

Implementation Reference

• src/mcp_tools/all_time.py:7-39 (handler)

  The main MCP tool handler function, decorated with @app.tool, that fetches all-time-since-today stats from Wakapi via the client.

  @app.tool
  async def get_all_time_since_today(user: str = "current") -> AllTimeViewModel:
      """Retrieve summary for all time since today for the specified user.
  
      operationId: get-all-time
      summary: Retrieve summary for all time
      description: Mimics https://wakatime.com/developers#all_time_since_today
      tags: [wakatime]
      parameters:
        - name: user
          in: path
          description: User ID to fetch data for (or 'current')
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.AllTimeViewModel
  
      Requires ApiKeyAuth: Set header `Authorization` to your API Key
      encoded as Base64 and prefixed with `Basic`.
      """
      from mcp_tools.dependency_injection import get_wakapi_client
  
      client = get_wakapi_client()
  
      try:
          model: AllTimeViewModel = await client.get_all_time_since_today(user=user)
          return model
      except Exception as e:
          raise ValueError(f"Failed to fetch all time stats: {e}") from e

• main.py:142-144 (registration)

  Import statement that triggers the tool registration by loading the decorated handler function.

  from mcp_tools.all_time import get_all_time_since_today
  
  _ = get_all_time_since_today  # Trigger registration

• wakapi_sdk_project/src/wakapi_sdk/client.py:109-132 (schema)

  Pydantic models defining the output schema: AllTimeViewModel, AllTimeData, and AllTimeRange.

  class AllTimeRange(BaseModel):
      """Model for all time range."""
  
      start: str
      start_date: str
      end: str
      end_date: str
      timezone: str
  
  
  class AllTimeData(BaseModel):
      """Model for all time data."""
  
      total_seconds: float
      text: str
      is_up_to_date: bool
      range: AllTimeRange
  
  
  class AllTimeViewModel(BaseModel):
      """Model for all time view."""
  
      data: AllTimeData

• wakapi_sdk_project/src/wakapi_sdk/client.py:651-692 (helper)

  Underlying WakapiClient method that performs the actual API call to retrieve all-time-since-today data and validates with Pydantic models.

  async def get_all_time_since_today(self, user: str = "current") -> AllTimeViewModel:
      """
      Retrieve summary for all time since today for the specified user.
  
      operationId: get-all-time
      summary: Retrieve summary for all time
      description: Mimics https://wakatime.com/developers#all_time_since_today
      tags: [wakatime]
      parameters:
        - name: user
          in: path
          description: User ID to fetch data for (or 'current')
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.AllTimeViewModel
  
      Requires ApiKeyAuth: Set header `Authorization` to your API Key
      encoded as Base64 and prefixed with `Basic`.
      """
      url = f"{self.base_url}{self.api_path}/users/{user}/all_time_since_today"
  
      logger = logging.getLogger(__name__)
      logger.debug("Calling real Wakapi API for get_all_time_since_today")
      try:
          response = await self.client.get(url, headers=self._get_headers())
          response.raise_for_status()
      except httpx.HTTPStatusError as e:
          raise ApiError(
              f"Wakapi API error in get_all_time_since_today: "
              f"{e.response.status_code} - {e.response.text}",
              details={
                  "status_code": e.response.status_code,
                  "method": "get_all_time_since_today",
              },
          ) from e
  
      json_data = response.json()
      return AllTimeViewModel.model_validate(json_data)