Knowledge Base MCP Server

Instructions

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",
              },
          },
      },
  ),

• src/knowledge_base_mcp/server.py:127-135 (schema)

  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",
          },
      },
  },

• src/knowledge_base_mcp/storage.py:778-839 (helper)

  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)