ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_tools.py:82-167 (handler)

  Main handler function implementing the logic to list ServiceNow service catalog items via REST API, including filtering, pagination, and formatting.

  def list_catalog_items(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: ListCatalogItemsParams,
  ) -> Dict[str, Any]:
      """
      List service catalog items from ServiceNow.
  
      Args:
          config: Server configuration
          auth_manager: Authentication manager
          params: Parameters for listing catalog items
  
      Returns:
          Dictionary containing catalog items and metadata
      """
      logger.info("Listing service catalog items")
      
      # Build the API URL
      url = f"{config.instance_url}/api/now/table/sc_cat_item"
      
      # Prepare query parameters
      query_params = {
          "sysparm_limit": params.limit,
          "sysparm_offset": params.offset,
          "sysparm_display_value": "true",
          "sysparm_exclude_reference_link": "true",
      }
      
      # Add filters
      filters = []
      if params.active:
          filters.append("active=true")
      if params.category:
          filters.append(f"category={params.category}")
      if params.query:
          filters.append(f"short_descriptionLIKE{params.query}^ORnameLIKE{params.query}")
      
      if filters:
          query_params["sysparm_query"] = "^".join(filters)
      
      # Make the API request
      headers = auth_manager.get_headers()
      headers["Accept"] = "application/json"
      
      try:
          response = requests.get(url, headers=headers, params=query_params)
          response.raise_for_status()
          
          # Process the response
          result = response.json()
          items = result.get("result", [])
          
          # Format the response
          formatted_items = []
          for item in items:
              formatted_items.append({
                  "sys_id": item.get("sys_id", ""),
                  "name": item.get("name", ""),
                  "short_description": item.get("short_description", ""),
                  "category": item.get("category", ""),
                  "price": item.get("price", ""),
                  "picture": item.get("picture", ""),
                  "active": item.get("active", ""),
                  "order": item.get("order", ""),
              })
          
          return {
              "success": True,
              "message": f"Retrieved {len(formatted_items)} catalog items",
              "items": formatted_items,
              "total": len(formatted_items),
              "limit": params.limit,
              "offset": params.offset,
          }
      
      except requests.exceptions.RequestException as e:
          logger.error(f"Error listing catalog items: {str(e)}")
          return {
              "success": False,
              "message": f"Error listing catalog items: {str(e)}",
              "items": [],
              "total": 0,
              "limit": params.limit,
              "offset": params.offset,
          }

• src/servicenow_mcp/tools/catalog_tools.py:19-27 (schema)

  Pydantic BaseModel defining the input schema/parameters for the list_catalog_items tool.

  class ListCatalogItemsParams(BaseModel):
      """Parameters for listing service catalog items."""
      
      limit: int = Field(10, description="Maximum number of catalog items to return")
      offset: int = Field(0, description="Offset for pagination")
      category: Optional[str] = Field(None, description="Filter by category")
      query: Optional[str] = Field(None, description="Search query for catalog items")
      active: bool = Field(True, description="Whether to only return active catalog items")

• src/servicenow_mcp/utils/tool_utils.py:354-360 (registration)

  Tool registration entry in get_tool_definitions() mapping 'list_catalog_items' to its handler function, input schema, description, and serialization hint.

  "list_catalog_items": (
      list_catalog_items_tool,
      ListCatalogItemsParams,
      str,  # Expects JSON string
      "List service catalog items.",
      "json",  # Tool returns list/dict
  ),