list_categories
Retrieve all knowledge base categories in a hierarchical tree structure to organize and navigate content effectively.
Instructions
List all categories in a hierarchical tree structure
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| parent_path | No | Optional: list only subcategories of this path |
Implementation Reference
- src/knowledge_base_mcp/server.py:597-620 (handler)The handler function that executes the list_categories tool. It extracts the optional parent_path from arguments, calls storage.get_category_hierarchy to get the category tree, formats it as a textual tree using format_tree, and returns it as TextContent.
async def handle_list_categories(arguments: dict) -> list[TextContent]: """Handle list_categories tool call.""" parent_path = arguments.get("parent_path") # Get hierarchical category structure categories = storage.get_category_hierarchy(parent_path=parent_path) if not categories: if parent_path: return [TextContent(type="text", text=f"No subcategories found in '{parent_path}/'")] else: return [TextContent(type="text", text="No categories found. Create one with create_category!")] # Format as tree if parent_path: output = f"Categories in {parent_path}/:\n\n" else: output = "Category Hierarchy:\n\n" for cat in categories: output += cat.format_tree(indent=0, show_counts=True) return [TextContent(type="text", text=output)] - src/knowledge_base_mcp/server.py:124-136 (registration)Registration of the list_categories tool in the @app.list_tools() function, including its name, description, and input schema.
Tool( name="list_categories", description="List all categories in a hierarchical tree structure", inputSchema={ "type": "object", "properties": { "parent_path": { "type": "string", "description": "Optional: list only subcategories of this path", }, }, }, ), - The input schema definition for the list_categories tool, defining an optional parent_path parameter.
inputSchema={ "type": "object", "properties": { "parent_path": { "type": "string", "description": "Optional: list only subcategories of this path", }, }, }, - Supporting helper method in KnowledgeBaseStorage that recursively builds the hierarchical structure of categories as CategoryInfo objects, used by the handler. Includes note counts, metadata, and sorting.
def get_category_hierarchy( self, parent_path: Optional[str] = None ) -> List[CategoryInfo]: """ Get hierarchical category structure. Args: parent_path: Optional parent path to list subcategories of Returns: List of CategoryInfo objects representing the category tree """ if parent_path: normalized = normalize_path(parent_path) search_path = self._get_category_path(normalized) else: search_path = self.base_path normalized = "" if not search_path.exists(): return [] categories = [] # Find all direct subdirectories for item in search_path.iterdir(): if not item.is_dir(): continue # Get relative path from base try: rel_path = item.relative_to(self.base_path) cat_path = str(rel_path) except ValueError: continue # Count notes in this category (non-recursive) note_count = self._count_notes_in_category(cat_path, recursive=False) # Load metadata metadata = self._load_category_metadata(cat_path) # Get depth depth = get_depth(cat_path) # Create CategoryInfo cat_info = CategoryInfo( name=item.name, path=cat_path, note_count=note_count, depth=depth, metadata=metadata ) # Recursively get children cat_info.children = self.get_category_hierarchy(cat_path) categories.append(cat_info) return sorted(categories, key=lambda c: c.name)