ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_variables.py:216-289 (handler)

  The core implementation of the update_catalog_item_variable tool. This function builds a PATCH request to the ServiceNow item_option_new table endpoint, including only provided update fields, handles the API call, and returns a structured response.

  def update_catalog_item_variable(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: UpdateCatalogItemVariableParams,
  ) -> CatalogItemVariableResponse:
      """
      Update an existing variable (form field) for a catalog item.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for updating a catalog item variable.
  
      Returns:
          Response with information about the updated variable.
      """
      api_url = f"{config.instance_url}/api/now/table/item_option_new/{params.variable_id}"
  
      # Build request data with only parameters that are provided
      data = {}
      
      if params.label is not None:
          data["question_text"] = params.label
      if params.mandatory is not None:
          data["mandatory"] = str(params.mandatory).lower()  # ServiceNow expects "true"/"false" strings
      if params.help_text is not None:
          data["help_text"] = params.help_text
      if params.default_value is not None:
          data["default_value"] = params.default_value
      if params.description is not None:
          data["description"] = params.description
      if params.order is not None:
          data["order"] = params.order
      if params.reference_qualifier is not None:
          data["reference_qual"] = params.reference_qualifier
      if params.max_length is not None:
          data["max_length"] = params.max_length
      if params.min is not None:
          data["min"] = params.min
      if params.max is not None:
          data["max"] = params.max
  
      # If no fields to update, return early
      if not data:
          return CatalogItemVariableResponse(
              success=False,
              message="No update parameters provided",
          )
  
      # Make request
      try:
          response = requests.patch(
              api_url,
              json=data,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          result = response.json().get("result", {})
  
          return CatalogItemVariableResponse(
              success=True,
              message="Catalog item variable updated successfully",
              variable_id=params.variable_id,
              details=result,
          )
  
      except requests.RequestException as e:
          logger.error(f"Failed to update catalog item variable: {e}")
          return CatalogItemVariableResponse(
              success=False,
              message=f"Failed to update catalog item variable: {str(e)}",
          ) 

• src/servicenow_mcp/tools/catalog_variables.py:65-79 (schema)

  Pydantic model defining the input schema for the update_catalog_item_variable tool, validating parameters like variable_id (required) and optional update fields.

  class UpdateCatalogItemVariableParams(BaseModel):
      """Parameters for updating a catalog item variable."""
  
      variable_id: str = Field(..., description="The sys_id of the variable to update")
      label: Optional[str] = Field(None, description="The display label for the variable")
      mandatory: Optional[bool] = Field(None, description="Whether the variable is required")
      help_text: Optional[str] = Field(None, description="Help text to display with the variable")
      default_value: Optional[str] = Field(None, description="Default value for the variable")
      description: Optional[str] = Field(None, description="Description of the variable")
      order: Optional[int] = Field(None, description="Display order of the variable")
      reference_qualifier: Optional[str] = Field(None, description="For reference fields, the query to filter reference options")
      max_length: Optional[int] = Field(None, description="Maximum length for string fields")
      min: Optional[int] = Field(None, description="Minimum value for numeric fields")
      max: Optional[int] = Field(None, description="Maximum value for numeric fields")

• src/servicenow_mcp/utils/tool_utils.py:471-477 (registration)

  The registration entry in get_tool_definitions() that associates the tool name 'update_catalog_item_variable' with its handler function (aliased as update_catalog_item_variable_tool), input schema, return type hint, description, and output serialization method.

  "update_catalog_item_variable": (
      update_catalog_item_variable_tool,
      UpdateCatalogItemVariableParams,
      Dict[str, Any],  # Expects dict
      "Update a catalog item variable",
      "dict",  # Tool returns Pydantic model
  ),

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

  Import of the update_catalog_item_variable function into the tools package __init__.py, making it available for export via __all__.

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

• src/servicenow_mcp/tools/__init__.py:135-137 (registration)

  Inclusion of 'update_catalog_item_variable' in the __all__ list of tools/__init__.py, explicitly exporting the tool function from the package.

  "create_catalog_item_variable",
  "list_catalog_item_variables",
  "update_catalog_item_variable",