Productive Simple MCP

Instructions

Implementation Reference

• server.py:525-546 (handler)

  MCP tool registration and handler for 'get_people'. Includes schema definition via Annotated parameters for pagination. Delegates to the tools module implementation.

  @mcp.tool
  async def get_people(
      ctx: Context,
      page_number: Annotated[int, Field(description="Page number for pagination")] = None,
      page_size: Annotated[
          int, Field(description="Optional number of people per page (max 200)")
      ] = None,
  ) -> Dict[str, Any]:
      """Get all team members/people with optional pagination.
  
      Returns team member data including:
      - Person ID, name, and email
      - Role and title information
      - Last seen and join dates
      - Avatar and contact information
      """
      return await tools.get_people(
          ctx,
          page_number=page_number,
          page_size=page_size,
      )

• tools.py:731-759 (helper)

  Primary helper function executing the tool logic: builds API parameters (pagination, sort by last_seen_at), calls productive_client.get_people, applies response filtering, handles API and general errors.

  async def get_people(ctx: Context, page_number: int = None, page_size: int = config.items_per_page) -> ToolResult:
      """List all team members/people with optional pagination.
  
      Developer notes:
      - Supports pagination with configurable default page[size].
      - Sorts by most recent activity first.
      - Applies utils.filter_response to sanitize output.
      - Returns basic info for all team members (name, email, role, etc.).
      """
      try:
          await ctx.info("Fetching all people")
          params = {}
          if page_number is not None:
              params["page[number]"] = page_number
          params["page[size]"] = page_size
          params["sort"] = "-last_seen_at"
  
          result = await client.get_people(params=params if params else None)
          await ctx.info("Successfully retrieved people")
  
          filtered = filter_response(result)
  
          return filtered
  
      except ProductiveAPIError as e:
          await _handle_productive_api_error(ctx, e, "people")
      except Exception as e:
          await ctx.error(f"Unexpected error fetching people: {str(e)}")
          raise e

• productive_client.py:133-136 (helper)

  Low-level client method that performs the HTTP GET request to the Productive API /people endpoint with optional query parameters.

  async def get_people(self, params: Optional[dict] = None) -> Dict[str, Any]:
      """Get all people/team members"""
      return await self._request("GET", "/people", params=params)