Wakapi MCP Server

Instructions

Implementation Reference

• src/mcp_tools/projects.py:16-58 (handler)

  The main handler function decorated with @app.tool that implements the logic for the 'get_projects' MCP tool. It includes type annotations for parameters and return type (ProjectsViewModel), detailed OpenAPI schema in the docstring, fetches data using the Wakapi client, handles errors, and returns the projects.

  @app.tool
  async def get_projects(
      user: str = "current", q: Optional[str] = None
  ) -> ProjectsViewModel:
      """Retrieve and filter the user's projects.
  
      operationId: get-wakatime-projects
      summary: Retrieve and filter the user's projects
      description: Mimics 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: q
          in: query
          description: Query to filter projects by
          schema:
            type: string
      responses:
        200:
          description: OK
          schema: v1.ProjectsViewModel
  
      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
  
      logger.info(f"get_projects called with user={user}, q={q}")
      client = get_wakapi_client()
  
      try:
          projects = await client.get_projects(user=user, q=q)
          logger.info(f"get_projects result type: {type(projects)}")
          return projects
      except Exception as e:
          logger.error(f"Error in get_projects: {e}")
          raise ValueError(f"Failed to fetch projects: {e}") from e

• main.py:133-135 (registration)

  The import statement in the initialize_tools function that triggers the registration of the get_projects tool. Importing the decorated function registers it with the MCP app.

  from mcp_tools.projects import get_projects
  
  _ = get_projects  # Trigger registration

• src/mcp_tools/projects.py:20-45 (schema)

  OpenAPI-style schema definition in the docstring of the get_projects handler, specifying parameters (user, q), responses, and authentication requirements for input/output validation.

  """Retrieve and filter the user's projects.
  
  operationId: get-wakatime-projects
  summary: Retrieve and filter the user's projects
  description: Mimics 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: q
      in: query
      description: Query to filter projects by
      schema:
        type: string
  responses:
    200:
      description: OK
      schema: v1.ProjectsViewModel
  
  Requires ApiKeyAuth: Set header `Authorization` to your API Key
  encoded as Base64 and prefixed with `Basic`.
  """