list_catalog_item_variables

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_variables.py:154-214 (handler)

  The handler function that executes the tool: queries ServiceNow's item_option_new table API for variables of the given catalog item sys_id, applies ORDERBYorder, optional pagination (sysparm_limit/offset), conditional field selection or full details, and returns a structured response.

  def list_catalog_item_variables(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: ListCatalogItemVariablesParams,
  ) -> ListCatalogItemVariablesResponse:
      """
      List all variables (form fields) for a catalog item.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for listing catalog item variables.
  
      Returns:
          Response with a list of variables for the catalog item.
      """
      # Build query parameters
      query_params = {
          "sysparm_query": f"cat_item={params.catalog_item_id}^ORDERBYorder",
      }
      
      if params.limit:
          query_params["sysparm_limit"] = params.limit
      if params.offset:
          query_params["sysparm_offset"] = params.offset
      
      # Include all fields if detailed info is requested
      if params.include_details:
          query_params["sysparm_display_value"] = "true"
          query_params["sysparm_exclude_reference_link"] = "false"
      else:
          query_params["sysparm_fields"] = "sys_id,name,type,question_text,order,mandatory"
  
      api_url = f"{config.instance_url}/api/now/table/item_option_new"
  
      # Make request
      try:
          response = requests.get(
              api_url,
              params=query_params,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          result = response.json().get("result", [])
          
          return ListCatalogItemVariablesResponse(
              success=True,
              message=f"Retrieved {len(result)} variables for catalog item",
              variables=result,
              count=len(result),
          )
  
      except requests.RequestException as e:
          logger.error(f"Failed to list catalog item variables: {e}")
          return ListCatalogItemVariablesResponse(
              success=False,
              message=f"Failed to list catalog item variables: {str(e)}",
          )

• src/servicenow_mcp/utils/tool_utils.py:464-470 (registration)

  Explicit registration of the tool in get_tool_definitions(): maps tool name to the imported handler alias, input Pydantic model (ListCatalogItemVariablesParams), expected return type hint, description, and serialization strategy ('dict'). This dict is loaded by the MCP server for tool listing and calling.

  "list_catalog_item_variables": (
      list_catalog_item_variables_tool,
      ListCatalogItemVariablesParams,
      Dict[str, Any],  # Expects dict
      "List catalog item variables",
      "dict",  # Tool returns Pydantic model
  ),

• src/servicenow_mcp/tools/catalog_variables.py:47-54 (schema)

  Input schema: Pydantic model validating tool arguments. Requires catalog_item_id (sys_id string); optional include_details (bool, default True for full fields), limit/offset (int) for pagination.

  class ListCatalogItemVariablesParams(BaseModel):
      """Parameters for listing catalog item variables."""
  
      catalog_item_id: str = Field(..., description="The sys_id of the catalog item")
      include_details: bool = Field(True, description="Whether to include detailed information about each variable")
      limit: Optional[int] = Field(None, description="Maximum number of variables to return")
      offset: Optional[int] = Field(None, description="Offset for pagination")

• src/servicenow_mcp/tools/catalog_variables.py:56-63 (schema)

  Output schema: Pydantic model structuring the tool response with success flag, result message, variables list (from API), and count.

  class ListCatalogItemVariablesResponse(BaseModel):
      """Response from listing catalog item variables."""
  
      success: bool = Field(..., description="Whether the operation was successful")
      message: str = Field(..., description="Message describing the result")
      variables: List[Dict[str, Any]] = Field([], description="List of variables")
      count: int = Field(0, description="Total number of variables found")

• src/servicenow_mcp/tools/__init__.py:18-22 (registration)

  Imports the handler function (along with related catalog variable tools) into the top-level tools namespace, enabling its use in tool_utils.py and server.py.

  from servicenow_mcp.tools.catalog_variables import (
      create_catalog_item_variable,
      list_catalog_item_variables,
      update_catalog_item_variable,
  )