delegate-sf-mcp 0.2.0

package/src/tools/time_machine.js

@@ -0,0 +1,347 @@
+import fs from 'fs';
+import path from 'path';
+import { logger } from '../utils/debug.js';
+
+class SalesforceTimeMachine {
+  constructor(backupRootDirectory = './backups') {
+    this.backupRootDirectory = backupRootDirectory;
+  }
+
+  /**
+   * Find all available backups sorted by timestamp (newest first)
+   */
+  async getAllBackups() {
+    try {
+      if (!fs.existsSync(this.backupRootDirectory)) {
+        return [];
+      }
+
+      const items = fs.readdirSync(this.backupRootDirectory);
+      const backups = [];
+
+      for (const item of items) {
+        const itemPath = path.join(this.backupRootDirectory, item);
+        if (fs.statSync(itemPath).isDirectory() && item.startsWith('salesforce-backup-')) {
+          const manifestPath = path.join(itemPath, 'backup-manifest.json');
+          if (fs.existsSync(manifestPath)) {
+            try {
+              const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+              backups.push({
+                path: itemPath,
+                timestamp: manifest.backupInfo.timestamp,
+                date: new Date(manifest.backupInfo.timestamp),
+                manifest: manifest
+              });
+            } catch (err) {
+              logger.warn(`Could not read manifest for backup ${item}:`, err.message);
+            }
+          }
+        }
+      }
+
+      // Sort by timestamp (newest first)
+      return backups.sort((a, b) => b.date - a.date);
+    } catch (error) {
+      throw new Error(`Failed to get backups: ${error.message}`);
+    }
+  }
+
+  /**
+   * Find backup closest to a specific date
+   */
+  async getBackupAtDate(targetDate) {
+    const backups = await this.getAllBackups();
+    if (backups.length === 0) {
+      return null;
+    }
+
+    const target = new Date(targetDate);
+    
+    // Find the backup with timestamp <= target date (most recent backup before target)
+    for (const backup of backups) {
+      if (backup.date <= target) {
+        return backup;
+      }
+    }
+
+    // If no backup before target date, return the oldest backup
+    return backups[backups.length - 1];
+  }
+
+  /**
+   * Query historical data from a specific backup
+   */
+  async queryBackupData(backupPath, objectType, filters = {}) {
+    try {
+      const dataPath = path.join(backupPath, 'data', `${objectType}.json`);
+      
+      if (!fs.existsSync(dataPath)) {
+        return {
+          success: false,
+          error: `No data found for object type '${objectType}' in backup`,
+          availableObjects: this.getAvailableObjectTypes(backupPath)
+        };
+      }
+
+      const data = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+      let filteredData = data;
+
+      // Apply filters
+      if (Object.keys(filters).length > 0) {
+        filteredData = data.filter(record => {
+          return Object.entries(filters).every(([field, value]) => {
+            if (typeof value === 'string' && value.includes('*')) {
+              // Wildcard matching
+              const regex = new RegExp(value.replace(/\*/g, '.*'), 'i');
+              return regex.test(record[field]);
+            }
+            return record[field] === value;
+          });
+        });
+      }
+
+      return {
+        success: true,
+        data: filteredData,
+        count: filteredData.length,
+        backupTimestamp: this.getBackupTimestamp(backupPath),
+        objectType: objectType
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: `Failed to query backup data: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Time Machine query: Find data as it existed at a specific point in time
+   */
+  async queryAtPointInTime(targetDate, objectType, filters = {}) {
+    try {
+      const backup = await this.getBackupAtDate(targetDate);
+      
+      if (!backup) {
+        return {
+          success: false,
+          error: 'No backups found for the specified date range'
+        };
+      }
+
+      const result = await this.queryBackupData(backup.path, objectType, filters);
+      
+      if (result.success) {
+        result.snapshotDate = backup.timestamp;
+        result.message = `Data as it existed on ${backup.timestamp}`;
+      }
+
+      return result;
+    } catch (error) {
+      return {
+        success: false,
+        error: `Time Machine query failed: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Compare data between two points in time
+   */
+  async compareDataOverTime(startDate, endDate, objectType, filters = {}) {
+    try {
+      const startBackup = await this.getBackupAtDate(startDate);
+      const endBackup = await this.getBackupAtDate(endDate);
+
+      if (!startBackup || !endBackup) {
+        return {
+          success: false,
+          error: 'Could not find backups for the specified date range'
+        };
+      }
+
+      const startResult = await this.queryBackupData(startBackup.path, objectType, filters);
+      const endResult = await this.queryBackupData(endBackup.path, objectType, filters);
+
+      if (!startResult.success || !endResult.success) {
+        return {
+          success: false,
+          error: 'Failed to query data from one or both backups'
+        };
+      }
+
+      // Simple comparison - can be enhanced with more sophisticated diff logic
+      const comparison = {
+        startSnapshot: {
+          date: startBackup.timestamp,
+          count: startResult.count,
+          data: startResult.data
+        },
+        endSnapshot: {
+          date: endBackup.timestamp,
+          count: endResult.count,
+          data: endResult.data
+        },
+        changes: {
+          countDifference: endResult.count - startResult.count,
+          // Add more sophisticated change detection here
+        }
+      };
+
+      return {
+        success: true,
+        comparison: comparison,
+        objectType: objectType
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: `Data comparison failed: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Search across all backups for historical changes to a specific record
+   */
+  async getRecordHistory(recordId, objectType) {
+    try {
+      const backups = await this.getAllBackups();
+      const history = [];
+
+      for (const backup of backups) {
+        const result = await this.queryBackupData(backup.path, objectType, { Id: recordId });
+        if (result.success && result.data.length > 0) {
+          history.push({
+            timestamp: backup.timestamp,
+            data: result.data[0] // Should be only one record with specific ID
+          });
+        }
+      }
+
+      return {
+        success: true,
+        recordId: recordId,
+        objectType: objectType,
+        history: history,
+        changesCount: history.length
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: `Record history query failed: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Get available object types from a backup
+   */
+  getAvailableObjectTypes(backupPath) {
+    try {
+      const dataPath = path.join(backupPath, 'data');
+      if (!fs.existsSync(dataPath)) {
+        return [];
+      }
+
+      return fs.readdirSync(dataPath)
+        .filter(file => file.endsWith('.json'))
+        .map(file => file.replace('.json', ''));
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Get backup timestamp from manifest
+   */
+  getBackupTimestamp(backupPath) {
+    try {
+      const manifestPath = path.join(backupPath, 'backup-manifest.json');
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      return manifest.backupInfo.timestamp;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * List all available Time Machine operations
+   */
+  getAvailableOperations() {
+    return [
+      {
+        operation: 'query_at_point_in_time',
+        description: 'Query data as it existed at a specific date',
+        parameters: ['targetDate', 'objectType', 'filters (optional)']
+      },
+      {
+        operation: 'compare_over_time',
+        description: 'Compare data between two points in time',
+        parameters: ['startDate', 'endDate', 'objectType', 'filters (optional)']
+      },
+      {
+        operation: 'get_record_history',
+        description: 'Get complete history of changes for a specific record',
+        parameters: ['recordId', 'objectType']
+      },
+      {
+        operation: 'list_backups',
+        description: 'List all available backup snapshots',
+        parameters: []
+      }
+    ];
+  }
+}
+
+// MCP Tool implementations
+const TIME_MACHINE_TOOLS = [
+  {
+    name: 'salesforce_time_machine_query',
+    description: 'Query historical Salesforce data from backups using Time Machine functionality. Supports point-in-time queries, comparisons, and record history tracking.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        operation: {
+          type: 'string',
+          enum: ['query_at_point_in_time', 'compare_over_time', 'get_record_history', 'list_backups'],
+          description: 'The Time Machine operation to perform'
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Target date for point-in-time queries (ISO 8601 format)'
+        },
+        startDate: {
+          type: 'string',
+          description: 'Start date for comparison queries (ISO 8601 format)'
+        },
+        endDate: {
+          type: 'string',
+          description: 'End date for comparison queries (ISO 8601 format)'
+        },
+        objectType: {
+          type: 'string',
+          description: 'Salesforce object type to query (e.g., Account, Contact, ContentVersion)'
+        },
+        recordId: {
+          type: 'string',
+          description: 'Specific record ID for history tracking'
+        },
+        filters: {
+          type: 'object',
+          description: 'Optional filters to apply to the query (field-value pairs, supports wildcards with *)'
+        },
+        backupDirectory: {
+          type: 'string',
+          description: 'Path to backup directory (defaults to ./backups)'
+        }
+      },
+      required: ['operation']
+    }
+  }
+];
+
+export {
+  SalesforceTimeMachine,
+  TIME_MACHINE_TOOLS
+};

package/src/tools/update.js

@@ -0,0 +1,138 @@
+import { hasInstallationDocumentation, getInstallationDocumentation } from './learn.js';
+
+export const updateTool = {
+  name: "salesforce_update",
+  description: "Update an existing record in any Salesforce object. Requires the record ID and field values to update.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sobject: {
+        type: "string",
+        description: "SObject API name (e.g., 'Contact', 'Account', 'CustomObject__c')"
+      },
+      id: {
+        type: "string",
+        description: "Salesforce record ID (15 or 18 character ID)"
+      },
+      data: {
+        type: "object",
+        description: "Field values to update. Only include fields you want to change (e.g., {'Email': 'newemail@example.com', 'Phone': '555-1234'})"
+      }
+    },
+    required: ["sobject", "id", "data"]
+  }
+};
+
+export async function executeUpdate(client, args) {
+  try {
+    const { sobject, id, data } = args;
+    
+    // Check if installation has been learned for better context
+    const hasDocumentation = await hasInstallationDocumentation();
+    let contextMessage = '';
+    
+    if (!hasDocumentation) {
+      contextMessage = `⚠️ **Tip:** Use \`salesforce_learn\` to analyze all available objects and fields.\n\n`;
+    } else {
+      // Provide context about the object if available
+      const documentation = await getInstallationDocumentation();
+      const objectInfo = documentation.objects[sobject];
+      if (objectInfo && !objectInfo.error) {
+        // Check for read-only fields in the provided data
+        const readOnlyFieldsInData = Object.keys(data).filter(fieldName => {
+          const field = objectInfo.fields[fieldName];
+          return field && field.writability && field.writability.read_only;
+        });
+        
+        const nonUpdateableFields = Object.keys(data).filter(fieldName => {
+          const field = objectInfo.fields[fieldName];
+          return field && !field.updateable;
+        });
+        
+        if (readOnlyFieldsInData.length > 0) {
+          const readOnlyWarnings = readOnlyFieldsInData.map(fieldName => {
+            const field = objectInfo.fields[fieldName];
+            const reason = field.writability.system_managed ? 'System Managed' :
+                          field.writability.formula ? 'Formula Field' :
+                          field.writability.calculated ? 'Calculated Field' :
+                          field.writability.rollup_summary ? 'Rollup Summary' :
+                          field.writability.auto_number ? 'Auto Number' : 'Read-Only';
+            return `- ${field.label || fieldName} (${fieldName}) - ${reason}`;
+          }).join('\n');
+          
+          contextMessage += `⚠️ **Warning: Read-only fields detected in update data:**\n${readOnlyWarnings}\n\n` +
+                           `These fields cannot be updated and will be ignored by Salesforce.\n\n`;
+        } else if (nonUpdateableFields.length > 0) {
+          const nonUpdateableWarnings = nonUpdateableFields.map(fieldName => {
+            const field = objectInfo.fields[fieldName];
+            return `- ${field.label || fieldName} (${fieldName})`;
+          }).join('\n');
+          
+          contextMessage += `⚠️ **Warning: Non-updateable fields detected:**\n${nonUpdateableWarnings}\n\n`;
+        }
+      }
+    }
+    
+    if (!sobject || typeof sobject !== 'string') {
+      throw new Error('sobject parameter is required and must be a string');
+    }
+
+    if (!id || typeof id !== 'string') {
+      throw new Error('id parameter is required and must be a string');
+    }
+
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new Error('data parameter is required and must be an object');
+    }
+
+    // Validate data is not empty
+    if (Object.keys(data).length === 0) {
+      throw new Error('data object cannot be empty - specify at least one field to update');
+    }
+
+    // Validate ID format (basic check)
+    if (id.length !== 15 && id.length !== 18) {
+      throw new Error('Invalid Salesforce ID format. ID must be 15 or 18 characters long.');
+    }
+
+    // Remove Id from data if accidentally included
+    const updateData = { ...data };
+    delete updateData.Id;
+    delete updateData.id;
+
+    const result = await client.update(sobject, id, updateData);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${contextMessage}✅ Successfully updated ${sobject} record!\n\n` +
+                `Record ID: ${result.id}\n` +
+                `Object Type: ${result.sobject}\n\n` +
+                `Updated fields:\n${JSON.stringify(updateData, null, 2)}\n\n` +
+                `You can view the updated record using:\n` +
+                `SELECT Id, * FROM ${sobject} WHERE Id = '${result.id}'`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ Failed to update ${args.sobject || 'record'}: ${error.message}\n\n` +
+                `Common issues:\n` +
+                `- Record not found (check the ID)\n` +
+                `- Invalid field names (use API names, not labels)\n` +
+                `- Read-only fields (some fields cannot be updated)\n` +
+                `- Invalid data types or formats\n` +
+                `- Insufficient permissions\n` +
+                `- Validation rule failures\n\n` +
+                `Record ID provided: ${args.id}\n` +
+                `Tip: Use salesforce_describe to check which fields are updateable`
+        }
+      ],
+      isError: true
+    };
+  }
+}

package/src/tools.js

@@ -0,0 +1,214 @@
+/**
+ * tools.js — Tool handlers for the Delegate SF MCP
+ */
+
+import { query, search, describe, createRecord, updateRecord } from './sf-client.js';
+
+// ── 1. SOQL Query ─────────────────────────────────────────────────────────────
+
+export async function handleQuery({ soql }) {
+  if (!soql) throw new Error('soql is required');
+
+  const records = await query(soql);
+
+  if (records.length === 0) return 'No records found.';
+
+  return JSON.stringify(records, null, 2);
+}
+
+// ── 2. Get Record ─────────────────────────────────────────────────────────────
+
+export async function handleGetRecord({ object_type, record_id, fields }) {
+  if (!object_type || !record_id) throw new Error('object_type and record_id are required');
+
+  const fieldList = fields?.length ? fields.join(',') : 'Id,Name';
+  const soql = `SELECT ${fieldList} FROM ${object_type} WHERE Id = '${record_id}' LIMIT 1`;
+  const records = await query(soql);
+
+  if (records.length === 0) return `No ${object_type} found with Id: ${record_id}`;
+  return JSON.stringify(records[0], null, 2);
+}
+
+// ── 3. SOSL Search ────────────────────────────────────────────────────────────
+
+export async function handleSearch({ search_term, object_types, fields }) {
+  if (!search_term) throw new Error('search_term is required');
+
+  const objects = (object_types || ['Contact', 'Account', 'Lead', 'Opportunity'])
+    .map(obj => {
+      const f = fields || ['Id', 'Name'];
+      return `${obj}(${f.join(',')})`;
+    })
+    .join(', ');
+
+  const sosl = `FIND {${search_term.replace(/[?&|!{}[\]()^~*:\\"'+-]/g, '\\$&')}} IN ALL FIELDS RETURNING ${objects}`;
+
+  const records = await search(sosl);
+
+  if (records.length === 0) return `No records found matching: ${search_term}`;
+  return JSON.stringify(records, null, 2);
+}
+
+// ── 4. Describe Object ────────────────────────────────────────────────────────
+
+export async function handleDescribe({ object_type }) {
+  if (!object_type) throw new Error('object_type is required');
+
+  const meta = await describe(object_type);
+
+  // Return only useful subset — full describe is massive
+  const summary = {
+    name: meta.name,
+    label: meta.label,
+    fields: meta.fields.map(f => ({
+      name: f.name,
+      label: f.label,
+      type: f.type,
+      required: !f.nillable && !f.defaultedOnCreate,
+      updateable: f.updateable,
+      picklistValues: f.picklistValues?.filter(v => v.active).map(v => v.value) || [],
+    })),
+  };
+
+  return JSON.stringify(summary, null, 2);
+}
+
+// ── 5. Create Record ──────────────────────────────────────────────────────────
+
+export async function handleCreate({ object_type, fields }) {
+  if (!object_type || !fields) throw new Error('object_type and fields are required');
+
+  const result = await createRecord(object_type, fields);
+  if (!result.success) throw new Error(result.errors?.map(e => e.message).join('; ') || 'Create failed');
+
+  return JSON.stringify({ success: true, id: result.id, object: object_type });
+}
+
+// ── 6. Update Record ──────────────────────────────────────────────────────────
+
+export async function handleUpdate({ object_type, record_id, fields }) {
+  if (!object_type || !record_id || !fields) throw new Error('object_type, record_id, and fields are required');
+
+  const result = await updateRecord(object_type, record_id, fields);
+  if (!result.success) throw new Error(result.errors?.map(e => e.message).join('; ') || 'Update failed');
+
+  return JSON.stringify({ success: true, id: record_id, updated_fields: Object.keys(fields) });
+}
+
+// ── 7. Verify Record Exists (Deduplication) ───────────────────────────────────
+
+export async function handleVerifyRecordExists({ object_type, name, email, phone, company }) {
+  if (!object_type) throw new Error('object_type is required');
+
+  const matches = [];
+
+  // Priority 1: email match
+  if (email) {
+    const soql = `SELECT Id, Name, Email, Account.Name FROM ${object_type} WHERE Email = '${email}' LIMIT 5`;
+    const records = await query(soql);
+    records.forEach(r => matches.push({ ...r, confidence: 95, match_reason: 'email' }));
+  }
+
+  // Priority 2: phone match
+  if (phone && matches.length === 0) {
+    const clean = phone.replace(/\D/g, '');
+    const soql = `SELECT Id, Name, Phone, Account.Name FROM ${object_type} WHERE Phone LIKE '%${clean.slice(-7)}%' LIMIT 5`;
+    const records = await query(soql);
+    records.forEach(r => matches.push({ ...r, confidence: 80, match_reason: 'phone' }));
+  }
+
+  // Priority 3: name + company
+  if (name && matches.length === 0) {
+    const nameParts = name.trim().split(/\s+/);
+    const lastName = nameParts[nameParts.length - 1];
+
+    let soql = `SELECT Id, Name, Email, Account.Name FROM ${object_type} WHERE LastName LIKE '%${lastName}%'`;
+    if (company) soql += ` AND Account.Name LIKE '%${company.split(' ')[0]}%'`;
+    soql += ' LIMIT 5';
+
+    const records = await query(soql);
+    records.forEach(r => matches.push({ ...r, confidence: 70, match_reason: 'name+company' }));
+  }
+
+  if (matches.length === 0) {
+    return JSON.stringify({ duplicate_found: false, message: 'No existing records found. Safe to create.' });
+  }
+
+  return JSON.stringify({
+    duplicate_found: true,
+    matches,
+    message: `Found ${matches.length} potential match(es). Review before creating.`,
+  });
+}
+
+// ── 8. Hygiene Score ──────────────────────────────────────────────────────────
+
+export async function handleGetHygieneScore({ account_id }) {
+  if (!account_id) throw new Error('account_id is required');
+
+  // Fetch account + opportunities + contacts + activities in parallel
+  const [opps, contacts, tasks, account] = await Promise.all([
+    query(`SELECT Id, Name, StageName, CloseDate, Amount, NextStep, ForecastCategoryName FROM Opportunity WHERE AccountId = '${account_id}' AND IsClosed = false`),
+    query(`SELECT Id, Name, Email, Phone, Title FROM Contact WHERE AccountId = '${account_id}'`),
+    query(`SELECT Id, Subject, Status, ActivityDate FROM Task WHERE AccountId = '${account_id}' AND IsClosed = false ORDER BY CreatedDate DESC LIMIT 10`),
+    query(`SELECT Id, Name, Type, Industry FROM Account WHERE Id = '${account_id}' LIMIT 1`),
+  ]);
+
+  const accountName = account[0]?.Name ?? account_id;
+  const now = new Date();
+  let score = 0;
+  const issues = [];
+  const strengths = [];
+
+  // 1. Required field completion (25 pts)
+  let fieldPoints = 0;
+  opps.forEach(opp => {
+    if (opp.Amount)    fieldPoints += 3;
+    if (opp.NextStep)  fieldPoints += 3;
+    if (opp.CloseDate) fieldPoints += 2;
+  });
+  const fieldScore = opps.length ? Math.min(25, Math.round(fieldPoints / opps.length * 5)) : 0;
+  score += fieldScore;
+  if (fieldScore < 15) issues.push('Missing required fields on open opportunities (Amount, NextStep, CloseDate)');
+  else strengths.push('Open opportunities have key fields populated');
+
+  // 2. Activity recency (25 pts)
+  const recentActivity = tasks.find(t => {
+    const d = new Date(t.ActivityDate || 0);
+    return (now - d) < 30 * 24 * 60 * 60 * 1000;
+  });
+  if (recentActivity) { score += 25; strengths.push('Activity logged within last 30 days'); }
+  else { issues.push('No activity logged in 30+ days'); }
+
+  // 3. Stage accuracy (20 pts) — flag stale close dates
+  const staleOpps = opps.filter(opp => opp.CloseDate && new Date(opp.CloseDate) < now);
+  if (staleOpps.length === 0) { score += 20; strengths.push('All close dates are in the future'); }
+  else { issues.push(`${staleOpps.length} opportunity(ies) have past close dates`); score += 5; }
+
+  // 4. Contact coverage (15 pts)
+  if (contacts.length === 0)     issues.push('No contacts associated with this account');
+  else if (contacts.length === 1) { score += 8; issues.push('Single-threaded — only 1 contact'); }
+  else { score += 15; strengths.push(`${contacts.length} contacts on account`); }
+
+  // 5. Next step presence (15 pts)
+  const oppsWithNextStep = opps.filter(o => o.NextStep);
+  if (opps.length === 0)                           score += 15;
+  else if (oppsWithNextStep.length === opps.length) { score += 15; strengths.push('All open opportunities have next steps'); }
+  else { issues.push(`${opps.length - oppsWithNextStep.length} open opp(s) missing next step`); score += Math.round((oppsWithNextStep.length / opps.length) * 15); }
+
+  const grade = score >= 80 ? 'A' : score >= 65 ? 'B' : score >= 50 ? 'C' : score >= 35 ? 'D' : 'F';
+
+  return JSON.stringify({
+    account: accountName,
+    score,
+    grade,
+    open_opportunities: opps.length,
+    contacts: contacts.length,
+    open_tasks: tasks.length,
+    strengths,
+    issues,
+    recommendation: issues.length === 0
+      ? 'Hygiene looks clean. No immediate action needed.'
+      : `Priority fixes: ${issues[0]}`,
+  }, null, 2);
+}