Mnemosyne MCP

Instructions

Implementation Reference

• src/neem/mcp/tools/hocuspocus.py:573-631 (handler)

  The main handler function for the 'delete_folder' MCP tool. It authenticates, connects to the workspace via HocusPocus, and performs the deletion transaction using WorkspaceWriter.delete_folder.

  @server.tool(
      name="delete_folder",
      title="Delete Folder",
      description=(
          "Delete a folder from the workspace. "
          "Set cascade=true to delete all contents (subfolders, documents, artifacts). "
          "Without cascade, deletion fails if the folder has children."
      ),
  )
  async def delete_folder_tool(
      graph_id: str,
      folder_id: str,
      cascade: bool = False,
      context: Context | None = None,
  ) -> dict:
      """Delete a folder via Y.js."""
      auth = MCPAuthContext.from_context(context)
      auth.require_auth()
  
      if not graph_id or not graph_id.strip():
          raise ValueError("graph_id is required and cannot be empty")
      if not folder_id or not folder_id.strip():
          raise ValueError("folder_id is required and cannot be empty")
  
      try:
          await hp_client.connect_workspace(graph_id.strip())
  
          # Delete folder via Y.js
          await hp_client.transact_workspace(
              graph_id.strip(),
              lambda doc: WorkspaceWriter(doc).delete_folder(folder_id.strip(), cascade=cascade),
          )
  
          snapshot = hp_client.get_workspace_snapshot(graph_id.strip())
  
          result = {
              "success": True,
              "deleted": True,
              "folder_id": folder_id.strip(),
              "graph_id": graph_id.strip(),
              "cascade": cascade,
              "workspace": snapshot,
          }
          return result
  
      except ValueError as ve:
          # Cascade error - folder has children
          raise RuntimeError(str(ve))
      except Exception as e:
          logger.error(
              "Failed to delete folder",
              extra_context={
                  "graph_id": graph_id,
                  "folder_id": folder_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to delete folder: {e}")

• src/neem/hocuspocus/workspace.py:316-347 (helper)

  The core helper method in WorkspaceWriter class that implements the folder deletion logic, including optional recursive cascade deletion of children.

  def delete_folder(self, folder_id: str, cascade: bool = False) -> bool:
      """Delete a folder from workspace navigation.
  
      Args:
          folder_id: The folder ID to delete
          cascade: If True, delete all children (subfolders, artifacts, documents).
                   If False, raises ValueError if folder has children.
  
      Returns:
          True if folder was deleted, False if not found.
  
      Raises:
          ValueError: If cascade=False and folder has children.
      """
      if folder_id not in self._folders:
          return False
  
      children = self._get_children_of(folder_id)
      if children and not cascade:
          raise ValueError(
              f"Folder has {len(children)} children. Use cascade=True to delete."
          )
  
      if cascade:
          self._delete_children_recursive(folder_id)
  
      del self._folders[folder_id]
      logger.debug(
          "Deleted folder from workspace",
          extra_context={"folder_id": folder_id, "cascade": cascade},
      )
      return True

• src/neem/mcp/server/standalone_server.py:317-317 (registration)

  Registration of the hocuspocus tools module, which includes the delete_folder tool, called during MCP server setup.

  register_hocuspocus_tools(mcp_server)