list_incidents

Instructions

Implementation Reference

• src/servicenow_mcp/tools/incident_tools.py:459-546 (handler)

  The core handler function for the 'list_incidents' tool. Queries the ServiceNow 'incident' table API with pagination and optional filters (state, assigned_to, category, query), processes the response to handle reference fields, and returns a structured dictionary of incidents.

  def list_incidents(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: ListIncidentsParams,
  ) -> dict:
      """
      List incidents from ServiceNow.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for listing incidents.
  
      Returns:
          Dictionary with list of incidents.
      """
      api_url = f"{config.api_url}/table/incident"
  
      # Build query parameters
      query_params = {
          "sysparm_limit": params.limit,
          "sysparm_offset": params.offset,
          "sysparm_display_value": "true",
          "sysparm_exclude_reference_link": "true",
      }
      
      # Add filters
      filters = []
      if params.state:
          filters.append(f"state={params.state}")
      if params.assigned_to:
          filters.append(f"assigned_to={params.assigned_to}")
      if params.category:
          filters.append(f"category={params.category}")
      if params.query:
          filters.append(f"short_descriptionLIKE{params.query}^ORdescriptionLIKE{params.query}")
      
      if filters:
          query_params["sysparm_query"] = "^".join(filters)
      
      # Make request
      try:
          response = requests.get(
              api_url,
              params=query_params,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
          
          data = response.json()
          incidents = []
          
          for incident_data in data.get("result", []):
              # Handle assigned_to field which could be a string or a dictionary
              assigned_to = incident_data.get("assigned_to")
              if isinstance(assigned_to, dict):
                  assigned_to = assigned_to.get("display_value")
              
              incident = {
                  "sys_id": incident_data.get("sys_id"),
                  "number": incident_data.get("number"),
                  "short_description": incident_data.get("short_description"),
                  "description": incident_data.get("description"),
                  "state": incident_data.get("state"),
                  "priority": incident_data.get("priority"),
                  "assigned_to": assigned_to,
                  "category": incident_data.get("category"),
                  "subcategory": incident_data.get("subcategory"),
                  "created_on": incident_data.get("sys_created_on"),
                  "updated_on": incident_data.get("sys_updated_on"),
              }
              incidents.append(incident)
          
          return {
              "success": True,
              "message": f"Found {len(incidents)} incidents",
              "incidents": incidents
          }
          
      except requests.RequestException as e:
          logger.error(f"Failed to list incidents: {e}")
          return {
              "success": False,
              "message": f"Failed to list incidents: {str(e)}",
              "incidents": []
          }

• src/servicenow_mcp/tools/incident_tools.py:69-78 (schema)

  Pydantic model defining the input schema for the list_incidents tool, including pagination (limit, offset) and optional filters.

  class ListIncidentsParams(BaseModel):
      """Parameters for listing incidents."""
      
      limit: int = Field(10, description="Maximum number of incidents to return")
      offset: int = Field(0, description="Offset for pagination")
      state: Optional[str] = Field(None, description="Filter by incident state")
      assigned_to: Optional[str] = Field(None, description="Filter by assigned user")
      category: Optional[str] = Field(None, description="Filter by category")
      query: Optional[str] = Field(None, description="Search query for incidents")

• src/servicenow_mcp/utils/tool_utils.py:396-402 (registration)

  Registers the 'list_incidents' tool in the central get_tool_definitions() function's dictionary, specifying the handler function alias, input schema, return type hint, description, and serialization method ('json').

  "list_incidents": (
      list_incidents_tool,
      ListIncidentsParams,
      str,  # Expects JSON string
      "List incidents from ServiceNow",
      "json",  # Tool returns list/dict, needs JSON dump
  ),

• src/servicenow_mcp/tools/__init__.py:42-49 (registration)

  Imports list_incidents from incident_tools.py into the tools package namespace, making it available for export via __all__.

  from servicenow_mcp.tools.incident_tools import (
      add_comment,
      create_incident,
      list_incidents,
      resolve_incident,
      update_incident,
      get_incident_by_number,
  )

• src/servicenow_mcp/utils/tool_utils.py:134-135 (registration)

  Imports the list_incidents handler as list_incidents_tool alias for use in tool definitions.

      list_incidents as list_incidents_tool,
  )