Knowledge Base MCP Server

Instructions

Implementation Reference

• src/knowledge_base_mcp/server.py:325-342 (handler)

  The handler function that executes the create_category tool. It extracts arguments, calls the storage layer to create the category, handles errors, and returns formatted TextContent.

  async def handle_create_category(arguments: dict) -> list[TextContent]:
      """Handle create_category tool call."""
      try:
          category_path = arguments["category_path"]
          description = arguments.get("description")
  
          result = storage.create_category(
              category_path=category_path,
              description=description,
              create_parents=True
          )
  
          return [TextContent(type="text", text=result)]
      except (CategoryExistsError, InvalidPathError, StorageError) as e:
          return [TextContent(type="text", text=str(e))]
      except Exception as e:
          return [TextContent(type="text", text=f"❌ Error: {str(e)}")]

• src/knowledge_base_mcp/server.py:46-63 (registration)

  The tool registration in list_tools(), defining the name, description, and input schema for create_category.

  Tool(
      name="create_category",
      description="Create a new category or subcategory in the knowledge base",
      inputSchema={
          "type": "object",
          "properties": {
              "category_path": {
                  "type": "string",
                  "description": "Category path (e.g., 'work', 'work/clients', 'personal/spiritual/devotionals'). Use forward slashes for nested categories.",
              },
              "description": {
                  "type": "string",
                  "description": "Optional description for the category",
              },
          },
          "required": ["category_path"],
      },
  ),

• src/knowledge_base_mcp/server.py:49-62 (schema)

  The inputSchema defining the parameters for the create_category tool: required category_path and optional description.

  inputSchema={
      "type": "object",
      "properties": {
          "category_path": {
              "type": "string",
              "description": "Category path (e.g., 'work', 'work/clients', 'personal/spiritual/devotionals'). Use forward slashes for nested categories.",
          },
          "description": {
              "type": "string",
              "description": "Optional description for the category",
          },
      },
      "required": ["category_path"],
  },

• src/knowledge_base_mcp/storage.py:289-348 (helper)

  The core storage method that performs the actual category creation: validates path, creates directory, saves optional metadata, and returns success message.

  def create_category(
      self,
      category_path: str,
      description: Optional[str] = None,
      create_parents: bool = True
  ) -> str:
      """
      Create a new category.
  
      Args:
          category_path: Category path (e.g., "work/clients/acme")
          description: Optional description for the category
          create_parents: If True, create parent directories as needed
  
      Returns:
          Success message
  
      Raises:
          CategoryExistsError: If category already exists
          InvalidPathError: If path is invalid
          StorageError: If creation fails
      """
      # Normalize and validate path
      normalized = normalize_path(category_path)
      if not normalized:
          raise InvalidPathError("Category path cannot be empty")
  
      is_valid, error_msg = validate_path(normalized)
      if not is_valid:
          raise InvalidPathError(error_msg)
  
      # Check if already exists
      if self._category_exists(normalized):
          raise CategoryExistsError(
              f"❌ Error: Category '{normalized}' already exists\n"
              f"💡 Tip: Use rename_category to rename it"
          )
  
      # Create the directory
      cat_path = self._get_category_path(normalized)
      try:
          cat_path.mkdir(parents=create_parents, exist_ok=False)
      except FileExistsError:
          raise CategoryExistsError(f"Category '{normalized}' already exists")
      except FileNotFoundError:
          parent = get_parent_path(normalized)
          raise StorageError(
              f"❌ Error: Parent category '{parent}' does not exist\n"
              f"💡 Tip: Create parent first or use create_parents=True"
          )
      except Exception as e:
          raise StorageError(f"Failed to create category '{normalized}': {e}")
  
      # Save metadata if description provided
      if description:
          metadata = CategoryMetadata(description=description)
          self._save_category_metadata(normalized, metadata)
  
      return f"✓ Category '{normalized}' created successfully"