ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/epic_tools.py:328-428 (handler)

  The core handler function for the 'list_epics' tool. It validates input parameters using ListEpicsParams, constructs a ServiceNow query based on filters like priority, assignment_group, timeframe, and custom query, then performs a GET request to the /api/now/table/rm_epic endpoint to retrieve epics.

  def list_epics(
      auth_manager: AuthManager,
      server_config: ServerConfig,
      params: Dict[str, Any],
  ) -> Dict[str, Any]:
      """
      List epics from ServiceNow.
  
      Args:
          auth_manager: The authentication manager.
          server_config: The server configuration.
          params: The parameters for listing epics.
  
      Returns:
          A list of epics.
      """
      # Unwrap and validate parameters
      result = _unwrap_and_validate_params(
          params, 
          ListEpicsParams
      )
      
      if not result["success"]:
          return result
      
      validated_params = result["params"]
      
      # Build the query
      query_parts = []
      
      if validated_params.priority:
          query_parts.append(f"priority={validated_params.priority}")
      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_epic"
      
      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
          epics = result.get("result", [])
          count = len(epics)
          
          return {
              "success": True,
              "epics": epics,
              "count": count,
              "total": count,  # Use count as total if total is not provided
          }
      except requests.exceptions.RequestException as e:
          logger.error(f"Error listing epics: {e}")
          return {
              "success": False,
              "message": f"Error listing epics: {str(e)}",
          }

• src/servicenow_mcp/tools/epic_tools.py:45-54 (schema)

  Pydantic model defining the input schema for the list_epics tool parameters, including pagination (limit, offset), filters (priority, assignment_group, timeframe, query).

  class ListEpicsParams(BaseModel):
      """Parameters for listing epics."""
  
      limit: Optional[int] = Field(10, description="Maximum number of records to return")
      offset: Optional[int] = Field(0, description="Offset to start from")
      priority: Optional[str] = Field(None, description="Filter by priority")
      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:894-900 (registration)

  Registration of the 'list_epics' tool in the central tool definitions dictionary used by the MCP server. Maps the tool name to its handler function alias, input schema, return type hint, description, and serialization method.

  "list_epics": (
      list_epics_tool,
      ListEpicsParams,
      str,  # Expects JSON string
      "List epics from ServiceNow",
      "json",  # Tool returns list/dict
  ),

• src/servicenow_mcp/tools/__init__.py:100-103 (registration)

  Import and re-export of the list_epics function in the tools package __init__.py, making it available for higher-level imports.

  from servicenow_mcp.tools.epic_tools import (
      create_epic,
      update_epic,
      list_epics,