list_incidents
Retrieve and filter incidents from ServiceNow with options to search by state, assigned user, category, or custom query, supporting pagination for efficient incident management.
Instructions
List incidents from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| assigned_to | No | Filter by assigned user | |
| category | No | Filter by category | |
| limit | No | Maximum number of incidents to return | |
| offset | No | Offset for pagination | |
| query | No | Search query for incidents | |
| state | No | Filter by incident state |
Implementation Reference
- Main handler function that implements the list_incidents tool by querying the ServiceNow incident table API with filters and pagination, processing the response into a structured list 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": [] } - Pydantic BaseModel defining the input parameters schema for the list_incidents tool, including pagination, filters, and search query.
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:392-398 (registration)Registration of the list_incidents tool in the central tool definitions dictionary, mapping name to implementation function, params schema, return type hint, description, and serialization method.
"list_incidents": ( list_incidents_tool, ListIncidentsParams, str, # Expects JSON string "List incidents from ServiceNow", "json", # Tool returns list/dict, needs JSON dump ),