ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/knowledge_base.py:197-321 (handler)

  The handler function that executes the tool logic: queries the ServiceNow kb_knowledge_base table API with pagination and filters, processes the response into a structured list of knowledge bases.

  def list_knowledge_bases(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: ListKnowledgeBasesParams,
  ) -> Dict[str, Any]:
      """
      List knowledge bases with filtering options.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for listing knowledge bases.
  
      Returns:
          Dictionary with list of knowledge bases and metadata.
      """
      api_url = f"{config.api_url}/table/kb_knowledge_base"
  
      # Build query parameters
      query_params = {
          "sysparm_limit": params.limit,
          "sysparm_offset": params.offset,
          "sysparm_display_value": "true",
      }
  
      # Build query string
      query_parts = []
      if params.active is not None:
          query_parts.append(f"active={str(params.active).lower()}")
      if params.query:
          query_parts.append(f"titleLIKE{params.query}^ORdescriptionLIKE{params.query}")
  
      if query_parts:
          query_params["sysparm_query"] = "^".join(query_parts)
  
      # Make request
      try:
          response = requests.get(
              api_url,
              params=query_params,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          # Get the JSON response 
          json_response = response.json()
          
          # Safely extract the result
          if isinstance(json_response, dict) and "result" in json_response:
              result = json_response.get("result", [])
          else:
              logger.error("Unexpected response format: %s", json_response)
              return {
                  "success": False,
                  "message": "Unexpected response format",
                  "knowledge_bases": [],
                  "count": 0,
                  "limit": params.limit,
                  "offset": params.offset,
              }
  
          # Transform the results - create a simpler structure
          knowledge_bases = []
          
          # Handle either string or list
          if isinstance(result, list):
              for kb_item in result:
                  if not isinstance(kb_item, dict):
                      logger.warning("Skipping non-dictionary KB item: %s", kb_item)
                      continue
                      
                  # Safely extract values
                  kb_id = kb_item.get("sys_id", "")
                  title = kb_item.get("title", "")
                  description = kb_item.get("description", "")
                  
                  # Extract nested values safely
                  owner = ""
                  if isinstance(kb_item.get("owner"), dict):
                      owner = kb_item["owner"].get("display_value", "")
                  
                  managers = ""
                  if isinstance(kb_item.get("kb_managers"), dict):
                      managers = kb_item["kb_managers"].get("display_value", "")
                  
                  active = False
                  if kb_item.get("active") == "true":
                      active = True
                  
                  created = kb_item.get("sys_created_on", "")
                  updated = kb_item.get("sys_updated_on", "")
                  
                  knowledge_bases.append({
                      "id": kb_id,
                      "title": title,
                      "description": description,
                      "owner": owner,
                      "managers": managers,
                      "active": active,
                      "created": created,
                      "updated": updated,
                  })
          else:
              logger.warning("Result is not a list: %s", result)
  
          return {
              "success": True,
              "message": f"Found {len(knowledge_bases)} knowledge bases",
              "knowledge_bases": knowledge_bases,
              "count": len(knowledge_bases),
              "limit": params.limit,
              "offset": params.offset,
          }
  
      except requests.RequestException as e:
          logger.error(f"Failed to list knowledge bases: {e}")
          return {
              "success": False,
              "message": f"Failed to list knowledge bases: {str(e)}",
              "knowledge_bases": [],
              "count": 0,
              "limit": params.limit,
              "offset": params.offset,
          }

• src/servicenow_mcp/tools/knowledge_base.py:30-37 (schema)

  Pydantic model defining the input parameters for the list_knowledge_bases tool, including pagination, active filter, and search query.

  class ListKnowledgeBasesParams(BaseModel):
      """Parameters for listing knowledge bases."""
      
      limit: int = Field(10, description="Maximum number of knowledge bases to return")
      offset: int = Field(0, description="Offset for pagination")
      active: Optional[bool] = Field(None, description="Filter by active status")
      query: Optional[str] = Field(None, description="Search query for knowledge bases")

• src/servicenow_mcp/utils/tool_utils.py:668-674 (registration)

  Tool registration in the central tool_definitions dictionary used by the MCP server, specifying the handler function alias, input schema, description, and serialization method.

  "list_knowledge_bases": (
      list_knowledge_bases_tool,
      ListKnowledgeBasesParams,
      Dict[str, Any],  # Expects dict
      "List knowledge bases from ServiceNow",
      "raw_dict",  # Tool returns raw dict
  ),

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

  Import of the list_knowledge_bases handler in the tools package __init__.py, making it available for higher-level imports and registrations.

  list_knowledge_bases,