delegate-sf-mcp 0.2.0

package/src/tools/auth.js

@@ -0,0 +1,190 @@
+import { TokenManager } from '../auth/token-manager.js';
+import { FileStorageManager } from '../auth/file-storage.js';
+
+export const reauth = {
+  name: 'salesforce_auth',
+  description: 'Authenticate with Salesforce. Automatically detects if authentication is needed and handles OAuth flow. Call this tool if any Salesforce operations fail due to authentication issues.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      force: {
+        type: 'boolean',
+        description: 'Force re-authentication even if current tokens appear valid',
+        default: false
+      }
+    },
+    additionalProperties: false
+  }
+};
+
+export async function handleReauth(args) {
+  const { force = false } = args;
+
+  try {
+    // Get stored credentials
+    const fileStorage = new FileStorageManager();
+    const credentials = await fileStorage.getCredentials();
+
+    // Check if we have existing tokens even without credentials
+    if (!credentials) {
+      const tokens = await fileStorage.getTokens();
+      if (tokens && tokens.access_token && tokens.refresh_token) {
+        // We have tokens but no credentials, try to use tokens directly
+        const tokenManager = new TokenManager(null, null, tokens.instance_url);
+        tokenManager.currentTokens = tokens;
+        
+        // Test if tokens are still valid
+        const testResult = await tokenManager.testTokens();
+        if (testResult.valid) {
+          return {
+            success: true,
+            message: 'Already authenticated with valid tokens',
+            details: {
+              authenticated: true,
+              instanceUrl: tokens.instance_url,
+              storedAt: tokens.stored_at
+            },
+            nextSteps: [
+              'Your MCP Salesforce tools should now work normally',
+              'Tokens are stored securely in your home directory with 600 permissions',
+              'They will auto-refresh before expiration'
+            ]
+          };
+        }
+      }
+      
+      return {
+        success: false,
+        error: 'No Salesforce credentials found. Please run the salesforce_setup tool first to configure your credentials.',
+        details: {
+          setupRequired: true,
+          requiredCredentials: ['clientId', 'clientSecret', 'instanceUrl']
+        }
+      };
+    }
+
+    const tokenManager = new TokenManager(
+      credentials.clientId,
+      credentials.clientSecret,
+      credentials.instanceUrl
+    );
+
+    // Check current token status if not forcing
+    if (!force) {
+      await tokenManager.initialize();
+      const tokenInfo = tokenManager.getTokenInfo();
+      
+      if (tokenInfo.authenticated) {
+        // Test if tokens are actually working
+        const testResult = await tokenManager.testTokens();
+        if (testResult.valid) {
+          return {
+            success: true,
+            message: 'Current tokens are still valid. Use force=true to re-authenticate anyway.',
+            tokenInfo: {
+              authenticated: true,
+              expiresInMinutes: tokenInfo.expires_in_minutes,
+              instanceUrl: tokenInfo.instance_url
+            }
+          };
+        }
+      }
+    }
+
+    // Clear existing tokens if forcing or if they're invalid
+    await tokenManager.clearTokens();
+
+    // Start OAuth flow
+    const tokens = await tokenManager.authenticateWithOAuth();
+
+    // Verify the new tokens work
+    const testResult = await tokenManager.testTokens();
+    
+    if (!testResult.valid) {
+      return {
+        success: false,
+        error: 'Authentication completed but token validation failed',
+        details: testResult
+      };
+    }
+
+    const tokenInfo = tokenManager.getTokenInfo();
+
+    return {
+      success: true,
+      message: 'Successfully authenticated with Salesforce! New tokens have been stored securely.',
+      authenticationFlow: 'OAuth completed successfully',
+      tokenInfo: {
+        authenticated: true,
+        instanceUrl: tokenInfo.instance_url,
+        expiresInMinutes: tokenInfo.expires_in_minutes,
+        storedAt: tokenInfo.stored_at
+      },
+      nextSteps: [
+        'Your MCP Salesforce tools should now work normally',
+        'Tokens are stored securely in your home directory with 600 permissions',
+        'They will auto-refresh before expiration'
+      ]
+    };
+
+  } catch (error) {
+    // Handle specific error types
+    if (error.message.includes('OAuth flow timed out')) {
+      return {
+        success: false,
+        error: 'Authentication timed out after 5 minutes',
+        details: {
+          reason: 'User did not complete OAuth flow in browser',
+          suggestion: 'Please try again and complete the authentication in your browser quickly'
+        }
+      };
+    }
+
+    if (error.message.includes('User denied')) {
+      return {
+        success: false,
+        error: 'Authentication was denied by user',
+        details: {
+          reason: 'User cancelled or denied the OAuth authorization',
+          suggestion: 'Please try again and accept the OAuth authorization'
+        }
+      };
+    }
+
+    if (error.message.includes('invalid_client')) {
+      return {
+        success: false,
+        error: 'Invalid Salesforce Connected App credentials',
+        details: {
+          reason: 'Client ID or Client Secret is incorrect',
+          suggestion: 'Please verify your Client ID and Client Secret in ~/.mcp-salesforce.json configuration'
+        }
+      };
+    }
+
+    if (error.message.includes('EADDRINUSE')) {
+      return {
+        success: false,
+        error: 'Cannot start OAuth callback server - port conflict',
+        details: {
+          reason: 'OAuth callback port is already in use',
+          suggestion: 'Please close any other applications using ports 8080-9000 and try again'
+        }
+      };
+    }
+
+    return {
+      success: false,
+      error: `Authentication failed: ${error.message}`,
+      details: {
+        errorType: error.constructor.name,
+        troubleshooting: [
+          'Verify your Salesforce Connected App configuration',
+          'Check that callback URLs include http://localhost:8080/callback',
+          'Ensure your Salesforce credentials are correct in MCP config',
+          'Try running with force=true parameter'
+        ]
+      }
+    };
+  }
+}

package/src/tools/backup.js

@@ -0,0 +1,486 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { SalesforceBackupManager } from '../backup/manager.js';
+import { debug as logger } from '../utils/debug.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Salesforce Backup MCP Tool
+ * 
+ * Creates comprehensive backups of Salesforce data including all file attachments
+ * from ContentDocument/ContentVersion, Attachments, and Documents
+ */
+export async function handleSalesforceBackup(args, client) {
+  const {
+    backup_type = 'incremental',
+    include_files = true,
+    include_attachments = true,
+    include_documents = true,
+    objects_filter = [],
+    since_date = null,
+    compression = false,
+    parallel_downloads = 5
+  } = args;
+
+  // Resolve backup directory relative to project root, not current working directory
+  const projectRoot = path.resolve(__dirname, '../..');
+  const output_directory = path.join(projectRoot, 'backups');
+
+  try {
+    // Ensure backup directory exists
+    await fs.mkdir(output_directory, { recursive: true });
+    
+    logger.log(`🗄️ Starting Salesforce ${backup_type} backup...`);
+    
+    // Validate parameters
+    const validBackupTypes = ['full', 'incremental', 'files_only'];
+    if (!validBackupTypes.includes(backup_type)) {
+      throw new Error(`Invalid backup_type. Must be one of: ${validBackupTypes.join(', ')}`);
+    }
+    
+    if (parallel_downloads < 1 || parallel_downloads > 10) {
+      throw new Error('parallel_downloads must be between 1 and 10');
+    }
+    
+    // Parse since_date if provided
+    let parsedSinceDate = null;
+    if (since_date) {
+      try {
+        parsedSinceDate = new Date(since_date).toISOString();
+      } catch (error) {
+        throw new Error(`Invalid since_date format. Use ISO format: YYYY-MM-DDTHH:mm:ss.sssZ`);
+      }
+    }
+    
+    // Create backup manager with options
+    const backupManager = new SalesforceBackupManager(client, {
+      outputDirectory: output_directory,
+      includeFiles: include_files,
+      includeAttachments: include_attachments,
+      includeDocuments: include_documents,
+      compression: compression,
+      parallelDownloads: parallel_downloads,
+      objectsFilter: objects_filter
+    });
+    
+    // Execute async backup - returns immediately
+    const jobResult = await backupManager.startAsyncBackup(backup_type, parsedSinceDate);
+    
+    // Return immediate response with job information
+    let successMessage = `🚀 **Salesforce ${backup_type} backup started successfully!**\n\n`;
+    successMessage += `📋 **Job ID**: \`${jobResult.jobId}\`\n`;
+    successMessage += `📁 **Backup Location**: \`${jobResult.backupDirectory}\`\n`;
+    successMessage += `⚡ **Status**: ${jobResult.status} - Running in background\n\n`;
+    successMessage += `ℹ️ **Monitor Progress**: Use the \`salesforce_backup_status\` tool to check job progress\n`;
+    successMessage += `📊 **View All Jobs**: Use \`salesforce_backup_status\` without parameters to see all jobs\n\n`;
+    
+    successMessage += `🔄 **What happens next?**\n`;
+    successMessage += `- The backup is now running in the background\n`;
+    successMessage += `- You can continue using other tools immediately\n`;
+    successMessage += `- Check progress anytime with \`salesforce_backup_status\`\n`;
+    successMessage += `- You'll find the completed backup in the specified directory\n\n`;
+    
+    successMessage += `📁 **Expected Directory Structure**:\n`;
+    successMessage += `\`\`\`\n`;
+    successMessage += `${path.basename(jobResult.backupDirectory)}/\n`;
+    successMessage += `├── metadata/           # Schemas and manifest\n`;
+    successMessage += `├── data/               # Object records (JSON)\n`;
+    successMessage += `├── files/\n`;
+    successMessage += `│   ├── content-versions/  # Modern files\n`;
+    successMessage += `│   ├── attachments/       # Legacy attachments\n`;
+    successMessage += `│   └── documents/         # Document objects\n`;
+    successMessage += `└── logs/               # Backup logs\n`;
+    successMessage += `\`\`\`\n\n`;
+    
+    // Add next steps suggestions
+    successMessage += `🔄 **Next Steps**:\n`;
+    successMessage += `- Monitor progress: Use \`salesforce_backup_status ${jobResult.jobId}\` for detailed status\n`;
+    successMessage += `- Check all jobs: Use \`salesforce_backup_status\` to see all running/completed jobs\n`;
+    
+    if (backup_type === 'full') {
+      successMessage += `- Schedule incremental backups using \`since_date\` parameter\n`;
+    }
+    
+    if (compression) {
+      successMessage += `- Archive will be created with compression enabled\n`;
+    }
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: successMessage
+        }
+      ]
+    };
+    
+  } catch (error) {
+    let errorMessage = `❌ **Salesforce backup failed**\n\n`;
+    errorMessage += `**Error**: ${error.message}\n\n`;
+    
+    errorMessage += `🔧 **Troubleshooting**:\n`;
+    
+    if (error.message.includes('Authentication')) {
+      errorMessage += `- Run \`salesforce_auth\` to refresh your authentication\n`;
+    }
+    
+    if (error.message.includes('permission') || error.message.includes('access')) {
+      errorMessage += `- Check your Salesforce user permissions for objects and files\n`;
+      errorMessage += `- Ensure you have \`View All Data\` or appropriate object permissions\n`;
+    }
+    
+    if (error.message.includes('API')) {
+      errorMessage += `- Check your Salesforce API limits in Setup > System Overview\n`;
+      errorMessage += `- Consider reducing \`parallel_downloads\` parameter\n`;
+    }
+    
+    if (error.message.includes('since_date')) {
+      errorMessage += `- Use ISO date format: \`2024-01-15T10:30:00.000Z\`\n`;
+      errorMessage += `- Check that the date is not in the future\n`;
+    }
+    
+    errorMessage += `\n💡 **Suggestions**:\n`;
+    errorMessage += `- Try a smaller backup first with \`backup_type: "files_only"\`\n`;
+    errorMessage += `- Use \`objects_filter\` to backup specific objects only\n`;
+    errorMessage += `- Check available disk space\n`;
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: errorMessage
+        }
+      ]
+    };
+  }
+}
+
+/**
+ * Salesforce Backup List MCP Tool
+ * 
+ * Lists available backups and their information
+ */
+export async function handleSalesforceBackupList(args) {
+  // Resolve backup directory relative to project root, not current working directory
+  const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  const backup_directory = path.join(projectRoot, 'backups');
+  
+  try {
+    // Check if backup directory exists
+    try {
+      await fs.access(backup_directory);
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📁 No backups found.\n\nCreate your first backup using the \`salesforce_backup\` tool.`
+          }
+        ]
+      };
+    }
+    
+    // Read backup directory
+    const entries = await fs.readdir(backup_directory, { withFileTypes: true });
+    const backupDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name.startsWith('salesforce-backup-'))
+      .sort((a, b) => b.name.localeCompare(a.name)); // Most recent first
+    
+    if (backupDirs.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📁 No Salesforce backups found.\n\nCreate your first backup using the \`salesforce_backup\` tool.`
+          }
+        ]
+      };
+    }
+    
+    let response = `📋 **Available Salesforce Backups** (${backupDirs.length} found)\n\n`;
+    
+    // Analyze each backup
+    for (const [index, backupDir] of backupDirs.slice(0, 10).entries()) { // Show max 10
+      const backupPath = path.join(backup_directory, backupDir.name);
+      const manifestPath = path.join(backupPath, 'backup-manifest.json');
+      
+      try {
+        const manifestData = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestData);
+        
+        const backupInfo = manifest.backupInfo;
+        const stats = manifest.downloadStats || {};
+        const totalFiles = (stats.contentVersions || 0) + (stats.attachments || 0) + (stats.documents || 0);
+        const sizeMB = Math.round((stats.totalBytes || 0) / (1024 * 1024) * 100) / 100;
+        
+        response += `**${index + 1}. ${backupDir.name}**\n`;
+        response += `   📅 Date: ${new Date(backupInfo.timestamp).toLocaleString()}\n`;
+        response += `   ⏱️ Duration: ${backupInfo.duration} seconds\n`;
+        response += `   📦 Files: ${totalFiles} (${sizeMB} MB)\n`;
+        response += `   🏢 Instance: ${backupInfo.salesforceInstance}\n`;
+        response += `   📁 Path: \`${backupPath}\`\n\n`;
+        
+      } catch (error) {
+        response += `**${index + 1}. ${backupDir.name}**\n`;
+        response += `   ⚠️ Manifest not found or corrupted\n`;
+        response += `   📁 Path: \`${backupPath}\`\n\n`;
+      }
+    }
+    
+    if (backupDirs.length > 10) {
+      response += `... and ${backupDirs.length - 10} more backups\n\n`;
+    }
+    
+    response += `🔧 **Management**:\n`;
+    response += `- View backup details: Check \`backup-manifest.json\` in each directory\n`;
+    response += `- Clean old backups: Manually delete directories you no longer need\n`;
+    response += `- Restore from backup: Use the data files to recreate records\n`;
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: response
+        }
+      ]
+    };
+    
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ **Failed to list backups**: ${error.message}\n\nPlease check your backup directory access.`
+        }
+      ]
+    };
+  }
+}
+
+/**
+ * Salesforce Backup Status MCP Tool
+ * 
+ * Check the status of backup jobs (running, completed, failed)
+ */
+export async function handleSalesforceBackupStatus(args, client) {
+  const { job_id = null } = args;
+
+  // Resolve backup directory relative to project root
+  const projectRoot = path.resolve(__dirname, '../..');
+  const backupDirectory = path.join(projectRoot, 'backups');
+
+  try {
+    // Ensure backup directory exists
+    await fs.mkdir(backupDirectory, { recursive: true });
+
+    // Create backup manager to access status methods
+    const backupManager = new SalesforceBackupManager(client, {
+      outputDirectory: backupDirectory
+    });
+
+    if (job_id) {
+      // Get status of specific job
+      const jobStatus = await backupManager.getBackupJobStatus(job_id);
+      
+      if (!jobStatus) {
+        return {
+          content: [{
+            type: "text",
+            text: `❌ **Job not found**: No backup job found with ID \`${job_id}\`\n\nUse \`salesforce_backup_status\` without parameters to see all jobs.`
+          }]
+        };
+      }
+
+      // Format single job status
+      let statusMessage = `📋 **Backup Job Status**\n\n`;
+      statusMessage += `🆔 **Job ID**: \`${jobStatus.jobId}\`\n`;
+      statusMessage += `⚡ **Status**: ${getStatusEmoji(jobStatus.status)} ${jobStatus.status.toUpperCase()}\n`;
+      statusMessage += `📅 **Started**: ${new Date(jobStatus.startTime).toLocaleString()}\n`;
+      
+      if (jobStatus.endTime) {
+        statusMessage += `🏁 **Completed**: ${new Date(jobStatus.endTime).toLocaleString()}\n`;
+      }
+      
+      statusMessage += `📁 **Backup Directory**: \`${jobStatus.backupDirectory}\`\n`;
+      statusMessage += `📊 **Progress**: ${jobStatus.progress}%\n`;
+      statusMessage += `💬 **Message**: ${jobStatus.message}\n`;
+      
+      if (jobStatus.result) {
+        const stats = jobStatus.result.stats;
+        const totalFiles = stats.contentVersions + stats.attachments + stats.documents;
+        const sizeMB = Math.round(stats.totalBytes / (1024 * 1024) * 100) / 100;
+        
+        statusMessage += `\n📊 **Backup Results**:\n`;
+        statusMessage += `- ⏱️ **Duration**: ${jobStatus.result.duration} seconds\n`;
+        statusMessage += `- 📄 **ContentVersion files**: ${stats.contentVersions}\n`;
+        statusMessage += `- 📎 **Attachment files**: ${stats.attachments}\n`;
+        statusMessage += `- 📋 **Document files**: ${stats.documents}\n`;
+        statusMessage += `- 📦 **Total files**: ${totalFiles}\n`;
+        statusMessage += `- 💾 **Total size**: ${sizeMB} MB\n`;
+        
+        if (stats.errors > 0) {
+          statusMessage += `- ⚠️ **Errors**: ${stats.errors} failed downloads\n`;
+        }
+      }
+      
+      if (jobStatus.error) {
+        statusMessage += `\n❌ **Error**: ${jobStatus.error}\n`;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: statusMessage
+        }]
+      };
+
+    } else {
+      // Get status of all jobs
+      const allJobs = await backupManager.getBackupJobStatuses();
+      
+      if (allJobs.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: `📋 **No backup jobs found**\n\nNo backup jobs have been started yet. Use the \`salesforce_backup\` tool to start a backup.`
+          }]
+        };
+      }
+
+      // Format all jobs status
+      let statusMessage = `📋 **All Backup Jobs** (${allJobs.length} total)\n\n`;
+      
+      allJobs.forEach((job, index) => {
+        statusMessage += `**${index + 1}. ${job.jobId}**\n`;
+        statusMessage += `   ${getStatusEmoji(job.status)} Status: ${job.status.toUpperCase()}\n`;
+        statusMessage += `   📅 Started: ${new Date(job.startTime).toLocaleString()}\n`;
+        statusMessage += `   📊 Progress: ${job.progress}%\n`;
+        statusMessage += `   💬 ${job.message}\n`;
+        
+        if (job.endTime) {
+          statusMessage += `   🏁 Completed: ${new Date(job.endTime).toLocaleString()}\n`;
+        }
+        
+        if (job.error) {
+          statusMessage += `   ❌ Error: ${job.error}\n`;
+        }
+        
+        statusMessage += `\n`;
+      });
+      
+      statusMessage += `ℹ️ **Tip**: Use \`salesforce_backup_status\` with a specific \`job_id\` to get detailed information about a single job.`;
+
+      return {
+        content: [{
+          type: "text",
+          text: statusMessage
+        }]
+      };
+    }
+
+  } catch (error) {
+    logger.log('Backup status error:', error);
+    
+    return {
+      content: [{
+        type: "text",
+        text: `❌ **Error checking backup status**: ${error.message}\n\nPlease check that the backup system is properly configured.`
+      }]
+    };
+  }
+}
+
+/**
+ * Helper function to get status emoji
+ */
+function getStatusEmoji(status) {
+  const emojis = {
+    'starting': '🚀',
+    'running': '⚡',
+    'completed': '✅',
+    'failed': '❌'
+  };
+  return emojis[status] || '❓';
+}
+
+export const BACKUP_TOOLS = {
+  salesforce_backup: {
+    name: "salesforce_backup",
+    description: "Start comprehensive backups of Salesforce data including all file attachments. Runs asynchronously in background - returns immediately with job ID. Check progress with salesforce_backup_status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        backup_type: {
+          type: "string",
+          enum: ["full", "incremental", "files_only"],
+          description: "Type of backup to perform: 'full' backs up everything, 'incremental' backs up changes since a date, 'files_only' backs up just attachments",
+          default: "incremental"
+        },
+        include_files: {
+          type: "boolean",
+          description: "Include modern Files (ContentDocument/ContentVersion) in backup",
+          default: true
+        },
+        include_attachments: {
+          type: "boolean", 
+          description: "Include legacy Attachment files in backup",
+          default: true
+        },
+        include_documents: {
+          type: "boolean",
+          description: "Include Document object files in backup", 
+          default: true
+        },
+        objects_filter: {
+          type: "array",
+          items: { type: "string" },
+          description: "Specific objects to backup (empty array = all objects). Example: ['Account', 'Contact', 'CustomObject__c']",
+          default: []
+        },
+        since_date: {
+          type: "string",
+          description: "ISO date for incremental backup - only backup records modified after this date. Format: YYYY-MM-DDTHH:mm:ss.sssZ",
+          default: null
+        },
+        compression: {
+          type: "boolean",
+          description: "Compress backup files with gzip to save space",
+          default: false
+        },
+        parallel_downloads: {
+          type: "number",
+          description: "Number of parallel file downloads (1-10). Higher values = faster but more API usage",
+          default: 5,
+          minimum: 1,
+          maximum: 10
+        }
+      }
+    }
+  },
+  
+  salesforce_backup_list: {
+    name: "salesforce_backup_list",
+    description: "List all available Salesforce backups with their details including timestamp, duration, file counts, and sizes",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  
+  salesforce_backup_status: {
+    name: "salesforce_backup_status",
+    description: "Check the status of Salesforce backup jobs. Monitor running, completed, or failed backup operations. Use without parameters to see all jobs, or specify a job_id to get detailed status of a specific backup job.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: {
+          type: "string",
+          description: "Optional: Specific backup job ID to check status for. If not provided, shows status of all backup jobs."
+        }
+      }
+    }
+  }
+};