Wakapi MCP Server

Instructions

Implementation Reference

• src/mcp_tools/project_detail.py:9-39 (handler)

  MCP tool handler for get_project_detail. Fetches project details using the Wakapi client and returns the model dump.
  @app.tool async def get_project_detail(id: str, user: str = "current") -> dict[str, Any]: """Retrieve a single project. Mimics undocumented endpoint related to https://wakatime.com/developers#projects. Requires ApiKeyAuth: Set header `Authorization` to your API Key encoded as Base64 and prefixed with `Basic`. Args: id (str, required): Project ID to fetch. user (str, required, default="current"): User ID to fetch data for (or 'current'). Returns: v1.ProjectViewModel: - data (Project): - id (str): Project ID. - name (str): Project name. - urlencoded_name (str): URL encoded name. - created_at (str): Creation timestamp. - last_heartbeat_at (str): Last activity timestamp. - human_readable_last_heartbeat_at (str): Human readable last activity. """ client = get_wakapi_client() try: project = await client.get_project_detail(user=user, id=id) return project.model_dump() except Exception as e: raise ValueError(f"Failed to fetch project detail: {e}") from e
• main.py:145-147 (registration)

  Import statement in main.py that triggers registration of the get_project_detail tool via the @app.tool decorator.
  from mcp_tools.project_detail import get_project_detail _ = get_project_detail # Trigger registration
• wakapi_sdk_project/src/wakapi_sdk/client.py:694-746 (helper)

  WakapiClient helper method that performs the actual API call to retrieve project details.
  async def get_project_detail( self, user: str = "current", id: Optional[str] = None ) -> ProjectViewModel: """ Retrieve a single project. operationId: get-wakatime-project summary: Retrieve a single project description: Mimics undocumented endpoint related to https://wakatime.com/developers#projects tags: [wakatime] parameters: - name: user in: path description: User ID to fetch data for (or 'current') required: true schema: type: string - name: id in: path description: Project ID to fetch required: true schema: type: string responses: 200: description: OK schema: v1.ProjectViewModel Requires ApiKeyAuth: Set header `Authorization` to your API Key encoded as Base64 and prefixed with `Basic`. """ if not id: raise ValueError("Project ID is required") url = f"{self.base_url}{self.api_path}/users/{user}/projects/{id}" logger = logging.getLogger(__name__) logger.debug("Calling real Wakapi API for get_project_detail") 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_project_detail: {e.response.status_code} - " f"{e.response.text}", details={ "status_code": e.response.status_code, "method": "get_project_detail", }, ) from e json_data = response.json() return ProjectViewModel.model_validate(json_data)
• src/mcp_tools/dependency_injection.py:105-108 (helper)

  Dependency injection helper function used by the handler to obtain the WakapiClient instance.
  def get_wakapi_client() -> WakapiClient: """Get global Wakapi client.""" return _injector.get_wakapi_client()
• wakapi_sdk_project/src/wakapi_sdk/client.py:226-230 (schema)

  Pydantic model defining the output schema for project details (ProjectViewModel). The handler returns its model_dump().
  class ProjectViewModel(BaseModel): """Model for project view.""" data: Project