Wakapi MCP Server

Instructions

Implementation Reference

• src/mcp_tools/stats.py:9-102 (handler)

  Handler function for the 'get_stats' MCP tool. Decorated with @app.tool, defines input parameters with type hints and detailed OpenAPI-style docstring for schema validation. Calls wakapi client to fetch and return StatsViewModel.

  @app.tool
  async def get_stats(
      user: str,
      range: str,
      project: Optional[str] = None,
      language: Optional[str] = None,
      editor: Optional[str] = None,
      operating_system: Optional[str] = None,
      machine: Optional[str] = None,
      label: Optional[str] = None,
  ) -> StatsViewModel:
      """
      Retrieve statistics for a given user.
  
      operationId: get-wakatime-stats
      summary: Retrieve statistics for a given user
      description: Mimics https://wakatime.com/developers#stats
      tags: [wakatime]
      parameters:
        - name: user
          in: path
          description: User ID to fetch data for (or 'current')
          required: true
          schema:
            type: string
        - name: range
          in: path
          description: Range interval identifier
          required: true
          schema:
            type: string
            enum: [
                "today", "yesterday", "week", "month", "year", "7_days",
                "last_7_days", "30_days", "last_30_days", "6_months",
                "last_6_months", "12_months", "last_12_months", "last_year",
                "any", "all_time"
            ]
        - name: project
          in: query
          description: Project to filter by
          schema:
            type: string
        - name: language
          in: query
          description: Language to filter by
          schema:
            type: string
        - name: editor
          in: query
          description: Editor to filter by
          schema:
            type: string
        - name: operating_system
          in: query
          description: OS to filter by
          schema:
            type: str
        - name: machine
          in: query
          description: Machine to filter by
          schema:
            type: string
        - name: label
          in: query
          description: Project label to filter by
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.StatsViewModel
  
      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:
          stats_data: StatsViewModel = await client.get_stats(
              range=range,
              user=user,
              project=project,
              language=language,
              editor=editor,
              operating_system=operating_system,
              machine=machine,
              label=label,
          )
          return stats_data
      except Exception as e:
          raise ValueError(f"Failed to fetch stats: {e}") from e

• main.py:130-132 (registration)

  Explicit import of get_stats function in initialize_tools() to trigger its automatic registration via the @app.tool decorator.

  from mcp_tools.stats import get_stats
  
  _ = get_stats  # Trigger registration

• wakapi_sdk_project/src/wakapi_sdk/client.py:103-107 (schema)

  Pydantic model defining the output schema (StatsViewModel) returned by the get_stats tool.

  class StatsViewModel(BaseModel):
      """Model for stats view."""
  
      data: StatsData

• src/mcp_tools/dependency_injection.py:105-108 (helper)

  Dependency injection helper function used by the handler to obtain the WakapiClient instance for API calls.

  def get_wakapi_client() -> WakapiClient:
      """Get global Wakapi client."""
      return _injector.get_wakapi_client()