list_incidents
Retrieve and filter ServiceNow incident records by state, assignee, category, or search query with pagination controls.
Instructions
List incidents from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of incidents to return | |
| offset | No | Offset for pagination | |
| state | No | Filter by incident state | |
| assigned_to | No | Filter by assigned user | |
| category | No | Filter by category | |
| query | No | Search query for incidents |
Implementation Reference
- The main handler function that implements the list_incidents tool logic, querying the ServiceNow API for incidents based on parameters and returning formatted results.
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 model defining the input parameters for the list_incidents tool.
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:346-352 (registration)Registration of the list_incidents tool in the central tool definitions dictionary used for MCP server.
"list_incidents": ( list_incidents_tool, ListIncidentsParams, str, # Expects JSON string "List incidents from ServiceNow", "json", # Tool returns list/dict, needs JSON dump ),