ServiceNow MCP Server

Instructions

Implementation Reference

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

  The handler function that executes the tool logic: queries ServiceNow's item_option_new table for variables of a catalog item, supports pagination and details flag.

  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/tools/catalog_variables.py:47-54 (schema)

  Pydantic model defining the input parameters for the tool: catalog_item_id (required), include_details, limit, offset.

  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)

  Pydantic model for the tool's response: success, message, variables list, 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/utils/tool_utils.py:418-424 (registration)

  Registration of the tool in the central tool_definitions dictionary used by the MCP server: maps name to (handler, input_schema, return_type, description, serialization).

  "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/__init__.py:18-22 (registration)

  Import of the handler function into the tools package namespace, exposing it for use in tool_utils.py.

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