list_stories
Retrieve and filter user stories from ServiceNow to manage agile project workflows. Use parameters like state, timeframe, and assignment group to find specific stories.
Instructions
List stories from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return | |
| offset | No | Offset to start from | |
| state | No | Filter by state | |
| assignment_group | No | Filter by assignment group | |
| timeframe | No | Filter by timeframe (upcoming, in-progress, completed) | |
| query | No | Additional query string |
Implementation Reference
- The handler function that implements the list_stories tool logic, querying the ServiceNow rm_story table via REST API with filtering and pagination.def list_stories( auth_manager: AuthManager, server_config: ServerConfig, params: Dict[str, Any], ) -> Dict[str, Any]: """ List stories from ServiceNow. Args: auth_manager: The authentication manager. server_config: The server configuration. params: The parameters for listing stories. Returns: A list of stories. """ # Unwrap and validate parameters result = _unwrap_and_validate_params( params, ListStoriesParams ) 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.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/rm_story" 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 stories = result.get("result", []) count = len(stories) return { "success": True, "stories": stories, "count": count, "total": count, # Use count as total if total is not provided } except requests.exceptions.RequestException as e: logger.error(f"Error listing stories: {e}") return { "success": False, "message": f"Error listing stories: {str(e)}", }
- Pydantic BaseModel defining the input parameters for the list_stories tool, including limits, filters, and query options.class ListStoriesParams(BaseModel): """Parameters for listing stories.""" 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") 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:851-857 (registration)Registration of the 'list_stories' tool in the central tool_definitions dictionary, mapping name to implementation, params, description, etc."list_stories": ( list_stories_tool, ListStoriesParams, str, # Expects JSON string "List stories from ServiceNow", "json", # Tool returns list/dict ),
- src/servicenow_mcp/tools/__init__.py:92-95 (registration)Import of list_stories function into the tools package __init__.py for easy access.from servicenow_mcp.tools.story_tools import ( create_story, update_story, list_stories,