Wakapi MCP Server

Instructions

Implementation Reference

• src/mcp_tools/users.py:7-38 (handler)

  The core handler function for the MCP 'get_user' tool, decorated with @app.tool(). It retrieves the Wakapi client via dependency injection and calls its get_user method, returning a UserViewModel or raising ValueError on failure. Includes OpenAPI-style docstring defining input/output schema.

  @app.tool
  async def get_user(user: str = "current") -> UserViewModel:
      """Retrieve the given user.
  
      operationId: get-wakatime-user
      summary: Retrieve the given user
      description: Mimics https://wakatime.com/developers#users
      tags: [wakatime]
      parameters:
        - name: user
          in: path
          description: User ID to fetch (or 'current')
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.UserViewModel
  
      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:
          user_model: UserViewModel = await client.get_user(user=user)
          return user_model
      except Exception as e:
          raise ValueError(f"Failed to fetch user: {e}") from e

• main.py:139-141 (registration)

  Import statement and reference in initialize_tools() that triggers the automatic registration of the get_user tool via its @app.tool decorator.

  from mcp_tools.users import get_user
  
  _ = get_user  # Trigger registration

• wakapi_sdk_project/src/wakapi_sdk/client.py:232-236 (schema)

  Pydantic BaseModel defining the output schema (UserViewModel) returned by the get_user tool, wrapping the User data model.

  class UserViewModel(BaseModel):
      """Model for user view."""
  
      data: User

• wakapi_sdk_project/src/wakapi_sdk/client.py:611-649 (helper)

  Underlying WakapiClient.get_user method called by the MCP tool handler. Performs the actual HTTP request to the Wakapi API and validates the response into UserViewModel.

  async def get_user(self, user: str = "current") -> UserViewModel:
      """
      Retrieve the given user.
  
      operationId: get-wakatime-user
      summary: Retrieve the given user
      description: Mimics https://wakatime.com/developers#users
      tags: [wakatime]
      parameters:
        - name: user
          in: path
          description: User ID to fetch (or 'current')
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.UserViewModel
  
      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}"
  
      logger = logging.getLogger(__name__)
      logger.debug("Calling real Wakapi API for get_user")
      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_user: {e.response.status_code} - "
              f"{e.response.text}",
              details={"status_code": e.response.status_code, "method": "get_user"},
          ) from e
  
      json_data = response.json()
      return UserViewModel.model_validate(json_data)