Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/download-management-tools.ts:135-214 (handler)

  The primary handler function for the 'download_list' tool. Validates input arguments, retrieves active and historical downloads from both log and database systems, applies filters by status and type, sorts and paginates results, formats unified download objects, and returns a structured response with a human-readable message.

  static async handleDownloadList(args: DownloadListArgs): Promise<any> {
      try {
          const { status = 'active', type = 'all', limit = 10, offset = 0 } = args;
  
          // Validate parameters
          const validStatuses = ['active', 'completed', 'failed', 'all'];
          if (!validStatuses.includes(status)) {
              return ResponseBuilder.invalidParams(`Invalid status: ${status}. Must be one of: ${validStatuses.join(', ')}`);
          }
  
          const validTypes = ['logs', 'database', 'all'];
          if (!validTypes.includes(type)) {
              return ResponseBuilder.invalidParams(`Invalid type: ${type}. Must be one of: ${validTypes.join(', ')}`);
          }
  
          if (limit < 0 || limit > 100) {
              return ResponseBuilder.invalidParams(`Invalid limit: ${limit}. Must be between 0 and 100`);
          }
  
          if (offset < 0) {
              return ResponseBuilder.invalidParams(`Invalid offset: ${offset}. Must be >= 0`);
          }
  
          // Get downloads from both systems
          // DXP-178 FIX: Need .default for ES module default export
          const DatabaseSimpleTools = require('./database-simple-tools').default;
  
          // Get log downloads
          const logDownloads = status === 'active'
              ? downloadManager.getActiveDownloads()
              : downloadManager.getHistory(1000); // Get all history for filtering
  
          // Get database downloads
          // DXP-177: Add null check to prevent "Cannot read properties of undefined (reading 'entries')" error
          const dbDownloadsArray = DatabaseSimpleTools.backgroundDownloads
              ? Array.from(DatabaseSimpleTools.backgroundDownloads.entries() as IterableIterator<[string, any]>)
                  .map(([downloadId, download]) => ({ ...download, downloadId }))
              : [];
  
          // Apply status filter
          const filteredLogDownloads = this._filterByStatus(logDownloads, status);
          const filteredDbDownloads = this._filterByStatus(dbDownloadsArray, status);
  
          // Apply type filter
          let allDownloads: UnifiedDownload[] = [];
          if (type === 'all' || type === 'logs') {
              allDownloads.push(...filteredLogDownloads.map(d => this._formatLogDownload(d)));
          }
          if (type === 'all' || type === 'database') {
              allDownloads.push(...filteredDbDownloads.map(d => this._formatDatabaseDownload(d)));
          }
  
          // Sort by startTime (most recent first)
          allDownloads.sort((a, b) => b.startTime - a.startTime);
  
          // Apply pagination (only for non-active status)
          let paginatedDownloads = allDownloads;
          let hasMore = false;
          if (status !== 'active' && limit > 0) {
              paginatedDownloads = allDownloads.slice(offset, offset + limit);
              hasMore = allDownloads.length > offset + limit;
          }
  
          // Build message
          const message = this._buildDownloadListMessage(paginatedDownloads, status, type, hasMore, offset, limit);
  
          // Build structured data
          const structuredData = {
              downloads: paginatedDownloads,
              totalCount: paginatedDownloads.length,
              hasMore: hasMore
          };
  
          return ResponseBuilder.successWithStructuredData(structuredData, message);
  
      } catch (error: any) {
          OutputLogger.error(`Download list error: ${error}`);
          return ResponseBuilder.internalError('Failed to list downloads', error.message);
      }
  }

• lib/tools/download-management-tools.ts:14-19 (schema)

  TypeScript interface defining the input arguments for the download_list tool, including optional parameters for filtering by status, type, pagination limit, and offset.

  interface DownloadListArgs {
      status?: 'active' | 'completed' | 'failed' | 'all';
      type?: 'logs' | 'database' | 'all';
      limit?: number;
      offset?: number;
  }

• lib/tools/download-management-tools.ts:214-220 (helper)

  Supporting helper methods that assist the handler in filtering, formatting downloads from different sources (logs and database), and building the response message.

  }
  
  /**
   * Filter downloads by status
   * @private
   */
  static _filterByStatus(downloads: any[], status: string): any[] {