ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_optimization.py:43-142 (handler)

  The main handler function implementing the get_optimization_recommendations tool. It processes various recommendation types by calling helper functions to fetch inactive items, low usage items, etc., and compiles them into recommendations.

  def get_optimization_recommendations(
      config: ServerConfig, auth_manager: AuthManager, params: OptimizationRecommendationsParams
  ) -> Dict:
      """
      Get optimization recommendations for the ServiceNow Service Catalog.
  
      Args:
          config: The server configuration
          auth_manager: The authentication manager
          params: The parameters for getting optimization recommendations
  
      Returns:
          A dictionary containing the optimization recommendations
      """
      logger.info("Getting catalog optimization recommendations")
      
      recommendations = []
      category_id = params.category_id
      
      try:
          # Get recommendations based on the requested types
          for rec_type in params.recommendation_types:
              if rec_type == "inactive_items":
                  items = _get_inactive_items(config, auth_manager, category_id)
                  if items:
                      recommendations.append({
                          "type": "inactive_items",
                          "title": "Inactive Catalog Items",
                          "description": "Items that are currently inactive in the catalog",
                          "items": items,
                          "impact": "medium",
                          "effort": "low",
                          "action": "Review and either update or remove these items",
                      })
              
              elif rec_type == "low_usage":
                  items = _get_low_usage_items(config, auth_manager, category_id)
                  if items:
                      recommendations.append({
                          "type": "low_usage",
                          "title": "Low Usage Catalog Items",
                          "description": "Items that have very few orders",
                          "items": items,
                          "impact": "medium",
                          "effort": "medium",
                          "action": "Consider promoting these items or removing them if no longer needed",
                      })
              
              elif rec_type == "high_abandonment":
                  items = _get_high_abandonment_items(config, auth_manager, category_id)
                  if items:
                      recommendations.append({
                          "type": "high_abandonment",
                          "title": "High Abandonment Rate Items",
                          "description": "Items that are frequently added to cart but not ordered",
                          "items": items,
                          "impact": "high",
                          "effort": "medium",
                          "action": "Simplify the request process or improve the item description",
                      })
              
              elif rec_type == "slow_fulfillment":
                  items = _get_slow_fulfillment_items(config, auth_manager, category_id)
                  if items:
                      recommendations.append({
                          "type": "slow_fulfillment",
                          "title": "Slow Fulfillment Items",
                          "description": "Items that take longer than average to fulfill",
                          "items": items,
                          "impact": "high",
                          "effort": "high",
                          "action": "Review the fulfillment process and identify bottlenecks",
                      })
              
              elif rec_type == "description_quality":
                  items = _get_poor_description_items(config, auth_manager, category_id)
                  if items:
                      recommendations.append({
                          "type": "description_quality",
                          "title": "Poor Description Quality",
                          "description": "Items with missing, short, or low-quality descriptions",
                          "items": items,
                          "impact": "medium",
                          "effort": "low",
                          "action": "Improve the descriptions to better explain the item's purpose and benefits",
                      })
          
          return {
              "success": True,
              "recommendations": recommendations,
          }
      
      except Exception as e:
          logger.error(f"Error getting optimization recommendations: {e}")
          return {
              "success": False,
              "message": f"Error getting optimization recommendations: {str(e)}",
              "recommendations": [],
          }

• src/servicenow_mcp/tools/catalog_optimization.py:23-29 (schema)

  Pydantic BaseModel defining the input schema for the tool: list of recommendation_types and optional category_id.

  class OptimizationRecommendationsParams(BaseModel):
      """Parameters for getting optimization recommendations."""
  
      recommendation_types: List[str]
      category_id: Optional[str] = None

• src/servicenow_mcp/utils/tool_utils.py:442-448 (registration)

  Tool registration in the central get_tool_definitions() function, associating the tool name with its handler, input schema, description, and serialization details.

  "get_optimization_recommendations": (
      get_optimization_recommendations_tool,
      OptimizationRecommendationsParams,
      str,  # Expects JSON string
      "Get optimization recommendations for the service catalog.",
      "json",  # Tool returns list/dict
  ),

• src/servicenow_mcp/tools/__init__.py:6-9 (registration)

  Export/import of the tool handler in the tools package __init__.py, making it available for use in tool_utils.py and elsewhere.

  from servicenow_mcp.tools.catalog_optimization import (
      get_optimization_recommendations,
      update_catalog_item,
  )

• src/servicenow_mcp/tools/catalog_optimization.py:201-238 (helper)

  Helper function to retrieve inactive catalog items via ServiceNow API, used by the main handler for 'inactive_items' recommendation type.

  def _get_inactive_items(
      config: ServerConfig, auth_manager: AuthManager, category_id: Optional[str] = None
  ) -> List[Dict]:
      """
      Get inactive catalog items.
  
      Args:
          config: The server configuration
          auth_manager: The authentication manager
          category_id: Optional category ID to filter by
  
      Returns:
          A list of inactive catalog items
      """
      try:
          # Build the query
          query = "active=false"
          if category_id:
              query += f"^category={category_id}"
          
          # Make the API request
          url = f"{config.instance_url}/api/now/table/sc_cat_item"
          headers = auth_manager.get_headers()
          params = {
              "sysparm_query": query,
              "sysparm_fields": "sys_id,name,short_description,category",
              "sysparm_limit": "50",
          }
          
          response = requests.get(url, headers=headers, params=params)
          response.raise_for_status()
          
          return response.json()["result"]
      
      except Exception as e:
          logger.error(f"Error getting inactive items: {e}")
          return []