get_tickets

Instructions

Implementation Reference

• src/freshdesk_mcp/server.py:176-223 (handler)

  The core handler function for the 'get_tickets' MCP tool, decorated with @mcp.tool() for registration. It fetches tickets from the Freshdesk API endpoint /api/v2/tickets, supports pagination via page and per_page parameters, validates inputs, parses the Link header for pagination info using the helper parse_link_header, and returns tickets with pagination metadata or error messages.

  @mcp.tool()
  async def get_tickets(page: Optional[int] = 1, per_page: Optional[int] = 30) -> Dict[str, Any]:
      """Get tickets from Freshdesk with pagination support."""
      # Validate input parameters
      if page < 1:
          return {"error": "Page number must be greater than 0"}
  
      if per_page < 1 or per_page > 100:
          return {"error": "Page size must be between 1 and 100"}
  
      url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets"
  
      params = {
          "page": page,
          "per_page": per_page
      }
  
      headers = {
          "Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",
          "Content-Type": "application/json"
      }
  
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(url, headers=headers, params=params)
              response.raise_for_status()
  
              # Parse pagination from Link header
              link_header = response.headers.get('Link', '')
              pagination_info = parse_link_header(link_header)
  
              tickets = response.json()
  
              return {
                  "tickets": tickets,
                  "pagination": {
                      "current_page": page,
                      "next_page": pagination_info.get("next"),
                      "prev_page": pagination_info.get("prev"),
                      "per_page": per_page
                  }
              }
  
          except httpx.HTTPStatusError as e:
              return {"error": f"Failed to fetch tickets: {str(e)}"}
          except Exception as e:
              return {"error": f"An unexpected error occurred: {str(e)}"}

• src/freshdesk_mcp/server.py:21-52 (helper)

  Supporting utility function that parses the Freshdesk API's Link header to extract 'next' and 'prev' pagination page numbers. Called within the get_tickets handler to provide pagination metadata in the response.

  def parse_link_header(link_header: str) -> Dict[str, Optional[int]]:
      """Parse the Link header to extract pagination information.
  
      Args:
          link_header: The Link header string from the response
  
      Returns:
          Dictionary containing next and prev page numbers
      """
      pagination = {
          "next": None,
          "prev": None
      }
  
      if not link_header:
          return pagination
  
      # Split multiple links if present
      links = link_header.split(',')
  
      for link in links:
          # Extract URL and rel
          match = re.search(r'<(.+?)>;\s*rel="(.+?)"', link)
          if match:
              url, rel = match.groups()
              # Extract page number from URL
              page_match = re.search(r'page=(\d+)', url)
              if page_match:
                  page_num = int(page_match.group(1))
                  pagination[rel] = page_num
  
      return pagination

• src/freshdesk_mcp/server.py:176-176 (registration)

  The @mcp.tool() decorator registers the get_tickets function as an MCP tool.

  @mcp.tool()