list_change_requests
Retrieve and filter change requests from ServiceNow to monitor and manage IT infrastructure modifications. Supports filtering by state, type, category, assignment group, and timeframe.
Instructions
List change requests from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| assignment_group | No | Filter by assignment group | |
| category | No | Filter by category | |
| limit | No | Maximum number of records to return | |
| offset | No | Offset to start from | |
| query | No | Additional query string | |
| state | No | Filter by state | |
| timeframe | No | Filter by timeframe (upcoming, in-progress, completed) | |
| type | No | Filter by type (normal, standard, emergency) |
Implementation Reference
- The handler function that executes the tool logic: validates params, builds ServiceNow query with filters, makes GET request to /api/now/table/change_request, returns list of change requests.
def list_change_requests( auth_manager: AuthManager, server_config: ServerConfig, params: Dict[str, Any], ) -> Dict[str, Any]: """ List change requests from ServiceNow. Args: auth_manager: The authentication manager. server_config: The server configuration. params: The parameters for listing change requests. Returns: A list of change requests. """ # Unwrap and validate parameters result = _unwrap_and_validate_params( params, ListChangeRequestsParams ) if not result["success"]: return result validated_params = result["params"] # Build the query query_parts = [] if validated_params.state: query_parts.append(f"state={validated_params.state}") if validated_params.type: query_parts.append(f"type={validated_params.type}") if validated_params.category: query_parts.append(f"category={validated_params.category}") if validated_params.assignment_group: query_parts.append(f"assignment_group={validated_params.assignment_group}") # Handle timeframe filtering if validated_params.timeframe: now = datetime.now().strftime("%Y-%m-%d %H:%M:%S") if validated_params.timeframe == "upcoming": query_parts.append(f"start_date>{now}") elif validated_params.timeframe == "in-progress": query_parts.append(f"start_date<{now}^end_date>{now}") elif validated_params.timeframe == "completed": query_parts.append(f"end_date<{now}") # Add any additional query string if validated_params.query: query_parts.append(validated_params.query) # Combine query parts query = "^".join(query_parts) if query_parts else "" # Get the instance URL instance_url = _get_instance_url(auth_manager, server_config) if not instance_url: return { "success": False, "message": "Cannot find instance_url in either server_config or auth_manager", } # Get the headers headers = _get_headers(auth_manager, server_config) if not headers: return { "success": False, "message": "Cannot find get_headers method in either auth_manager or server_config", } # Make the API request url = f"{instance_url}/api/now/table/change_request" params = { "sysparm_limit": validated_params.limit, "sysparm_offset": validated_params.offset, "sysparm_query": query, "sysparm_display_value": "true", } try: response = requests.get(url, headers=headers, params=params) response.raise_for_status() result = response.json() # Handle the case where result["result"] is a list change_requests = result.get("result", []) count = len(change_requests) return { "success": True, "change_requests": change_requests, "count": count, "total": count, # Use count as total if total is not provided } except requests.exceptions.RequestException as e: logger.error(f"Error listing change requests: {e}") return { "success": False, "message": f"Error listing change requests: {str(e)}", } - Pydantic BaseModel defining the input parameters for the list_change_requests tool, including pagination, filters, and custom query.
class ListChangeRequestsParams(BaseModel): """Parameters for listing change requests.""" limit: Optional[int] = Field(10, description="Maximum number of records to return") offset: Optional[int] = Field(0, description="Offset to start from") state: Optional[str] = Field(None, description="Filter by state") type: Optional[str] = Field(None, description="Filter by type (normal, standard, emergency)") category: Optional[str] = Field(None, description="Filter by category") assignment_group: Optional[str] = Field(None, description="Filter by assignment group") timeframe: Optional[str] = Field(None, description="Filter by timeframe (upcoming, in-progress, completed)") query: Optional[str] = Field(None, description="Additional query string") - src/servicenow_mcp/utils/tool_utils.py:493-499 (registration)Registers the tool in get_tool_definitions() with handler alias, schema, description, and JSON serialization for MCP server.
"list_change_requests": ( list_change_requests_tool, ListChangeRequestsParams, str, # Expects JSON string "List change requests from ServiceNow", "json", # Tool returns list/dict ), - src/servicenow_mcp/tools/__init__.py:28-28 (registration)Re-exports the list_change_requests function from change_tools for use in tool_utils.
list_change_requests, - Helper function used by the handler to unwrap, validate input parameters against the Pydantic schema, and handle common input formats.
def _unwrap_and_validate_params(params: Any, model_class: Type[T], required_fields: List[str] = None) -> Dict[str, Any]: """ Helper function to unwrap and validate parameters. Args: params: The parameters to unwrap and validate. model_class: The Pydantic model class to validate against. required_fields: List of required field names. Returns: A tuple of (success, result) where result is either the validated parameters or an error message. """ # Handle case where params might be wrapped in another dictionary if isinstance(params, dict) and len(params) == 1 and "params" in params and isinstance(params["params"], dict): logger.warning("Detected params wrapped in a 'params' key. Unwrapping...") params = params["params"] # Handle case where params might be a Pydantic model object if not isinstance(params, dict): try: # Try to convert to dict if it's a Pydantic model logger.warning("Params is not a dictionary. Attempting to convert...") params = params.dict() if hasattr(params, "dict") else dict(params) except Exception as e: logger.error(f"Failed to convert params to dictionary: {e}") return { "success": False, "message": f"Invalid parameters format. Expected a dictionary, got {type(params).__name__}", } # Validate required parameters are present if required_fields: for field in required_fields: if field not in params: return { "success": False, "message": f"Missing required parameter '{field}'", } try: # Validate parameters against the model validated_params = model_class(**params) return { "success": True, "params": validated_params, } except Exception as e: logger.error(f"Error validating parameters: {e}") return { "success": False, "message": f"Error validating parameters: {str(e)}", }