ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/knowledge_base.py:325-395 (handler)

  The handler function that implements the create_category tool by making a POST request to ServiceNow's kb_category table endpoint with the provided parameters.

  def create_category(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: CreateCategoryParams,
  ) -> CategoryResponse:
      """
      Create a new category in a knowledge base.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for creating the category.
  
      Returns:
          Response with the created category details.
      """
      api_url = f"{config.api_url}/table/kb_category"
  
      # Build request data
      data = {
          "label": params.title,
          "kb_knowledge_base": params.knowledge_base,
          # Convert boolean to string "true"/"false" as ServiceNow expects
          "active": str(params.active).lower(),
      }
  
      if params.description:
          data["description"] = params.description
      if params.parent_category:
          data["parent"] = params.parent_category
      if params.parent_table:
          data["parent_table"] = params.parent_table
      
      # Log the request data for debugging
      logger.debug(f"Creating category with data: {data}")
  
      # Make request
      try:
          response = requests.post(
              api_url,
              json=data,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          result = response.json().get("result", {})
          logger.debug(f"Category creation response: {result}")
  
          # Log the specific fields to check the knowledge base assignment
          if "kb_knowledge_base" in result:
              logger.debug(f"Knowledge base in response: {result['kb_knowledge_base']}")
          
          # Log the active status
          if "active" in result:
              logger.debug(f"Active status in response: {result['active']}")
          
          return CategoryResponse(
              success=True,
              message="Category created successfully",
              category_id=result.get("sys_id"),
              category_name=result.get("label"),
          )
  
      except requests.RequestException as e:
          logger.error(f"Failed to create category: {e}")
          return CategoryResponse(
              success=False,
              message=f"Failed to create category: {str(e)}",
          )

• src/servicenow_mcp/tools/knowledge_base.py:39-48 (schema)

  Pydantic model defining the input schema for the create_category tool, including required fields like title and knowledge_base.

  class CreateCategoryParams(BaseModel):
      """Parameters for creating a category in a knowledge base."""
  
      title: str = Field(..., description="Title of the category")
      description: Optional[str] = Field(None, description="Description of the category")
      knowledge_base: str = Field(..., description="The knowledge base to create the category in")
      parent_category: Optional[str] = Field(None, description="Parent category (if creating a subcategory). Sys_id refering to the parent category or sys_id of the parent table.")
      parent_table: Optional[str] = Field(None, description="Parent table (if creating a subcategory). Sys_id refering to the table where the parent category is defined.")
      active: bool = Field(True, description="Whether the category is active")

• src/servicenow_mcp/utils/tool_utils.py:722-728 (registration)

  Tool registration entry in the tool_definitions dictionary, mapping 'create_category' to its aliased handler, schema, description, and serialization hint.

  "create_category": (
      create_kb_category_tool_impl,  # Use passed function
      CreateKBCategoryParams,
      str,  # Expects JSON string
      "Create a new category in a knowledge base",
      "json_dict",  # Tool returns Pydantic model
  ),

• src/servicenow_mcp/server.py:18-20 (registration)

  Import of the create_category handler aliased as create_kb_category_tool, which is passed to get_tool_definitions for registration.

  from servicenow_mcp.tools.knowledge_base import (
      create_category as create_kb_category_tool,
  )

• src/servicenow_mcp/utils/tool_utils.py:151-152 (schema)

  Alias for the CreateCategoryParams schema used in tool registration as CreateKBCategoryParams.

      CreateCategoryParams as CreateKBCategoryParams,  # Aliased
  )