delegate-sf-mcp 0.2.0

package/src/tools/create.js

@@ -0,0 +1,109 @@
+import { hasInstallationDocumentation, getInstallationDocumentation } from './learn.js';
+
+export const createTool = {
+  name: "salesforce_create",
+  description: "Create a new record in any Salesforce object. Automatically handles required fields validation.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sobject: {
+        type: "string",
+        description: "SObject API name (e.g., 'Contact', 'Account', 'CustomObject__c'). Use exact API names."
+      },
+      data: {
+        type: "object",
+        description: "Field values for the new record. Use API field names as keys (e.g., {'FirstName': 'John', 'LastName': 'Doe', 'Email': 'john@example.com'})"
+      }
+    },
+    required: ["sobject", "data"]
+  }
+};
+
+export async function executeCreate(client, args) {
+  try {
+    const { sobject, data } = args;
+    
+    // Check if installation has been learned and provide helpful context
+    const hasDocumentation = await hasInstallationDocumentation();
+    let contextMessage = '';
+    
+    if (!hasDocumentation) {
+      contextMessage = `⚠️ **Tipp:** Die Salesforce-Installation wurde noch nicht analysiert. Verwende \`salesforce_learn\` um alle verfügbaren Objekte und Felder kennenzulernen.\n\n`;
+    } else {
+      // Provide context about the object if available
+      const documentation = await getInstallationDocumentation();
+      const objectInfo = documentation.objects[sobject];
+      if (objectInfo && !objectInfo.error) {
+        const requiredFields = Object.entries(objectInfo.fields)
+          .filter(([name, field]) => field.required)
+          .map(([name, field]) => `${field.label} (${name})`);
+        
+        if (requiredFields.length > 0) {
+          contextMessage = `💡 **Required fields for ${objectInfo.basic_info.label}:** ${requiredFields.join(', ')}\n\n`;
+        }
+        
+        // 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;
+        });
+        
+        if (readOnlyFieldsInData.length > 0) {
+          const readOnlyWarnings = readOnlyFieldsInData.map(fieldName => {
+            const field = objectInfo.fields[fieldName];
+            return `- ${field.label || fieldName} (${fieldName})`;
+          }).join('\n');
+          
+          contextMessage += `⚠️ **Warning: Read-only fields detected in data:**\n${readOnlyWarnings}\n\n` +
+                           `These fields cannot be set during record creation and will be ignored by Salesforce.\n\n`;
+        }
+      }
+    }
+    
+    if (!sobject || typeof sobject !== 'string') {
+      throw new Error('sobject 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');
+    }
+
+    const result = await client.create(sobject, data);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${contextMessage}✅ Successfully created ${sobject} record!\n\n` +
+                `Record ID: ${result.id}\n` +
+                `Object Type: ${result.sobject}\n\n` +
+                `Created with data:\n${JSON.stringify(data, null, 2)}\n\n` +
+                `You can view this record in Salesforce or query it using:\n` +
+                `SELECT Id, * FROM ${sobject} WHERE Id = '${result.id}'`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ Failed to create ${args.sobject || 'record'}: ${error.message}\n\n` +
+                `Common issues:\n` +
+                `- Required fields missing (use salesforce_describe to see required fields)\n` +
+                `- Invalid field names (use API names, not labels)\n` +
+                `- Invalid data types or formats\n` +
+                `- Insufficient permissions\n` +
+                `- Validation rule failures\n\n` +
+                `Tip: Use salesforce_describe to get field information for ${args.sobject || 'the object'}`
+        }
+      ],
+      isError: true
+    };
+  }
+}

package/src/tools/delegate-hygiene.js

@@ -0,0 +1,268 @@
+/**
+ * delegate_get_hygiene_score — composite health score per account or rep
+ * delegate_bulk_update — batch approved writes via Composite API (up to 25 at once)
+ */
+
+// ─── delegate_get_hygiene_score ───────────────────────────────────────────────
+
+export const getHygieneScoreTool = {
+  name: 'delegate_get_hygiene_score',
+  description:
+    'Delegate: Generate a composite Salesforce hygiene score for an Account or a rep (by owner). ' +
+    'Weighted across: required field completion, activity recency, stage accuracy, contact role coverage, next step presence. ' +
+    'Use this to surface which accounts need attention and to track data quality over time.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      accountId: {
+        type: 'string',
+        description: 'Score hygiene for a specific Account (and its open opps)',
+      },
+      accountName: {
+        type: 'string',
+        description: 'Account name (partial match, used if accountId not known)',
+      },
+      ownerId: {
+        type: 'string',
+        description: "Score hygiene for all open opportunities owned by this user (rep-level view)",
+      },
+      ownerName: {
+        type: 'string',
+        description: 'Owner name (partial match, used if ownerId not known)',
+      },
+    },
+  },
+};
+
+export async function executeGetHygieneScore(client, args) {
+  const { accountId, accountName, ownerId, ownerName } = args;
+
+  try {
+    // ── Resolve IDs ───────────────────────────────────────────────────────────
+    let resolvedAccountId = accountId;
+    if (!resolvedAccountId && accountName) {
+      const r = await client.query(
+        `SELECT Id FROM Account WHERE Name LIKE '%${accountName.replace(/'/g, "\\'")}%' LIMIT 1`
+      );
+      if (r.records.length) resolvedAccountId = r.records[0].Id;
+    }
+
+    let resolvedOwnerId = ownerId;
+    if (!resolvedOwnerId && ownerName) {
+      const r = await client.query(
+        `SELECT Id FROM User WHERE Name LIKE '%${ownerName.replace(/'/g, "\\'")}%' AND IsActive = true LIMIT 1`
+      );
+      if (r.records.length) resolvedOwnerId = r.records[0].Id;
+    }
+
+    if (!resolvedAccountId && !resolvedOwnerId) {
+      return err('Provide accountId, accountName, ownerId, or ownerName');
+    }
+
+    // ── Fetch opportunities ───────────────────────────────────────────────────
+    const whereClause = resolvedAccountId
+      ? `AccountId = '${resolvedAccountId}'`
+      : `OwnerId = '${resolvedOwnerId}'`;
+
+    const opps = await client.query(
+      `SELECT Id, Name, StageName, CloseDate, Amount, NextStep, LastActivityDate,
+              OwnerId, Owner.Name, AccountId, Account.Name, Probability
+       FROM Opportunity
+       WHERE IsClosed = false AND ${whereClause}
+       LIMIT 50`
+    );
+
+    if (!opps.records.length) {
+      return {
+        content: [{ type: 'text', text: '⚠️ No open opportunities found for the given account/owner.' }],
+      };
+    }
+
+    // ── Fetch contact role coverage ───────────────────────────────────────────
+    const oppIds = opps.records.map(o => `'${o.Id}'`).join(',');
+    const contactRoles = await client.query(
+      `SELECT OpportunityId, COUNT(Id) RoleCount
+       FROM OpportunityContactRole
+       WHERE OpportunityId IN (${oppIds})
+       GROUP BY OpportunityId`
+    );
+    const roleMap = Object.fromEntries(contactRoles.records.map(r => [r.OpportunityId, r.RoleCount]));
+
+    // ── Fetch open tasks (next step proxy) ────────────────────────────────────
+    const openTasks = await client.query(
+      `SELECT WhatId FROM Task WHERE WhatId IN (${oppIds}) AND IsClosed = false`
+    );
+    const taskSet = new Set(openTasks.records.map(t => t.WhatId));
+
+    // ── Score each opp ────────────────────────────────────────────────────────
+    const now = new Date();
+    const scored = opps.records.map(opp => {
+      const issues = [];
+      let score = 100;
+
+      // Required fields (−15 each)
+      if (!opp.Amount) { issues.push('Missing Amount'); score -= 15; }
+      if (!opp.CloseDate) { issues.push('Missing Close Date'); score -= 15; }
+
+      // Stale close date (−20)
+      if (opp.CloseDate && new Date(opp.CloseDate) < now) {
+        issues.push('Close date in the past'); score -= 20;
+      }
+
+      // No activity in 30+ days (−15)
+      const daysSinceActivity = opp.LastActivityDate
+        ? Math.floor((now - new Date(opp.LastActivityDate)) / 86_400_000)
+        : 999;
+      if (daysSinceActivity > 30) {
+        issues.push(`No activity in ${daysSinceActivity === 999 ? 'ever' : daysSinceActivity + ' days'}`);
+        score -= 15;
+      }
+
+      // No contact roles (−20)
+      if (!roleMap[opp.Id]) { issues.push('No contact roles'); score -= 20; }
+
+      // No open next step / task (−15)
+      if (!taskSet.has(opp.Id) && !opp.NextStep) {
+        issues.push('No next step or open task'); score -= 15;
+      }
+
+      return {
+        id: opp.Id,
+        name: opp.Name,
+        account: opp['Account.Name'],
+        owner: opp['Owner.Name'],
+        stage: opp.StageName,
+        closeDate: opp.CloseDate,
+        amount: opp.Amount,
+        score: Math.max(0, score),
+        grade: score >= 80 ? '🟢 Good' : score >= 60 ? '🟡 Fair' : '🔴 Poor',
+        issues,
+      };
+    });
+
+    const avg = Math.round(scored.reduce((s, o) => s + o.score, 0) / scored.length);
+    const label = resolvedAccountId
+      ? `Account: ${scored[0]?.account || resolvedAccountId}`
+      : `Owner: ${opps.records[0]?.['Owner.Name'] || resolvedOwnerId}`;
+
+    const poor = scored.filter(o => o.score < 60).length;
+    const fair = scored.filter(o => o.score >= 60 && o.score < 80).length;
+    const good = scored.filter(o => o.score >= 80).length;
+
+    const detail = scored
+      .sort((a, b) => a.score - b.score)
+      .map(o =>
+        `${o.grade} [${o.score}] ${o.name}\n` +
+        (o.issues.length ? `        Issues: ${o.issues.join(' · ')}` : '        No issues')
+      )
+      .join('\n\n');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `📊 **Hygiene Score — ${label}**\n\n` +
+            `Overall: **${avg}/100**  |  🟢 ${good} Good  🟡 ${fair} Fair  🔴 ${poor} Poor\n\n` +
+            `**Opportunities (${scored.length}):**\n\n${detail}`,
+        },
+      ],
+      _delegateResult: { averageScore: avg, opportunities: scored },
+    };
+  } catch (e) {
+    return err(`Hygiene score failed: ${e.message}`);
+  }
+}
+
+// ─── delegate_bulk_update ─────────────────────────────────────────────────────
+
+export const bulkUpdateTool = {
+  name: 'delegate_bulk_update',
+  description:
+    'Delegate: Execute multiple pre-approved Salesforce updates in a single batched operation. ' +
+    'Only call this AFTER the user has explicitly approved each update. ' +
+    'Batches up to 25 writes efficiently. Returns per-record results — partial success is handled gracefully.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      updates: {
+        type: 'array',
+        description: 'Array of approved updates to execute',
+        items: {
+          type: 'object',
+          properties: {
+            objectType: { type: 'string', description: "e.g. 'Opportunity'" },
+            id: { type: 'string', description: 'Salesforce record ID' },
+            fields: { type: 'object', description: 'Fields to update' },
+            description: { type: 'string', description: 'Human-readable description for the confirmation message' },
+          },
+          required: ['objectType', 'id', 'fields'],
+        },
+        maxItems: 25,
+      },
+    },
+    required: ['updates'],
+  },
+};
+
+export async function executeBulkUpdate(client, args) {
+  const { updates } = args;
+
+  if (!updates?.length) {
+    return err('No updates provided');
+  }
+
+  const results = [];
+  let successCount = 0;
+  let failCount = 0;
+
+  // Execute sequentially — jsforce v3 doesn't expose Composite REST directly,
+  // so we batch with Promise.allSettled for parallelism within the rate limit
+  const settled = await Promise.allSettled(
+    updates.map(u => client.update(u.objectType, u.id, u.fields))
+  );
+
+  for (let i = 0; i < updates.length; i++) {
+    const u = updates[i];
+    const outcome = settled[i];
+
+    if (outcome.status === 'fulfilled') {
+      successCount++;
+      results.push({
+        status: '✅',
+        objectType: u.objectType,
+        id: u.id,
+        description: u.description || Object.keys(u.fields).join(', '),
+      });
+    } else {
+      failCount++;
+      results.push({
+        status: '❌',
+        objectType: u.objectType,
+        id: u.id,
+        description: u.description || Object.keys(u.fields).join(', '),
+        error: outcome.reason?.message || 'Unknown error',
+      });
+    }
+  }
+
+  const lines = results.map(
+    r => `${r.status} ${r.objectType} ${r.id} — ${r.description}${r.error ? `\n   Error: ${r.error}` : ''}`
+  );
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text:
+          `**Bulk update complete: ${successCount} succeeded, ${failCount} failed**\n\n` +
+          lines.join('\n'),
+      },
+    ],
+    _delegateResult: { successCount, failCount, results },
+  };
+}
+
+function err(msg) {
+  return { content: [{ type: 'text', text: `❌ ${msg}` }], isError: true };
+}

package/src/tools/delegate-validate.js

@@ -0,0 +1,212 @@
+/**
+ * delegate_validate_update — pre-flight validation before any write surfaces to user
+ * delegate_get_metadata_modified_dates — cheap timestamp check, the #1 governor limit optimization
+ *
+ * These two together guarantee zero failed writes after approval.
+ * The modified date check is the single most important optimization in the entire MCP.
+ */
+
+// ─── delegate_get_metadata_modified_dates ─────────────────────────────────────
+
+export const getMetadataModifiedDatesTool = {
+  name: 'delegate_get_metadata_modified_dates',
+  description:
+    'Delegate: Cheap timestamp check on Salesforce field metadata. ' +
+    'Call this BEFORE pulling full schema. If nothing changed since last_check, skip the expensive metadata read entirely. ' +
+    'This is the #1 governor limit optimization — saves 80% of metadata API calls.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      objectNames: {
+        type: 'array',
+        items: { type: 'string' },
+        description: "Salesforce object API names to check (e.g. ['Opportunity','Contact','Account','Task'])",
+      },
+      lastCheckTimestamp: {
+        type: 'string',
+        description:
+          'ISO datetime of last schema check. Objects with LastModifiedDate > this will be flagged as stale.',
+      },
+    },
+    required: ['objectNames'],
+  },
+};
+
+export async function executeGetMetadataModifiedDates(client, args) {
+  const { objectNames, lastCheckTimestamp } = args;
+
+  // Default: yesterday (forces a fresh check if no checkpoint provided)
+  const since = lastCheckTimestamp
+    ? new Date(lastCheckTimestamp).toISOString()
+    : new Date(Date.now() - 86_400_000).toISOString();
+
+  try {
+    const nameList = objectNames.map(n => `'${n}'`).join(',');
+
+    // This is the critical query from the spec — cheap, targeted, saves everything else
+    const result = await client.query(
+      `SELECT EntityDefinition.QualifiedApiName, MAX(LastModifiedDate) MaxMod
+       FROM FieldDefinition
+       WHERE EntityDefinition.QualifiedApiName IN (${nameList})
+       GROUP BY EntityDefinition.QualifiedApiName`
+    );
+
+    const stale = [];
+    const fresh = [];
+
+    for (const row of result.records) {
+      const objName = row['EntityDefinition.QualifiedApiName'];
+      const serverMod = new Date(row.MaxMod);
+      const sinceDate = new Date(since);
+
+      if (serverMod > sinceDate) {
+        stale.push({ object: objName, lastModified: row.MaxMod });
+      } else {
+        fresh.push(objName);
+      }
+    }
+
+    const cacheValid = stale.length === 0;
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: cacheValid
+            ? `✅ Schema cache valid for: ${fresh.join(', ')}. Skip full metadata pull.`
+            : `⚠️ Schema changed for: ${stale.map(s => s.object).join(', ')}. ` +
+              `Pull full metadata for these objects only.\n\n${JSON.stringify(stale, null, 2)}`,
+        },
+      ],
+      _delegateResult: {
+        cacheValid,
+        staleObjects: stale,
+        freshObjects: fresh,
+        checkedSince: since,
+      },
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `❌ Metadata timestamp check failed: ${err.message}` }],
+      isError: true,
+    };
+  }
+}
+
+// ─── delegate_validate_update ─────────────────────────────────────────────────
+
+export const validateUpdateTool = {
+  name: 'delegate_validate_update',
+  description:
+    'Delegate: Pre-flight validation — checks a proposed update against live Salesforce org metadata ' +
+    'BEFORE surfacing it to the user. Validates required fields, picklist values, field types, and updateability. ' +
+    'A suggestion that fails this check never reaches the approval queue. Zero failed writes after approval.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: "Salesforce object API name (e.g. 'Opportunity')",
+      },
+      recordId: {
+        type: 'string',
+        description: 'Record ID being updated (used to fetch current state for context)',
+      },
+      fields: {
+        type: 'object',
+        description: 'Proposed field updates — { fieldApiName: value }',
+      },
+    },
+    required: ['objectName', 'fields'],
+  },
+};
+
+export async function executeValidateUpdate(client, args) {
+  const { objectName, recordId, fields } = args;
+
+  try {
+    // Pull live metadata for the object
+    const describeResult = await client.describe(objectName);
+
+    const fieldMap = Object.fromEntries(
+      describeResult.fields.map(f => [f.name.toLowerCase(), f])
+    );
+
+    const errors = [];
+    const warnings = [];
+    const validated = [];
+
+    for (const [fieldName, value] of Object.entries(fields)) {
+      const meta = fieldMap[fieldName.toLowerCase()];
+
+      if (!meta) {
+        errors.push(`Field '${fieldName}' does not exist on ${objectName}`);
+        continue;
+      }
+
+      if (!meta.updateable) {
+        errors.push(
+          `Field '${fieldName}' (${meta.label}) is not updateable — ` +
+            (meta.calculated ? 'formula field' : meta.autoNumber ? 'auto-number' : 'system managed')
+        );
+        continue;
+      }
+
+      if (meta.type === 'picklist' && meta.picklistValues?.length > 0) {
+        const valid = meta.picklistValues.filter(p => p.active).map(p => p.value);
+        if (!valid.includes(value)) {
+          errors.push(
+            `'${value}' is not a valid picklist value for ${fieldName}. ` +
+              `Valid options: ${valid.join(', ')}`
+          );
+          continue;
+        }
+      }
+
+      if (meta.type === 'date' || meta.type === 'datetime') {
+        if (value && isNaN(Date.parse(value))) {
+          errors.push(`'${value}' is not a valid date for ${fieldName}`);
+          continue;
+        }
+      }
+
+      if (meta.type === 'currency' || meta.type === 'double' || meta.type === 'integer') {
+        if (value !== null && value !== undefined && isNaN(Number(value))) {
+          errors.push(`'${value}' is not a valid number for ${fieldName} (${meta.type})`);
+          continue;
+        }
+      }
+
+      if (meta.nillable === false && (value === null || value === undefined || value === '')) {
+        warnings.push(`Field '${fieldName}' is required and cannot be blank`);
+      }
+
+      validated.push({ field: fieldName, label: meta.label, type: meta.type, value });
+    }
+
+    const isValid = errors.length === 0;
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: isValid
+            ? `✅ Validation passed for ${objectName}${recordId ? ` (${recordId})` : ''}.\n\n` +
+              `Validated fields:\n${validated.map(v => `  • ${v.label} (${v.field}): ${v.value}`).join('\n')}` +
+              (warnings.length ? `\n\n⚠️ Warnings:\n${warnings.map(w => `  • ${w}`).join('\n')}` : '')
+            : `❌ Validation failed — ${errors.length} error(s). This update will NOT be surfaced to the user.\n\n` +
+              `Errors:\n${errors.map(e => `  • ${e}`).join('\n')}` +
+              (warnings.length ? `\n\nWarnings:\n${warnings.map(w => `  • ${w}`).join('\n')}` : ''),
+        },
+      ],
+      _delegateResult: { isValid, errors, warnings, validated },
+      isError: !isValid,
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `❌ Validation error: ${err.message}` }],
+      _delegateResult: { isValid: false, errors: [err.message], warnings: [], validated: [] },
+      isError: true,
+    };
+  }
+}