delegate-sf-mcp 0.2.0

package/src/tools/delegate-verify.js

@@ -0,0 +1,143 @@
+/**
+ * verify_record_exists
+ * Fuzzy match before every create suggestion.
+ * Priority: email → phone → name + company
+ * Returns potential duplicates with confidence score.
+ * Non-negotiable — runs before EVERY create. Zero exceptions.
+ */
+
+export const verifyRecordExistsTool = {
+  name: 'delegate_verify_record_exists',
+  description:
+    'Delegate: Check for duplicate records before creating a new Contact, Lead, or Account. ' +
+    'Runs fuzzy matching — email first (confidence 95), then phone (80), then name + company (70). ' +
+    'Always call this before suggesting salesforce_create for person or account records.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      objectType: {
+        type: 'string',
+        enum: ['Contact', 'Lead', 'Account'],
+        description: 'Salesforce object type to check for duplicates',
+      },
+      email: { type: 'string', description: 'Email address — highest confidence match key' },
+      phone: { type: 'string', description: 'Phone number — secondary match key' },
+      name: { type: 'string', description: 'Full name or account name — tertiary match key' },
+      company: { type: 'string', description: 'Company name — used with name for person records' },
+    },
+    required: ['objectType'],
+  },
+};
+
+export async function executeVerifyRecordExists(client, args) {
+  const { objectType, email, phone, name, company } = args;
+
+  if (!email && !phone && !name) {
+    return result(false, [], 'Provide at least one of: email, phone, or name');
+  }
+
+  try {
+    const matches = [];
+
+    // ── Pass 1: email (confidence 95) ─────────────────────────────────────────
+    if (email) {
+      const emailField = objectType === 'Account' ? null : 'Email';
+      if (emailField) {
+        const emailMatches = await client.query(
+          `SELECT Id, Name, ${emailField}, ${objectType === 'Lead' ? 'Company' : 'Account.Name'}
+           FROM ${objectType}
+           WHERE ${emailField} = '${email.replace(/'/g, "\\'")}'
+           LIMIT 5`
+        );
+        for (const r of emailMatches.records) {
+          matches.push({ ...r, _confidence: 95, _matchedOn: 'email' });
+        }
+      }
+    }
+
+    // ── Pass 2: phone (confidence 80) ─────────────────────────────────────────
+    if (phone && matches.length === 0) {
+      const cleanPhone = phone.replace(/\D/g, '');
+      const phoneField = objectType === 'Account' ? 'Phone' : 'Phone';
+      const phoneMatches = await client.query(
+        `SELECT Id, Name, ${phoneField}${objectType !== 'Account' ? ', Email' : ''}
+         FROM ${objectType}
+         WHERE ${phoneField} LIKE '%${cleanPhone.slice(-7)}%'
+         LIMIT 5`
+      );
+      for (const r of phoneMatches.records) {
+        if (!matches.find(m => m.Id === r.Id)) {
+          matches.push({ ...r, _confidence: 80, _matchedOn: 'phone' });
+        }
+      }
+    }
+
+    // ── Pass 3: name + company (confidence 70) ────────────────────────────────
+    if (name && matches.length === 0) {
+      const nameClean = name.replace(/'/g, "\\'");
+      let soql;
+
+      if (objectType === 'Account') {
+        soql = `SELECT Id, Name, Phone, Website FROM Account
+                WHERE Name LIKE '%${nameClean}%' LIMIT 5`;
+      } else {
+        const companyFilter =
+          company
+            ? ` AND ${objectType === 'Lead' ? 'Company' : 'Account.Name'} LIKE '%${company.replace(/'/g, "\\'")}%'`
+            : '';
+        soql = `SELECT Id, Name, Email, Phone${objectType === 'Contact' ? ', Account.Name' : ', Company'}
+                FROM ${objectType}
+                WHERE Name LIKE '%${nameClean}%'${companyFilter}
+                LIMIT 5`;
+      }
+
+      const nameMatches = await client.query(soql);
+      for (const r of nameMatches.records) {
+        if (!matches.find(m => m.Id === r.Id)) {
+          matches.push({ ...r, _confidence: 70, _matchedOn: 'name' });
+        }
+      }
+    }
+
+    if (matches.length === 0) {
+      return result(true, [], null, 'No duplicates found — safe to create');
+    }
+
+    const formatted = matches.map(m => ({
+      id: m.Id,
+      name: m.Name,
+      confidence: m._confidence,
+      matchedOn: m._matchedOn,
+      email: m.Email || null,
+      phone: m.Phone || null,
+      company: m['Account.Name'] || m.Company || null,
+    }));
+
+    return result(true, formatted, null,
+      `Found ${matches.length} potential duplicate(s). Review before creating.`
+    );
+
+  } catch (err) {
+    return result(false, [], `Query failed: ${err.message}`);
+  }
+}
+
+function result(success, matches, error, message) {
+  const hasDuplicates = matches.length > 0;
+  return {
+    content: [
+      {
+        type: 'text',
+        text: error
+          ? `❌ verify_record_exists error: ${error}`
+          : hasDuplicates
+          ? `⚠️ **Potential duplicates found** — ${message}\n\n${JSON.stringify(matches, null, 2)}\n\n` +
+            `Confirm with the user: "We found an existing record. Is this the same person?" ` +
+            `If yes → update existing. If no → create new and note the distinction.`
+          : `✅ ${message} — proceed with create`,
+      },
+    ],
+    _delegateResult: { success, hasDuplicates, matches },
+    isError: !success,
+  };
+}

package/src/tools/delete.js

@@ -0,0 +1,72 @@
+export const deleteTool = {
+  name: "salesforce_delete",
+  description: "Delete a record from any Salesforce object. This action is permanent and cannot be undone.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sobject: {
+        type: "string",
+        description: "SObject API name (e.g., 'Contact', 'Account', 'CustomObject__c')"
+      },
+      id: {
+        type: "string",
+        description: "Salesforce record ID to delete (15 or 18 character ID)"
+      }
+    },
+    required: ["sobject", "id"]
+  }
+};
+
+export async function executeDelete(client, args) {
+  try {
+    const { sobject, id } = args;
+    
+    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');
+    }
+
+    // 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.');
+    }
+
+    const result = await client.delete(sobject, id);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `✅ Successfully deleted ${sobject} record!\n\n` +
+                `Deleted Record ID: ${result.id}\n` +
+                `Object Type: ${result.sobject}\n\n` +
+                `⚠️  This action is permanent and cannot be undone.\n` +
+                `The record has been moved to the Recycle Bin and will be permanently deleted after 15 days.`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ Failed to delete ${args.sobject || 'record'}: ${error.message}\n\n` +
+                `Common issues:\n` +
+                `- Record not found (check the ID)\n` +
+                `- Record cannot be deleted (may have dependencies)\n` +
+                `- Insufficient permissions\n` +
+                `- Record is referenced by other records\n` +
+                `- Object deletion is not allowed\n\n` +
+                `Record ID provided: ${args.id}\n` +
+                `Object Type: ${args.sobject}\n\n` +
+                `Tip: Some records cannot be deleted if they are referenced by other records. ` +
+                `You may need to delete dependent records first.`
+        }
+      ],
+      isError: true
+    };
+  }
+}

package/src/tools/describe.js

@@ -0,0 +1,132 @@
+export const describeTool = {
+  name: "salesforce_describe",
+  description: "Get detailed schema information for any Salesforce object, including all fields, data types, and permissions.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sobject: {
+        type: "string",
+        description: "SObject API name to describe (e.g., 'Contact', 'Account', 'CustomObject__c'). Leave empty to get list of all available objects."
+      }
+    },
+    required: []
+  }
+};
+
+export async function executeDescribe(client, args) {
+  try {
+    const { sobject } = args;
+    
+    // If no sobject specified, return list of all available objects
+    if (!sobject) {
+      const sobjects = await client.describeGlobal();
+      
+      const standardObjects = sobjects.filter(obj => !obj.custom).slice(0, 20);
+      const customObjects = sobjects.filter(obj => obj.custom);
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📊 Available Salesforce Objects (${sobjects.length} total)\n\n` +
+                  `Standard Objects (showing first 20):\n` +
+                  standardObjects.map(obj => 
+                    `• ${obj.name} (${obj.label}) - Create: ${obj.createable}, Update: ${obj.updateable}, Delete: ${obj.deletable}`
+                  ).join('\n') +
+                  (sobjects.filter(obj => !obj.custom).length > 20 ? '\n... and more standard objects\n' : '\n') +
+                  `\nCustom Objects:\n` +
+                  (customObjects.length > 0 
+                    ? customObjects.map(obj => 
+                        `• ${obj.name} (${obj.label}) - Create: ${obj.createable}, Update: ${obj.updateable}, Delete: ${obj.deletable}`
+                      ).join('\n')
+                    : 'No custom objects found'
+                  ) +
+                  `\n\nTo get detailed information about a specific object, use:\n` +
+                  `salesforce_describe with sobject parameter (e.g., "Contact", "Account")`
+          }
+        ]
+      };
+    }
+
+    if (typeof sobject !== 'string') {
+      throw new Error('sobject parameter must be a string');
+    }
+
+    const schema = await client.describe(sobject);
+    
+    // Categorize fields
+    const requiredFields = schema.fields.filter(f => f.required);
+    const createableFields = schema.fields.filter(f => f.createable);
+    const updateableFields = schema.fields.filter(f => f.updateable);
+    const picklistFields = schema.fields.filter(f => f.type === 'picklist' && f.picklistValues.length > 0);
+    const referenceFields = schema.fields.filter(f => f.type === 'reference' && f.referenceTo.length > 0);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `📋 ${schema.label} (${schema.name}) Schema Information\n\n` +
+                `Object Details:\n` +
+                `• Label: ${schema.label} (Plural: ${schema.labelPlural})\n` +
+                `• API Name: ${schema.name}\n` +
+                `• Key Prefix: ${schema.keyPrefix || 'N/A'}\n` +
+                `• Permissions: Create: ${schema.createable}, Update: ${schema.updateable}, Delete: ${schema.deletable}, Query: ${schema.queryable}\n` +
+                `• Total Fields: ${schema.fields.length}\n\n` +
+                
+                `Required Fields (${requiredFields.length}):\n` +
+                (requiredFields.length > 0 
+                  ? requiredFields.map(f => `• ${f.name} (${f.label}) - ${f.type}`).join('\n')
+                  : 'None'
+                ) + '\n\n' +
+                
+                `Key Fields for Operations:\n` +
+                `Createable Fields: ${createableFields.length}\n` +
+                `Updateable Fields: ${updateableFields.length}\n\n` +
+                
+                (picklistFields.length > 0 
+                  ? `Picklist Fields:\n` + 
+                    picklistFields.map(f => 
+                      `• ${f.name} (${f.label}): ${f.picklistValues.map(p => p.value).join(', ')}`
+                    ).join('\n') + '\n\n'
+                  : ''
+                ) +
+                
+                (referenceFields.length > 0 
+                  ? `Reference Fields (Lookups):\n` + 
+                    referenceFields.map(f => 
+                      `• ${f.name} (${f.label}) → ${f.referenceTo.join(', ')}`
+                    ).join('\n') + '\n\n'
+                  : ''
+                ) +
+                
+                `Common Fields for SOQL:\n` +
+                schema.fields
+                  .filter(f => ['Id', 'Name', 'CreatedDate', 'LastModifiedDate'].includes(f.name) || 
+                              f.name.includes('Email') || f.name.includes('Phone'))
+                  .map(f => `• ${f.name} (${f.label}) - ${f.type}`)
+                  .join('\n') +
+                
+                `\n\nExample SOQL Query:\n` +
+                `SELECT Id, ${schema.fields.filter(f => f.name !== 'Id').slice(0, 5).map(f => f.name).join(', ')} FROM ${schema.name} LIMIT 10`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ Failed to describe ${args.sobject || 'objects'}: ${error.message}\n\n` +
+                `Common issues:\n` +
+                `- Object name not found (check spelling and API name)\n` +
+                `- Insufficient permissions to access object metadata\n` +
+                `- Object may not be queryable\n\n` +
+                `Tip: Object API names are case-sensitive. Use exact API names like:\n` +
+                `- Standard objects: "Account", "Contact", "Opportunity"\n` +
+                `- Custom objects: end with "__c" like "CustomObject__c"`
+        }
+      ],
+      isError: true
+    };
+  }
+}