@rohithvemulapally/mcp-server-salesforce 0.0.6

package/dist/tools/aggregateQuery.d.ts

@@ -0,0 +1,18 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const AGGREGATE_QUERY: Tool;
+export interface AggregateQueryArgs {
+    objectName: string;
+    selectFields: string[];
+    groupByFields: string[];
+    whereClause?: string;
+    havingClause?: string;
+    orderBy?: string;
+    limit?: number;
+}
+export declare function handleAggregateQuery(conn: any, args: AggregateQueryArgs): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/tools/aggregateQuery.js

@@ -0,0 +1,250 @@
+export const AGGREGATE_QUERY = {
+    name: "salesforce_aggregate_query",
+    description: `Execute SOQL queries with GROUP BY, aggregate functions, and statistical analysis. Use this tool for queries that summarize and group data rather than returning individual records.
+
+NOTE: For regular queries without GROUP BY or aggregates, use salesforce_query_records instead.
+
+This tool handles:
+1. GROUP BY queries (single/multiple fields, related objects, date functions)
+2. Aggregate functions: COUNT(), COUNT_DISTINCT(), SUM(), AVG(), MIN(), MAX()
+3. HAVING clauses for filtering grouped results
+4. Date/time grouping: CALENDAR_YEAR(), CALENDAR_MONTH(), CALENDAR_QUARTER(), FISCAL_YEAR(), FISCAL_QUARTER()
+
+Examples:
+1. Count opportunities by stage:
+   - objectName: "Opportunity"
+   - selectFields: ["StageName", "COUNT(Id) OpportunityCount"]
+   - groupByFields: ["StageName"]
+
+2. Analyze cases by priority and status:
+   - objectName: "Case"
+   - selectFields: ["Priority", "Status", "COUNT(Id) CaseCount", "AVG(Days_Open__c) AvgDaysOpen"]
+   - groupByFields: ["Priority", "Status"]
+
+3. Count contacts by account industry:
+   - objectName: "Contact"
+   - selectFields: ["Account.Industry", "COUNT(Id) ContactCount"]
+   - groupByFields: ["Account.Industry"]
+
+4. Quarterly opportunity analysis:
+   - objectName: "Opportunity"
+   - selectFields: ["CALENDAR_YEAR(CloseDate) Year", "CALENDAR_QUARTER(CloseDate) Quarter", "SUM(Amount) Revenue"]
+   - groupByFields: ["CALENDAR_YEAR(CloseDate)", "CALENDAR_QUARTER(CloseDate)"]
+
+5. Find accounts with more than 10 opportunities:
+   - objectName: "Opportunity"
+   - selectFields: ["Account.Name", "COUNT(Id) OpportunityCount"]
+   - groupByFields: ["Account.Name"]
+   - havingClause: "COUNT(Id) > 10"
+
+Important Rules:
+- All non-aggregate fields in selectFields MUST be included in groupByFields
+- Use whereClause to filter rows BEFORE grouping
+- Use havingClause to filter AFTER grouping (for aggregate conditions)
+- ORDER BY can only use fields from groupByFields or aggregate functions
+- OFFSET is not supported with GROUP BY in Salesforce`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            objectName: {
+                type: "string",
+                description: "API name of the object to query"
+            },
+            selectFields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Fields to select - mix of group fields and aggregates. Format: 'FieldName' or 'COUNT(Id) AliasName'"
+            },
+            groupByFields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Fields to group by - must include all non-aggregate fields from selectFields"
+            },
+            whereClause: {
+                type: "string",
+                description: "WHERE clause to filter rows BEFORE grouping (cannot contain aggregate functions)",
+                optional: true
+            },
+            havingClause: {
+                type: "string",
+                description: "HAVING clause to filter results AFTER grouping (use for aggregate conditions)",
+                optional: true
+            },
+            orderBy: {
+                type: "string",
+                description: "ORDER BY clause - can only use grouped fields or aggregate functions",
+                optional: true
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of grouped results to return",
+                optional: true
+            }
+        },
+        required: ["objectName", "selectFields", "groupByFields"]
+    }
+};
+// Aggregate functions that don't need to be in GROUP BY
+const AGGREGATE_FUNCTIONS = ['COUNT', 'COUNT_DISTINCT', 'SUM', 'AVG', 'MIN', 'MAX'];
+const DATE_FUNCTIONS = ['CALENDAR_YEAR', 'CALENDAR_MONTH', 'CALENDAR_QUARTER', 'FISCAL_YEAR', 'FISCAL_QUARTER'];
+// Helper function to detect if a field contains an aggregate function
+function isAggregateField(field) {
+    const upperField = field.toUpperCase();
+    return AGGREGATE_FUNCTIONS.some(func => upperField.includes(`${func}(`));
+}
+// Helper function to extract the base field from a select field (removing alias)
+function extractBaseField(field) {
+    // Remove alias if present (e.g., "COUNT(Id) OpportunityCount" -> "COUNT(Id)")
+    const parts = field.trim().split(/\s+/);
+    return parts[0];
+}
+// Helper function to extract non-aggregate fields from select fields
+function extractNonAggregateFields(selectFields) {
+    return selectFields
+        .filter(field => !isAggregateField(field))
+        .map(field => extractBaseField(field));
+}
+// Helper function to validate that all non-aggregate fields are in GROUP BY
+function validateGroupByFields(selectFields, groupByFields) {
+    const nonAggregateFields = extractNonAggregateFields(selectFields);
+    const groupBySet = new Set(groupByFields.map(f => f.trim()));
+    const missingFields = nonAggregateFields.filter(field => !groupBySet.has(field));
+    return {
+        isValid: missingFields.length === 0,
+        missingFields
+    };
+}
+// Helper function to validate WHERE clause doesn't contain aggregates
+function validateWhereClause(whereClause) {
+    if (!whereClause)
+        return { isValid: true };
+    const upperWhere = whereClause.toUpperCase();
+    for (const func of AGGREGATE_FUNCTIONS) {
+        if (upperWhere.includes(`${func}(`)) {
+            return {
+                isValid: false,
+                error: `WHERE clause cannot contain aggregate functions. Use HAVING clause instead for aggregate conditions like ${func}()`
+            };
+        }
+    }
+    return { isValid: true };
+}
+// Helper function to validate ORDER BY fields
+function validateOrderBy(orderBy, groupByFields, selectFields) {
+    if (!orderBy)
+        return { isValid: true };
+    // Extract fields from ORDER BY (handling DESC/ASC)
+    const orderByParts = orderBy.split(',').map(part => {
+        return part.trim().replace(/ (DESC|ASC)$/i, '').trim();
+    });
+    const groupBySet = new Set(groupByFields);
+    const aggregateFields = selectFields.filter(field => isAggregateField(field)).map(field => extractBaseField(field));
+    for (const orderField of orderByParts) {
+        // Check if it's in GROUP BY or is an aggregate
+        if (!groupBySet.has(orderField) && !aggregateFields.some(agg => agg === orderField) && !isAggregateField(orderField)) {
+            return {
+                isValid: false,
+                error: `ORDER BY field '${orderField}' must be in GROUP BY clause or be an aggregate function`
+            };
+        }
+    }
+    return { isValid: true };
+}
+export async function handleAggregateQuery(conn, args) {
+    const { objectName, selectFields, groupByFields, whereClause, havingClause, orderBy, limit } = args;
+    try {
+        // Validate GROUP BY contains all non-aggregate fields
+        const groupByValidation = validateGroupByFields(selectFields, groupByFields);
+        if (!groupByValidation.isValid) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: The following non-aggregate fields must be included in GROUP BY clause: ${groupByValidation.missingFields.join(', ')}\n\n` +
+                            `All fields in SELECT that are not aggregate functions (COUNT, SUM, AVG, etc.) must be included in GROUP BY.`
+                    }],
+                isError: true,
+            };
+        }
+        // Validate WHERE clause doesn't contain aggregates
+        const whereValidation = validateWhereClause(whereClause);
+        if (!whereValidation.isValid) {
+            return {
+                content: [{
+                        type: "text",
+                        text: whereValidation.error
+                    }],
+                isError: true,
+            };
+        }
+        // Validate ORDER BY fields
+        const orderByValidation = validateOrderBy(orderBy, groupByFields, selectFields);
+        if (!orderByValidation.isValid) {
+            return {
+                content: [{
+                        type: "text",
+                        text: orderByValidation.error
+                    }],
+                isError: true,
+            };
+        }
+        // Construct SOQL query
+        let soql = `SELECT ${selectFields.join(', ')} FROM ${objectName}`;
+        if (whereClause)
+            soql += ` WHERE ${whereClause}`;
+        soql += ` GROUP BY ${groupByFields.join(', ')}`;
+        if (havingClause)
+            soql += ` HAVING ${havingClause}`;
+        if (orderBy)
+            soql += ` ORDER BY ${orderBy}`;
+        if (limit)
+            soql += ` LIMIT ${limit}`;
+        const result = await conn.query(soql);
+        // Format the output
+        const formattedRecords = result.records.map((record, index) => {
+            const recordStr = selectFields.map(field => {
+                const baseField = extractBaseField(field);
+                const fieldParts = field.trim().split(/\s+/);
+                const displayName = fieldParts.length > 1 ? fieldParts[fieldParts.length - 1] : baseField;
+                // Handle nested fields in results
+                if (baseField.includes('.')) {
+                    const parts = baseField.split('.');
+                    let value = record;
+                    for (const part of parts) {
+                        value = value?.[part];
+                    }
+                    return `    ${displayName}: ${value !== null && value !== undefined ? value : 'null'}`;
+                }
+                const value = record[baseField] || record[displayName];
+                return `    ${displayName}: ${value !== null && value !== undefined ? value : 'null'}`;
+            }).join('\n');
+            return `Group ${index + 1}:\n${recordStr}`;
+        }).join('\n\n');
+        return {
+            content: [{
+                    type: "text",
+                    text: `Aggregate query returned ${result.records.length} grouped results:\n\n${formattedRecords}`
+                }],
+            isError: false,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide more helpful error messages for common issues
+        let enhancedError = errorMessage;
+        if (errorMessage.includes('MALFORMED_QUERY')) {
+            if (errorMessage.includes('GROUP BY')) {
+                enhancedError = `Query error: ${errorMessage}\n\nCommon issues:\n` +
+                    `1. Ensure all non-aggregate fields in SELECT are in GROUP BY\n` +
+                    `2. Check that date functions match exactly between SELECT and GROUP BY\n` +
+                    `3. Verify field names and relationships are correct`;
+            }
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error executing aggregate query: ${enhancedError}`
+                }],
+            isError: true,
+        };
+    }
+}

package/dist/tools/describe.d.ts

@@ -0,0 +1,9 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const DESCRIBE_OBJECT: Tool;
+export declare function handleDescribeObject(conn: any, objectName: string): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/tools/describe.js

@@ -0,0 +1,33 @@
+export const DESCRIBE_OBJECT = {
+    name: "salesforce_describe_object",
+    description: "Get detailed schema metadata including all fields, relationships, and field properties of any Salesforce object. Examples: 'Account' shows all Account fields including custom fields; 'Case' shows all Case fields including relationships to Account, Contact etc.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            objectName: {
+                type: "string",
+                description: "API name of the object (e.g., 'Account', 'Contact', 'Custom_Object__c')"
+            }
+        },
+        required: ["objectName"]
+    }
+};
+export async function handleDescribeObject(conn, objectName) {
+    const describe = await conn.describe(objectName);
+    // Format the output
+    const formattedDescription = `
+Object: ${describe.name} (${describe.label})${describe.custom ? ' (Custom Object)' : ''}
+Fields:
+${describe.fields.map((field) => `  - ${field.name} (${field.label})
+    Type: ${field.type}${field.length ? `, Length: ${field.length}` : ''}
+    Required: ${!field.nillable}
+    ${field.referenceTo && field.referenceTo.length > 0 ? `References: ${field.referenceTo.join(', ')}` : ''}
+    ${field.picklistValues && field.picklistValues.length > 0 ? `Picklist Values: ${field.picklistValues.map((v) => v.value).join(', ')}` : ''}`).join('\n')}`;
+    return {
+        content: [{
+                type: "text",
+                text: formattedDescription
+            }],
+        isError: false,
+    };
+}

package/dist/tools/dml.d.ts

@@ -0,0 +1,15 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const DML_RECORDS: Tool;
+export interface DMLArgs {
+    operation: 'insert' | 'update' | 'delete' | 'upsert';
+    objectName: string;
+    records: Record<string, any>[];
+    externalIdField?: string;
+}
+export declare function handleDMLRecords(conn: any, args: DMLArgs): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/tools/dml.js

@@ -0,0 +1,105 @@
+export const DML_RECORDS = {
+    name: "salesforce_dml_records",
+    description: `Perform data manipulation operations on Salesforce records:
+  - insert: Create new records
+  - update: Modify existing records (requires Id)
+  - delete: Remove records (requires Id)
+  - upsert: Insert or update based on external ID field
+  Examples: Insert new Accounts, Update Case status, Delete old records, Upsert based on custom external ID`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                type: "string",
+                enum: ["insert", "update", "delete", "upsert"],
+                description: "Type of DML operation to perform"
+            },
+            objectName: {
+                type: "string",
+                description: "API name of the object"
+            },
+            records: {
+                type: "array",
+                items: { type: "object" },
+                description: "Array of records to process"
+            },
+            externalIdField: {
+                type: "string",
+                description: "External ID field name for upsert operations",
+                optional: true
+            }
+        },
+        required: ["operation", "objectName", "records"]
+    }
+};
+export async function handleDMLRecords(conn, args) {
+    const { operation, objectName, records, externalIdField } = args;
+    let result;
+    switch (operation) {
+        case 'insert':
+            result = await conn.sobject(objectName).create(records);
+            break;
+        case 'update':
+            result = await conn.sobject(objectName).update(records);
+            break;
+        case 'delete':
+            result = await conn.sobject(objectName).destroy(records.map(r => r.Id));
+            break;
+        case 'upsert':
+            if (!externalIdField) {
+                throw new Error('externalIdField is required for upsert operations');
+            }
+            result = await conn.sobject(objectName).upsert(records, externalIdField);
+            break;
+        default:
+            throw new Error(`Unsupported operation: ${operation}`);
+    }
+    // Format DML results
+    const results = Array.isArray(result) ? result : [result];
+    const successCount = results.filter(r => r.success).length;
+    const failureCount = results.length - successCount;
+    let responseText = `${operation.toUpperCase()} operation completed.\n`;
+    responseText += `Processed ${results.length} records:\n`;
+    responseText += `- Successful: ${successCount}\n`;
+    responseText += `- Failed: ${failureCount}\n\n`;
+    if (failureCount > 0) {
+        responseText += 'Errors:\n';
+        results.forEach((r, idx) => {
+            if (!r.success && r.errors) {
+                responseText += `Record ${idx + 1}:\n`;
+                if (Array.isArray(r.errors)) {
+                    r.errors.forEach((error) => {
+                        responseText += `  - ${error.message}`;
+                        if (error.statusCode) {
+                            responseText += ` [${error.statusCode}]`;
+                        }
+                        if (error.fields && error.fields.length > 0) {
+                            responseText += `\n    Fields: ${error.fields.join(', ')}`;
+                        }
+                        responseText += '\n';
+                    });
+                }
+                else {
+                    // Single error object
+                    const error = r.errors;
+                    responseText += `  - ${error.message}`;
+                    if (error.statusCode) {
+                        responseText += ` [${error.statusCode}]`;
+                    }
+                    if (error.fields) {
+                        const fields = Array.isArray(error.fields) ? error.fields.join(', ') : error.fields;
+                        responseText += `\n    Fields: ${fields}`;
+                    }
+                    responseText += '\n';
+                }
+            }
+        });
+    }
+    return {
+        content: [{
+                type: "text",
+                text: responseText
+            }],
+        isError: false,
+    };
+}

package/dist/tools/executeAnonymous.d.ts

@@ -0,0 +1,25 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const EXECUTE_ANONYMOUS: Tool;
+export interface ExecuteAnonymousArgs {
+    apexCode: string;
+    logLevel?: 'NONE' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'FINE' | 'FINER' | 'FINEST';
+}
+/**
+ * Handles executing anonymous Apex code in Salesforce
+ * @param conn Active Salesforce connection
+ * @param args Arguments for executing anonymous Apex
+ * @returns Tool response with execution results and debug logs
+ */
+export declare function handleExecuteAnonymous(conn: any, args: ExecuteAnonymousArgs): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/tools/executeAnonymous.js

@@ -0,0 +1,130 @@
+export const EXECUTE_ANONYMOUS = {
+    name: "salesforce_execute_anonymous",
+    description: `Execute anonymous Apex code in Salesforce.
+  
+Examples:
+1. Execute simple Apex code:
+   {
+     "apexCode": "System.debug('Hello World');"
+   }
+
+2. Execute Apex code with variables:
+   {
+     "apexCode": "List<Account> accounts = [SELECT Id, Name FROM Account LIMIT 5]; for(Account a : accounts) { System.debug(a.Name); }"
+   }
+
+3. Execute Apex with debug logs:
+   {
+     "apexCode": "System.debug(LoggingLevel.INFO, 'Processing accounts...'); List<Account> accounts = [SELECT Id FROM Account LIMIT 10]; System.debug(LoggingLevel.INFO, 'Found ' + accounts.size() + ' accounts');",
+     "logLevel": "DEBUG"
+   }
+
+Notes:
+- The apexCode parameter is required and must contain valid Apex code
+- The code is executed in an anonymous context and does not persist
+- The logLevel parameter is optional (defaults to 'DEBUG')
+- Execution results include compilation success/failure, execution success/failure, and debug logs
+- For security reasons, some operations may be restricted based on user permissions
+- This tool can be used for data operations or updates when there are no other specific tools available
+- When users request data queries or updates that aren't directly supported by other tools, this tool can be used if the operation is achievable using Apex code
+`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            apexCode: {
+                type: "string",
+                description: "Apex code to execute anonymously"
+            },
+            logLevel: {
+                type: "string",
+                enum: ["NONE", "ERROR", "WARN", "INFO", "DEBUG", "FINE", "FINER", "FINEST"],
+                description: "Log level for debug logs (optional, defaults to DEBUG)"
+            }
+        },
+        required: ["apexCode"]
+    }
+};
+/**
+ * Handles executing anonymous Apex code in Salesforce
+ * @param conn Active Salesforce connection
+ * @param args Arguments for executing anonymous Apex
+ * @returns Tool response with execution results and debug logs
+ */
+export async function handleExecuteAnonymous(conn, args) {
+    try {
+        // Validate inputs
+        if (!args.apexCode || args.apexCode.trim() === '') {
+            throw new Error('apexCode is required and cannot be empty');
+        }
+        console.error(`Executing anonymous Apex code`);
+        // Set default log level if not provided
+        const logLevel = args.logLevel || 'DEBUG';
+        // Execute the anonymous Apex code
+        const result = await conn.tooling.executeAnonymous(args.apexCode);
+        // Format the response
+        let responseText = '';
+        // Add compilation and execution status
+        if (result.compiled) {
+            responseText += `**Compilation:** Success\n`;
+        }
+        else {
+            responseText += `**Compilation:** Failed\n`;
+            responseText += `**Line:** ${result.line}\n`;
+            responseText += `**Column:** ${result.column}\n`;
+            responseText += `**Error:** ${result.compileProblem}\n\n`;
+        }
+        if (result.compiled && result.success) {
+            responseText += `**Execution:** Success\n`;
+        }
+        else if (result.compiled) {
+            responseText += `**Execution:** Failed\n`;
+            responseText += `**Error:** ${result.exceptionMessage}\n`;
+            if (result.exceptionStackTrace) {
+                responseText += `**Stack Trace:**\n\`\`\`\n${result.exceptionStackTrace}\n\`\`\`\n\n`;
+            }
+        }
+        // Get debug logs if available
+        if (result.compiled) {
+            try {
+                // Query for the most recent debug log
+                const logs = await conn.query(`
+          SELECT Id, LogUserId, Operation, Application, Status, LogLength, LastModifiedDate, Request
+          FROM ApexLog 
+          ORDER BY LastModifiedDate DESC 
+          LIMIT 1
+        `);
+                if (logs.records.length > 0) {
+                    const logId = logs.records[0].Id;
+                    // Retrieve the log body
+                    const logBody = await conn.tooling.request({
+                        method: 'GET',
+                        url: `${conn.instanceUrl}/services/data/v58.0/tooling/sobjects/ApexLog/${logId}/Body`
+                    });
+                    responseText += `\n**Debug Log:**\n\`\`\`\n${logBody}\n\`\`\``;
+                }
+                else {
+                    responseText += `\n**Debug Log:** No logs available. Ensure debug logs are enabled for your user.`;
+                }
+            }
+            catch (logError) {
+                responseText += `\n**Debug Log:** Unable to retrieve debug logs: ${logError instanceof Error ? logError.message : String(logError)}`;
+            }
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: responseText
+                }]
+        };
+    }
+    catch (error) {
+        console.error('Error executing anonymous Apex:', error);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error executing anonymous Apex: ${error instanceof Error ? error.message : String(error)}`
+                }],
+            isError: true,
+        };
+    }
+}

package/dist/tools/manageDebugLogs.d.ts

@@ -0,0 +1,30 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const MANAGE_DEBUG_LOGS: Tool;
+export interface ManageDebugLogsArgs {
+    operation: 'enable' | 'disable' | 'retrieve';
+    username: string;
+    logLevel?: 'NONE' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'FINE' | 'FINER' | 'FINEST';
+    expirationTime?: number;
+    limit?: number;
+    logId?: string;
+    includeBody?: boolean;
+}
+/**
+ * Handles managing debug logs for Salesforce users
+ * @param conn Active Salesforce connection
+ * @param args Arguments for managing debug logs
+ * @returns Tool response with operation results
+ */
+export declare function handleManageDebugLogs(conn: any, args: ManageDebugLogsArgs): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;