ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/knowledge_base.py:198-322 (handler)

  The handler function that implements the list_knowledge_bases tool by querying the ServiceNow kb_knowledge_base table API with pagination and filters, transforming the response into a structured dictionary.
  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 limit, offset, active filter, and 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:714-720 (registration)

  Registration of the list_knowledge_bases tool in the get_tool_definitions dictionary, mapping name to (handler, schema, return_type, description, serialization).
  "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/utils/tool_utils.py:171-172 (registration)

  Import alias for the handler function used in tool registration.
  list_knowledge_bases as list_knowledge_bases_tool, )
• src/servicenow_mcp/tools/__init__.py:55-55 (registration)

  Re-export of the list_knowledge_bases function in the tools module __init__.
  list_knowledge_bases,