zendesk_search_tickets

Instructions

Implementation Reference

• src/zendesk_mcp/tools/ticket.py:5-39 (handler)

  Core handler function that executes the Zendesk search query, processes results, and returns JSON. Takes keywords, status, and limit parameters; uses the Zendesk API client to search tickets and returns structured data.

  def _search_tickets_data(keywords: str | None, status: str | None, limit: int) -> str:
      try:
          client = get_client()
          query = "type:ticket"
          if keywords:
              query += f" {keywords}"
          if status:
              query += f" status:{status}"
          results = client.search(query=query, sort_by="created_at", sort_order="desc")
          tickets = []
          for ticket in results:
              if len(tickets) >= limit:
                  break
              tickets.append({
                  "id": ticket.id,
                  "subject": ticket.subject,
                  "status": ticket.status,
                  "priority": ticket.priority,
                  "requester": {
                      "name": ticket.requester.name,
                      "email": ticket.requester.email,
                  },
                  "assignee": {
                      "name": ticket.assignee.name,
                      "email": ticket.assignee.email,
                  } if ticket.assignee else None,
                  "created_at": str(ticket.created_at),
                  "updated_at": str(ticket.updated_at),
                  "description": ticket.description[:300] if ticket.description else "",
              })
          return json.dumps(tickets, indent=2)
      except ConfigError as e:
          return str(e)
      except Exception as e:
          return f"Zendesk API error: {e}"

• src/zendesk_mcp/tools/ticket.py:87-89 (schema)

  The MCP tool decorator defines the input schema: keywords (str, default ''), status (str, default ''), limit (int, default 50). The docstring documents parameter usage. It delegates to _search_tickets_data.

  def zendesk_search_tickets(keywords: str = "", status: str = "", limit: int = 50) -> str:
      """Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates."""
      return _search_tickets_data(keywords or None, status or None, limit)

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

  Registration call in main() function - register_ticket_tools(mcp) registers all ticket tools (including zendesk_search_tickets) on the FastMCP server instance.

  register_ticket_tools(mcp)

• src/zendesk_mcp/tools/ticket.py:80-90 (registration)

  The register_ticket_tools function contains the @mcp.tool() decorator that registers zendesk_search_tickets as an MCP tool on the server.

  def register_ticket_tools(mcp) -> None:
      @mcp.tool()
      def zendesk_get_ticket(ticket_id: int) -> str:
          """Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description."""
          return _get_ticket_data(ticket_id)
  
      @mcp.tool()
      def zendesk_search_tickets(keywords: str = "", status: str = "", limit: int = 50) -> str:
          """Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates."""
          return _search_tickets_data(keywords or None, status or None, limit)