zendesk_get_tickets

Instructions

Implementation Reference

• src/zendesk_mcp/tools/list_tickets.py:68-77 (handler)

  The `zendesk_get_tickets` tool handler function, registered as an MCP tool via the `@mcp.tool()` decorator and exposed by `register_list_tickets_tools()`. It accepts optional pagination/sorting parameters and delegates to `_get_tickets_data()`.

  def register_list_tickets_tools(mcp) -> None:
      @mcp.tool()
      def zendesk_get_tickets(
          page: int = 1,
          per_page: int = 25,
          sort_by: str = "created_at",
          sort_order: str = "desc",
      ) -> str:
          """List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata."""
          return _get_tickets_data(page=page, per_page=per_page, sort_by=sort_by, sort_order=sort_order)

• src/zendesk_mcp/tools/list_tickets.py:10-65 (helper)

  The `_get_tickets_data()` helper that performs the actual Zendesk API call via httpx, validates parameters, constructs the API URL, parses the response, and returns a JSON string with ticket data and pagination metadata.

  def _get_tickets_data(
      page: int = 1,
      per_page: int = 25,
      sort_by: str = "created_at",
      sort_order: str = "desc",
  ) -> str:
      if sort_by not in _VALID_SORT_BY:
          return f"Invalid sort_by '{sort_by}'. Valid values: {', '.join(sorted(_VALID_SORT_BY))}"
      if sort_order not in _VALID_SORT_ORDER:
          return f"Invalid sort_order '{sort_order}'. Valid values: {', '.join(sorted(_VALID_SORT_ORDER))}"
      per_page = max(1, min(per_page, _MAX_PER_PAGE))
      page = max(1, int(page))
  
      try:
          subdomain, token = get_oauth_session()
      except ConfigError as e:
          return str(e)
  
      url = f"https://{subdomain}.zendesk.com/api/v2/tickets.json"
      try:
          response = httpx.get(
              url,
              params={"page": page, "per_page": per_page, "sort_by": sort_by, "sort_order": sort_order},
              headers={"Authorization": f"Bearer {token}"},
              timeout=30,
          )
          response.raise_for_status()
          data = response.json()
      except Exception as e:
          return f"Zendesk API error: {e}"
  
      raw_tickets = data.get("tickets", [])
      tickets = [{
          "id": t.get("id"),
          "subject": t.get("subject"),
          "status": t.get("status"),
          "priority": t.get("priority"),
          "description": t.get("description"),
          "created_at": t.get("created_at"),
          "updated_at": t.get("updated_at"),
          "requester_id": t.get("requester_id"),
          "assignee_id": t.get("assignee_id"),
      } for t in raw_tickets]
  
      has_more = data.get("next_page") is not None
      return json.dumps({
          "tickets": tickets,
          "page": page,
          "per_page": per_page,
          "count": len(tickets),
          "sort_by": sort_by,
          "sort_order": sort_order,
          "has_more": has_more,
          "next_page": page + 1 if has_more else None,
          "previous_page": page - 1 if page > 1 else None,
      }, indent=2)

• src/zendesk_mcp/tools/list_tickets.py:1-7 (helper)

  Imports and constants: httpx for API calls, `get_oauth_session`/`ConfigError` from client module, and validation constants for sort_by/sort_order/per_page.

  import json
  import httpx
  from zendesk_mcp.client import get_oauth_session, ConfigError
  
  _VALID_SORT_BY = {"created_at", "updated_at", "priority", "status"}
  _VALID_SORT_ORDER = {"asc", "desc"}
  _MAX_PER_PAGE = 100

• src/zendesk_mcp/server.py:22-22 (registration)

  Import of `register_list_tickets_tools` from the list_tickets module.

  from zendesk_mcp.tools.list_tickets import register_list_tickets_tools

• src/zendesk_mcp/server.py:42-42 (registration)

  Registration call: `register_list_tickets_tools(mcp)` which triggers the decorator that registers `zendesk_get_tickets` as an MCP tool.

  register_list_tickets_tools(mcp)