Productive Simple MCP

Instructions

Implementation Reference

• tools.py:679-711 (handler)

  Core handler function that implements the get_attachments tool logic: constructs pagination and filter parameters, calls the Productive client API, filters the response using filter_response, logs progress, and handles API-specific and general errors.

  async def get_attachments(
      ctx: Context,
      page_number: int = None,
      page_size: int = config.items_per_page,
      extra_filters: dict = None
  ) -> ToolResult:
      """List attachments with optional filters and pagination (metadata only).
  
      Developer notes:
      - Enforces configurable default page[size] when not provided.
      - Sorting not supported by API - uses default order.
      """
      try:
          await ctx.info("Fetching attachments")
          params = {}
          if page_number is not None:
              params["page[number]"] = page_number
          params["page[size]"] = page_size
          if extra_filters:
              params.update(extra_filters)
  
          result = await client.get_attachments(params=params if params else None)
          await ctx.info("Successfully retrieved attachments")
          
          filtered = filter_response(result)
          
          return filtered
          
      except ProductiveAPIError as e:
          await _handle_productive_api_error(ctx, e, "attachments")
      except Exception as e:
          await ctx.error(f"Unexpected error fetching attachments: {str(e)}")
          raise e

• server.py:565-588 (registration)

  Registers the 'get_attachments' tool in the MCP server using the @mcp.tool decorator. Includes detailed input schema definitions via Annotated parameters with Field descriptions and a comprehensive docstring describing inputs and outputs.

  @mcp.tool
  async def get_attachments(
      ctx: Context,
      page_number: Annotated[int, Field(description="Page number for pagination")] = None,
      page_size: Annotated[
          int, Field(description="Optional number of attachments per page (max 200)")
      ] = None,
      extra_filters: Annotated[
          dict, Field(description="Additional Productive query filters using API syntax")
      ] = None,
  ) -> Dict[str, Any]:
      """Get all attachments/files with optional filtering.
  
      Attachments are files (PDFs, images, documents) that can be associated with
      various Productive entities like tasks, comments, expenses, etc.
  
      Returns:
          Dictionary containing attachment metadata (name, type, size, relationships)
          Note: This provides metadata only, not actual file content
      """
      return await tools.get_attachments(
          ctx, page_number=page_number, page_size=page_size, extra_filters=extra_filters
      )

• productive_client.py:125-127 (helper)

  Helper method in ProductiveClient class that performs the actual HTTP GET request to the '/attachments' API endpoint with optional query parameters.

  async def get_attachments(self, params: Optional[dict] = None) -> Dict[str, Any]:
      """Get all attachments with optional filtering"""
      return await self._request("GET", "/attachments", params=params)