delegate-sf-mcp 0.2.0

package/src/tools/learn.js

@@ -0,0 +1,351 @@
+/**
+ * Salesforce Learn Tool
+ * 
+ * This tool analyzes the complete Salesforce installation and creates
+ * a comprehensive local documentation cache of all objects, fields,
+ * relationships, and customizations.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { debug as logger } from '../utils/debug.js';
+import { getCacheFilePath, ensureCacheDirectory } from '../utils/cache.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Path for storing the learned installation data
+const INSTALLATION_FILE = getCacheFilePath('salesforce-installation.json');
+
+export const salesforceLearnTool = {
+  name: "salesforce_learn",
+  description: "Analyzes the complete Salesforce installation and creates local documentation of all objects, fields, and customizations. This should be run once after initial setup to enable intelligent assistance.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      force_refresh: {
+        type: "boolean",
+        description: "Forces a complete re-analysis even if documentation already exists",
+        default: false
+      },
+      include_unused: {
+        type: "boolean", 
+        description: "Includes unused/inactive fields and objects in the documentation",
+        default: false
+      },
+      detailed_relationships: {
+        type: "boolean",
+        description: "Analyzes detailed relationships between objects",
+        default: true
+      }
+    }
+  }
+};
+
+export async function handleSalesforceLearn(args, salesforceClient) {
+  const { force_refresh = false, include_unused = false, detailed_relationships = true } = args;
+  
+  try {
+    // Check if we need to create cache directory
+    await ensureCacheDirectory();
+    
+    // Check if documentation already exists
+    const existingDoc = await getExistingDocumentation();
+    if (existingDoc && !force_refresh) {
+      return {
+        content: [{
+          type: "text", 
+          text: `✅ Salesforce installation already documented (${existingDoc.metadata.learned_at})\n\n` +
+                `📊 **Overview:**\n` +
+                `- **${existingDoc.summary.total_objects}** total objects\n` +
+                `- **${existingDoc.summary.custom_objects}** custom objects\n` + 
+                `- **${existingDoc.summary.total_fields}** total fields\n` +
+                `- **${existingDoc.summary.custom_fields}** custom fields\n\n` +
+                `💡 Use \`force_refresh: true\` to force re-analysis, or use the \`salesforce_installation_info\` tool to view details.`
+        }]
+      };
+    }
+
+    // Start learning process
+    logger.log('🔍 Starting Salesforce installation learning process...');
+    
+    // Step 1: Get all available objects
+    const globalDescribe = await salesforceClient.describeGlobal();
+    
+    logger.log(`📋 Found: ${globalDescribe.length} objects`);
+    
+    // Step 2: Filter and categorize objects
+    const standardObjects = [];
+    const customObjects = [];
+    
+    for (const obj of globalDescribe) {
+      if (obj.custom) {
+        customObjects.push(obj);
+      } else if (obj.name.match(/^(Account|Contact|Lead|Opportunity|Case|Task|Event|Campaign|Product2|Pricebook2|User|Profile)$/)) {
+        // Include important standard objects
+        standardObjects.push(obj);
+      }
+    }
+    
+    logger.log(`📊 Standard objects: ${standardObjects.length}, Custom objects: ${customObjects.length}`);
+    
+    // Step 3: Detailed analysis of selected objects
+    const documentation = {
+      metadata: {
+        learned_at: new Date().toISOString(),
+        salesforce_instance: salesforceClient.instanceUrl,
+        api_version: salesforceClient.version || 'v58.0',
+        learning_options: { include_unused, detailed_relationships }
+      },
+      summary: {
+        total_objects: standardObjects.length + customObjects.length,
+        standard_objects: standardObjects.length,
+        custom_objects: customObjects.length,
+        total_fields: 0,
+        custom_fields: 0
+      },
+      objects: {}
+    };
+    
+    // Analyze objects in batches to avoid rate limits
+    const objectsToAnalyze = [...standardObjects, ...customObjects];
+    const batchSize = 10;
+    
+    for (let i = 0; i < objectsToAnalyze.length; i += batchSize) {
+      const batch = objectsToAnalyze.slice(i, i + batchSize);
+      logger.log(`🔬 Analyzing batch ${Math.floor(i/batchSize) + 1}/${Math.ceil(objectsToAnalyze.length/batchSize)} (${batch.length} objects)`);
+      
+      await Promise.all(batch.map(async (obj) => {
+        try {
+          const objectDoc = await analyzeObject(obj, salesforceClient, { include_unused, detailed_relationships });
+          documentation.objects[obj.name] = objectDoc;
+          documentation.summary.total_fields += objectDoc.field_count;
+          documentation.summary.custom_fields += objectDoc.custom_field_count;
+        } catch (error) {
+          logger.warn(`⚠️ Error analyzing ${obj.name}:`, error.message);
+          documentation.objects[obj.name] = {
+            error: `Analysis failed: ${error.message}`,
+            basic_info: {
+              name: obj.name,
+              label: obj.label,
+              custom: obj.custom
+            }
+          };
+        }
+      }));
+      
+      // Small delay between batches
+      if (i + batchSize < objectsToAnalyze.length) {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+    }
+    
+    // Step 4: Save documentation
+    await fs.writeFile(INSTALLATION_FILE, JSON.stringify(documentation, null, 2), 'utf8');
+    
+    logger.log('✅ Learning process completed');
+    
+    return {
+      content: [{
+        type: "text",
+        text: `🎉 **Salesforce installation successfully learned!**\n\n` +
+              `📊 **Analyzed data:**\n` +
+              `- **${documentation.summary.total_objects}** total objects\n` +
+              `- **${documentation.summary.standard_objects}** standard objects\n` +
+              `- **${documentation.summary.custom_objects}** custom objects\n` +
+              `- **${documentation.summary.total_fields}** total fields\n` +
+              `- **${documentation.summary.custom_fields}** custom fields\n\n` +
+              `💾 **Documentation saved** to: \`${INSTALLATION_FILE}\`\n\n` +
+              `✨ **Next steps:**\n` +
+              `- Use \`salesforce_installation_info\` to get an overview\n` +
+              `- Ask about specific objects or fields\n` +
+              `- The AI can now work intelligently with your Salesforce installation!`
+      }]
+    };
+    
+  } catch (error) {
+    logger.error('❌ Error during learning process:', error);
+    return {
+      content: [{
+        type: "text",
+        text: `❌ **Error learning Salesforce installation:**\n\n` +
+              `${error.message}\n\n` +
+              `🔧 **Possible solutions:**\n` +
+              `- Check your Salesforce connection\n` +
+              `- Ensure you have sufficient permissions\n` +
+              `- Try re-authenticating with \`salesforce_auth\``
+      }]
+    };
+  }
+}
+
+async function analyzeObject(obj, salesforceClient, options) {
+  const { include_unused, detailed_relationships } = options;
+  
+  // Get detailed object description
+  const describe = await salesforceClient.describe(obj.name);
+  
+  const objectDoc = {
+    basic_info: {
+      name: obj.name,
+      label: obj.label,
+      label_plural: obj.labelPlural,
+      custom: obj.custom,
+      api_name: obj.name
+    },
+    metadata: {
+      createable: describe.createable,
+      updateable: describe.updateable,
+      deletable: describe.deletable,
+      queryable: describe.queryable,
+      searchable: describe.searchable,
+      retrieveable: describe.retrieveable
+    },
+    field_count: describe.fields.length,
+    custom_field_count: describe.fields.filter(f => f.custom).length,
+    fields: {},
+    relationships: {
+      parent_relationships: [],
+      child_relationships: []
+    }
+  };
+  
+  // Analyze fields
+  for (const field of describe.fields) {
+    // Skip system fields if not including unused
+    if (!include_unused && isSystemField(field)) {
+      continue;
+    }
+    
+    const fieldDoc = {
+      name: field.name,
+      label: field.label,
+      type: field.type,
+      custom: field.custom,
+      required: !field.nillable && !field.defaultedOnCreate,
+      updateable: field.updateable,
+      createable: field.createable,
+      // Enhanced writability information
+      writability: {
+        fully_writable: field.updateable && field.createable,
+        create_only: field.createable && !field.updateable,
+        read_only: !field.updateable && !field.createable,
+        system_managed: isSystemManagedField(field),
+        calculated: field.calculated || false,
+        auto_number: field.type === 'autonumber',
+        formula: field.type === 'formula' || field.calculated,
+        rollup_summary: field.type === 'summary'
+      }
+    };
+    
+    // Add type-specific information
+    if (field.type === 'picklist' || field.type === 'multipicklist') {
+      fieldDoc.picklist_values = field.picklistValues?.map(v => ({
+        value: v.value,
+        label: v.label,
+        active: v.active
+      })) || [];
+    }
+    
+    if (field.type === 'reference') {
+      fieldDoc.reference_to = field.referenceTo;
+      if (detailed_relationships && field.referenceTo?.length > 0) {
+        objectDoc.relationships.parent_relationships.push({
+          field: field.name,
+          references: field.referenceTo
+        });
+      }
+    }
+    
+    if (field.length) {
+      fieldDoc.max_length = field.length;
+    }
+    
+    if (field.precision) {
+      fieldDoc.precision = field.precision;
+      fieldDoc.scale = field.scale;
+    }
+    
+    objectDoc.fields[field.name] = fieldDoc;
+  }
+  
+  // Analyze child relationships
+  if (detailed_relationships && describe.childRelationships) {
+    for (const childRel of describe.childRelationships) {
+      if (childRel.relationshipName) {
+        objectDoc.relationships.child_relationships.push({
+          child_object: childRel.childSObject,
+          relationship_name: childRel.relationshipName,
+          field: childRel.field
+        });
+      }
+    }
+  }
+  
+  return objectDoc;
+}
+
+function isSystemField(field) {
+  const systemFields = [
+    'Id', 'CreatedDate', 'CreatedById', 'LastModifiedDate', 'LastModifiedById',
+    'SystemModstamp', 'IsDeleted', 'MasterRecordId', 'LastActivityDate',
+    'LastViewedDate', 'LastReferencedDate'
+  ];
+  return systemFields.includes(field.name);
+}
+
+function isSystemManagedField(field) {
+  // System fields that are automatically managed by Salesforce
+  const systemManagedFields = [
+    'Id', 'CreatedDate', 'CreatedById', 'LastModifiedDate', 'LastModifiedById',
+    'SystemModstamp', 'IsDeleted', 'MasterRecordId', 'LastActivityDate',
+    'LastViewedDate', 'LastReferencedDate', 'RecordTypeId'
+  ];
+  
+  // Check if it's a system managed field by name
+  if (systemManagedFields.includes(field.name)) {
+    return true;
+  }
+  
+  // Check if it's an auto-number field
+  if (field.type === 'autonumber') {
+    return true;
+  }
+  
+  // Check if it's a formula field
+  if (field.type === 'formula' || field.calculated) {
+    return true;
+  }
+  
+  // Check if it's a rollup summary field
+  if (field.type === 'summary') {
+    return true;
+  }
+  
+  // Check if field is marked as not updateable and not createable (fully read-only)
+  if (!field.updateable && !field.createable) {
+    return true;
+  }
+  
+  return false;
+}
+
+
+async function getExistingDocumentation() {
+  try {
+    const content = await fs.readFile(INSTALLATION_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export async function getInstallationDocumentation() {
+  return await getExistingDocumentation();
+}
+
+export async function hasInstallationDocumentation() {
+  const doc = await getExistingDocumentation();
+  return doc !== null;
+}

package/src/tools/query.js

@@ -0,0 +1,82 @@
+import { hasInstallationDocumentation } from './learn.js';
+
+export const queryTool = {
+  name: "salesforce_query",
+  description: "Execute SOQL queries against any Salesforce object. Supports SELECT, WHERE, ORDER BY, LIMIT, and other SOQL features.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "SOQL query string (e.g., 'SELECT Id, Name FROM Account WHERE Industry = \\'Technology\\' LIMIT 10'). Use proper SOQL syntax with single quotes for string literals."
+      }
+    },
+    required: ["query"]
+  }
+};
+
+export async function executeQuery(client, args) {
+  try {
+    const { query } = args;
+    
+    // Check if installation has been learned
+    const hasDocumentation = await hasInstallationDocumentation();
+    if (!hasDocumentation) {
+      return {
+        content: [{
+          type: "text",
+          text: `⚠️ **Salesforce-Installation noch nicht gelernt**\n\n` +
+                `Bevor du SOQL-Abfragen ausführst, sollte die KI deine Salesforce-Installation kennenlernen.\n\n` +
+                `🚀 **Empfehlung:** Führe zuerst das \`salesforce_learn\` Tool aus, um alle verfügbaren Objekte und Felder zu analysieren.\n\n` +
+                `Danach kann ich dir bei intelligenten Abfragen helfen und die richtigen Feld- und Objektnamen vorschlagen.\n\n` +
+                `**Deine Abfrage wird trotzdem ausgeführt:**`
+        }]
+      };
+    }
+    
+    if (!query || typeof query !== 'string') {
+      throw new Error('Query parameter is required and must be a string');
+    }
+
+    // Basic SOQL validation
+    if (!query.trim().toUpperCase().startsWith('SELECT')) {
+      throw new Error('Query must be a SELECT statement');
+    }
+
+    const result = await client.query(query);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `SOQL Query Results:\n\n` +
+                `Query: ${query}\n` +
+                `Total Records: ${result.totalSize}\n` +
+                `Records Returned: ${result.records.length}\n` +
+                `More Records Available: ${!result.done}\n\n` +
+                `Results:\n${JSON.stringify(result.records, null, 2)}`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text", 
+          text: `❌ Query failed: ${error.message}\n\n` +
+                `Query: ${args.query || 'N/A'}\n\n` +
+                `Common issues:\n` +
+                `- Check field names (case-sensitive)\n` +
+                `- Verify object name exists\n` +
+                `- Ensure you have read permissions\n` +
+                `- Use single quotes for string literals\n\n` +
+                `SOQL Syntax Help:\n` +
+                `- SELECT Id, Name FROM Account LIMIT 10\n` +
+                `- SELECT Id, Name FROM Contact WHERE Email != null\n` +
+                `- SELECT Id, Name FROM Opportunity WHERE Amount > 1000`
+        }
+      ],
+      isError: true
+    };
+  }
+}

package/src/tools/repair-credentials.js

@@ -0,0 +1,77 @@
+import { FileStorageManager } from '../auth/file-storage.js';
+
+/**
+ * Repair credentials that were accidentally set to null
+ * This is a one-time fix for the bug where credentials were overwritten with null
+ */
+export async function repairCredentials() {
+  const fileStorage = new FileStorageManager();
+  
+  try {
+    const data = await fileStorage.getAllData();
+    
+    console.error('Current data:', data);
+    
+    if (data.access_token && data.refresh_token && (!data.clientId || !data.clientSecret)) {
+      console.error('🔍 Found tokens without credentials - this is the bug!');
+      
+      // We need to ask the user for the credentials
+      console.error('❗ We need to restore the missing credentials.');
+      console.error('Please provide the following information:');
+      console.error('1. Client ID (Consumer Key from your Connected App)');
+      console.error('2. Client Secret (Consumer Secret from your Connected App)');
+      console.error('');
+      console.error('You can find these in your Salesforce Setup > App Manager > Your Connected App > View');
+      
+      // For now, we'll create a temporary fix that preserves the tokens
+      // but allows the system to work
+      const repairedData = {
+        ...data,
+        clientId: data.clientId || 'NEEDS_REPAIR',
+        clientSecret: data.clientSecret || 'NEEDS_REPAIR',
+        instanceUrl: data.instanceUrl || data.instance_url,
+        credentialsStoredAt: data.credentialsStoredAt || new Date().toISOString(),
+        repaired: true,
+        repairNote: 'Credentials were null due to bug - needs manual repair'
+      };
+      
+      await fileStorage.storeCredentials({
+        clientId: 'NEEDS_REPAIR',
+        clientSecret: 'NEEDS_REPAIR', 
+        instanceUrl: data.instanceUrl || data.instance_url
+      });
+      
+      console.error('✅ Temporary repair applied. You can now use the system, but please update credentials.');
+      
+      return {
+        success: true,
+        message: 'Temporary repair applied',
+        nextSteps: [
+          'Get your Client ID and Client Secret from Salesforce Setup',
+          'Run the setup tool to properly configure credentials',
+          'Your existing tokens will be preserved'
+        ]
+      };
+    }
+    
+    console.error('✅ No repair needed - credentials look correct');
+    return {
+      success: true,
+      message: 'No repair needed'
+    };
+    
+  } catch (error) {
+    console.error('❌ Repair failed:', error.message);
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+// If run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  repairCredentials().then(result => {
+    console.error(JSON.stringify(result, null, 2));
+  });
+}

package/src/tools/setup.js

@@ -0,0 +1,120 @@
+import { FileStorageManager } from '../auth/file-storage.js';
+import { logger } from '../utils/debug.js';
+
+/**
+ * Setup tool for collecting Salesforce credentials
+ */
+export const setupTool = {
+  name: 'salesforce_setup',
+  description: 'Configure Salesforce credentials (Client ID, Client Secret, Instance URL)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      clientId: {
+        type: 'string',
+        description: 'Salesforce Connected App Client ID (Consumer Key)'
+      },
+      clientSecret: {
+        type: 'string',
+        description: 'Salesforce Connected App Client Secret (Consumer Secret)'
+      },
+      instanceUrl: {
+        type: 'string',
+        description: 'Salesforce Instance URL (e.g., https://mycompany.salesforce.com)'
+      }
+    },
+    required: ['clientId', 'clientSecret', 'instanceUrl']
+  }
+};
+
+/**
+ * Handle Salesforce setup
+ * @param {Object} args - Setup arguments
+ * @returns {Object} Setup result
+ */
+export async function handleSalesforceSetup(args) {
+  try {
+    logger.log('🔧 Setting up Salesforce credentials...');
+
+    const { clientId, clientSecret, instanceUrl } = args;
+
+    // Validate inputs
+    if (!clientId || !clientSecret || !instanceUrl) {
+      return {
+        success: false,
+        error: 'Missing required credentials. Please provide clientId, clientSecret, and instanceUrl.'
+      };
+    }
+
+    // Validate instance URL format
+    if (!instanceUrl.startsWith('https://') || !instanceUrl.includes('.salesforce.com')) {
+      return {
+        success: false,
+        error: 'Invalid instance URL format. Must be https://yourorg.salesforce.com'
+      };
+    }
+
+    // Clean up instance URL (remove trailing slash)
+    const cleanInstanceUrl = instanceUrl.replace(/\/$/, '');
+
+    // Store credentials
+    const fileStorage = new FileStorageManager();
+    await fileStorage.storeCredentials({
+      clientId,
+      clientSecret,
+      instanceUrl: cleanInstanceUrl
+    });
+
+    logger.log('✅ Salesforce credentials configured successfully');
+
+    return {
+      success: true,
+      message: 'Salesforce credentials have been configured successfully. You can now use other Salesforce tools.',
+      details: {
+        instanceUrl: cleanInstanceUrl,
+        clientIdPreview: clientId.substring(0, 20) + '...'
+      }
+    };
+
+  } catch (error) {
+    logger.error('❌ Setup failed:', error);
+    return {
+      success: false,
+      error: `Setup failed: ${error.message}`
+    };
+  }
+}
+
+/**
+ * Check if credentials are configured
+ * @returns {Object} Configuration status
+ */
+export async function checkCredentialsStatus() {
+  try {
+    const fileStorage = new FileStorageManager();
+    const credentials = await fileStorage.getCredentials();
+    
+    if (!credentials) {
+      return {
+        configured: false,
+        message: 'No Salesforce credentials found. Please run the salesforce_setup tool first.'
+      };
+    }
+
+    return {
+      configured: true,
+      message: 'Salesforce credentials are configured.',
+      details: {
+        instanceUrl: credentials.instanceUrl,
+        clientIdPreview: credentials.clientId.substring(0, 20) + '...',
+        configuredAt: credentials.credentialsStoredAt
+      }
+    };
+
+  } catch (error) {
+    return {
+      configured: false,
+      error: `Error checking credentials: ${error.message}`
+    };
+  }
+}