ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_tools.py:544-617 (handler)

  The main handler function that implements the move_catalog_items tool logic. It iterates over the provided item_ids, sends PATCH requests to update the 'category' field to the target_category_id for each sc_cat_item in ServiceNow API, handles partial successes and failures, and returns a CatalogResponse.

  def move_catalog_items(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: MoveCatalogItemsParams,
  ) -> CatalogResponse:
      """
      Move catalog items to a different category.
  
      Args:
          config: Server configuration
          auth_manager: Authentication manager
          params: Parameters for moving catalog items
  
      Returns:
          Response containing the result of the operation
      """
      logger.info(f"Moving {len(params.item_ids)} catalog items to category: {params.target_category_id}")
      
      # Build the API URL
      url = f"{config.instance_url}/api/now/table/sc_cat_item"
      
      # Make the API request for each item
      headers = auth_manager.get_headers()
      headers["Accept"] = "application/json"
      headers["Content-Type"] = "application/json"
      
      success_count = 0
      failed_items = []
      
      try:
          for item_id in params.item_ids:
              item_url = f"{url}/{item_id}"
              body = {
                  "category": params.target_category_id
              }
              
              try:
                  response = requests.patch(item_url, headers=headers, json=body)
                  response.raise_for_status()
                  success_count += 1
              except requests.exceptions.RequestException as e:
                  logger.error(f"Error moving catalog item {item_id}: {str(e)}")
                  failed_items.append({"item_id": item_id, "error": str(e)})
          
          # Prepare the response
          if success_count == len(params.item_ids):
              return CatalogResponse(
                  success=True,
                  message=f"Successfully moved {success_count} catalog items to category {params.target_category_id}",
                  data={"moved_items_count": success_count},
              )
          elif success_count > 0:
              return CatalogResponse(
                  success=True,
                  message=f"Partially moved catalog items. {success_count} succeeded, {len(failed_items)} failed.",
                  data={
                      "moved_items_count": success_count,
                      "failed_items": failed_items,
                  },
              )
          else:
              return CatalogResponse(
                  success=False,
                  message="Failed to move any catalog items",
                  data={"failed_items": failed_items},
              )
      
      except Exception as e:
          logger.error(f"Error moving catalog items: {str(e)}")
          return CatalogResponse(
              success=False,
              message=f"Error moving catalog items: {str(e)}",
              data=None,
          ) 

• src/servicenow_mcp/tools/catalog_tools.py:75-80 (schema)

  Pydantic BaseModel defining the input schema for the move_catalog_items tool, requiring a list of item_ids and the target_category_id.

  class MoveCatalogItemsParams(BaseModel):
      """Parameters for moving catalog items between categories."""
      
      item_ids: List[str] = Field(..., description="List of catalog item IDs to move")
      target_category_id: str = Field(..., description="Target category ID to move items to")

• src/servicenow_mcp/utils/tool_utils.py:446-452 (registration)

  Entry in the tool_definitions dictionary that registers the move_catalog_items tool with its handler (aliased as move_catalog_items_tool), schema (MoveCatalogItemsParams), description, and serialization details for the MCP server.

  "move_catalog_items": (
      move_catalog_items_tool,
      MoveCatalogItemsParams,
      str,  # Expects JSON string
      "Move catalog items to a different category.",
      "json_dict",  # Tool returns Pydantic model
  ),