@aaron-pienza/mcp-server-salesforce 1.0.0

package/dist/index.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as dotenv from "dotenv";
+import { createSalesforceConnection } from "./utils/connection.js";
+import { SEARCH_OBJECTS, handleSearchObjects } from "./tools/search.js";
+import { DESCRIBE_OBJECT, handleDescribeObject } from "./tools/describe.js";
+import { QUERY_RECORDS, handleQueryRecords } from "./tools/query.js";
+import { AGGREGATE_QUERY, handleAggregateQuery } from "./tools/aggregateQuery.js";
+import { DML_RECORDS, handleDMLRecords } from "./tools/dml.js";
+import { MANAGE_OBJECT, handleManageObject } from "./tools/manageObject.js";
+import { MANAGE_FIELD, handleManageField } from "./tools/manageField.js";
+import { MANAGE_FIELD_PERMISSIONS, handleManageFieldPermissions } from "./tools/manageFieldPermissions.js";
+import { SEARCH_ALL, handleSearchAll } from "./tools/searchAll.js";
+import { READ_APEX, handleReadApex } from "./tools/readApex.js";
+import { WRITE_APEX, handleWriteApex } from "./tools/writeApex.js";
+import { READ_APEX_TRIGGER, handleReadApexTrigger } from "./tools/readApexTrigger.js";
+import { WRITE_APEX_TRIGGER, handleWriteApexTrigger } from "./tools/writeApexTrigger.js";
+import { EXECUTE_ANONYMOUS, handleExecuteAnonymous } from "./tools/executeAnonymous.js";
+import { MANAGE_DEBUG_LOGS, handleManageDebugLogs } from "./tools/manageDebugLogs.js";
+import { LIST_ANALYTICS, handleListAnalytics } from "./tools/listAnalytics.js";
+import { DESCRIBE_ANALYTICS, handleDescribeAnalytics } from "./tools/describeAnalytics.js";
+import { RUN_ANALYTICS, handleRunAnalytics } from "./tools/runAnalytics.js";
+import { REFRESH_DASHBOARD, handleRefreshDashboard } from "./tools/refreshDashboard.js";
+import { REST_API, handleRestApi } from "./tools/restApi.js";
+// Load environment variables — quiet: true suppresses dotenv 17.x stderr logging
+// MCP servers require stdout to contain ONLY JSON-RPC messages
+dotenv.config({ quiet: true });
+const server = new Server({
+    name: "salesforce-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        SEARCH_OBJECTS,
+        DESCRIBE_OBJECT,
+        QUERY_RECORDS,
+        AGGREGATE_QUERY,
+        DML_RECORDS,
+        MANAGE_OBJECT,
+        MANAGE_FIELD,
+        MANAGE_FIELD_PERMISSIONS,
+        SEARCH_ALL,
+        READ_APEX,
+        WRITE_APEX,
+        READ_APEX_TRIGGER,
+        WRITE_APEX_TRIGGER,
+        EXECUTE_ANONYMOUS,
+        MANAGE_DEBUG_LOGS,
+        LIST_ANALYTICS,
+        DESCRIBE_ANALYTICS,
+        RUN_ANALYTICS,
+        REFRESH_DASHBOARD,
+        REST_API
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const { name, arguments: args } = request.params;
+        if (!args)
+            throw new Error('Arguments are required');
+        const conn = await createSalesforceConnection();
+        switch (name) {
+            case "salesforce_search_objects": {
+                const searchObjArgs = args;
+                if (!searchObjArgs.searchPattern)
+                    throw new Error('searchPattern is required');
+                const validatedArgs = {
+                    searchPattern: searchObjArgs.searchPattern,
+                    limit: searchObjArgs.limit,
+                    offset: searchObjArgs.offset,
+                };
+                return await handleSearchObjects(conn, validatedArgs);
+            }
+            case "salesforce_describe_object": {
+                const { objectName } = args;
+                if (!objectName)
+                    throw new Error('objectName is required');
+                return await handleDescribeObject(conn, objectName);
+            }
+            case "salesforce_query_records": {
+                const queryArgs = args;
+                if (!queryArgs.objectName || !Array.isArray(queryArgs.fields)) {
+                    throw new Error('objectName and fields array are required for query');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    objectName: queryArgs.objectName,
+                    fields: queryArgs.fields,
+                    whereClause: queryArgs.whereClause,
+                    orderBy: queryArgs.orderBy,
+                    limit: queryArgs.limit,
+                    offset: queryArgs.offset
+                };
+                return await handleQueryRecords(conn, validatedArgs);
+            }
+            case "salesforce_aggregate_query": {
+                const aggregateArgs = args;
+                if (!aggregateArgs.objectName || !Array.isArray(aggregateArgs.selectFields) || !Array.isArray(aggregateArgs.groupByFields)) {
+                    throw new Error('objectName, selectFields array, and groupByFields array are required for aggregate query');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    objectName: aggregateArgs.objectName,
+                    selectFields: aggregateArgs.selectFields,
+                    groupByFields: aggregateArgs.groupByFields,
+                    whereClause: aggregateArgs.whereClause,
+                    havingClause: aggregateArgs.havingClause,
+                    orderBy: aggregateArgs.orderBy,
+                    limit: aggregateArgs.limit
+                };
+                return await handleAggregateQuery(conn, validatedArgs);
+            }
+            case "salesforce_dml_records": {
+                const dmlArgs = args;
+                if (!dmlArgs.operation || !dmlArgs.objectName || !Array.isArray(dmlArgs.records)) {
+                    throw new Error('operation, objectName, and records array are required for DML');
+                }
+                const validatedArgs = {
+                    operation: dmlArgs.operation,
+                    objectName: dmlArgs.objectName,
+                    records: dmlArgs.records,
+                    externalIdField: dmlArgs.externalIdField
+                };
+                return await handleDMLRecords(conn, validatedArgs);
+            }
+            case "salesforce_manage_object": {
+                const objectArgs = args;
+                if (!objectArgs.operation || !objectArgs.objectName) {
+                    throw new Error('operation and objectName are required for object management');
+                }
+                const validatedArgs = {
+                    operation: objectArgs.operation,
+                    objectName: objectArgs.objectName,
+                    label: objectArgs.label,
+                    pluralLabel: objectArgs.pluralLabel,
+                    description: objectArgs.description,
+                    nameFieldLabel: objectArgs.nameFieldLabel,
+                    nameFieldType: objectArgs.nameFieldType,
+                    nameFieldFormat: objectArgs.nameFieldFormat,
+                    sharingModel: objectArgs.sharingModel
+                };
+                return await handleManageObject(conn, validatedArgs);
+            }
+            case "salesforce_manage_field": {
+                const fieldArgs = args;
+                if (!fieldArgs.operation || !fieldArgs.objectName || !fieldArgs.fieldName) {
+                    throw new Error('operation, objectName, and fieldName are required for field management');
+                }
+                const validatedArgs = {
+                    operation: fieldArgs.operation,
+                    objectName: fieldArgs.objectName,
+                    fieldName: fieldArgs.fieldName,
+                    label: fieldArgs.label,
+                    type: fieldArgs.type,
+                    required: fieldArgs.required,
+                    unique: fieldArgs.unique,
+                    externalId: fieldArgs.externalId,
+                    length: fieldArgs.length,
+                    precision: fieldArgs.precision,
+                    scale: fieldArgs.scale,
+                    referenceTo: fieldArgs.referenceTo,
+                    relationshipLabel: fieldArgs.relationshipLabel,
+                    relationshipName: fieldArgs.relationshipName,
+                    deleteConstraint: fieldArgs.deleteConstraint,
+                    picklistValues: fieldArgs.picklistValues,
+                    description: fieldArgs.description,
+                    grantAccessTo: fieldArgs.grantAccessTo
+                };
+                return await handleManageField(conn, validatedArgs);
+            }
+            case "salesforce_manage_field_permissions": {
+                const permArgs = args;
+                if (!permArgs.operation || !permArgs.objectName || !permArgs.fieldName) {
+                    throw new Error('operation, objectName, and fieldName are required for field permissions management');
+                }
+                const validatedArgs = {
+                    operation: permArgs.operation,
+                    objectName: permArgs.objectName,
+                    fieldName: permArgs.fieldName,
+                    profileNames: permArgs.profileNames,
+                    readable: permArgs.readable,
+                    editable: permArgs.editable
+                };
+                return await handleManageFieldPermissions(conn, validatedArgs);
+            }
+            case "salesforce_search_all": {
+                const searchArgs = args;
+                if (!searchArgs.searchTerm || !Array.isArray(searchArgs.objects)) {
+                    throw new Error('searchTerm and objects array are required for search');
+                }
+                // Validate objects array
+                const objects = searchArgs.objects;
+                if (!objects.every(obj => obj.name && Array.isArray(obj.fields))) {
+                    throw new Error('Each object must specify name and fields array');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    searchTerm: searchArgs.searchTerm,
+                    searchIn: searchArgs.searchIn,
+                    objects: objects.map(obj => ({
+                        name: obj.name,
+                        fields: obj.fields,
+                        where: obj.where,
+                        orderBy: obj.orderBy,
+                        limit: obj.limit
+                    })),
+                    withClauses: searchArgs.withClauses,
+                    updateable: searchArgs.updateable,
+                    viewable: searchArgs.viewable
+                };
+                return await handleSearchAll(conn, validatedArgs);
+            }
+            case "salesforce_read_apex": {
+                const apexArgs = args;
+                // Type check and conversion
+                const validatedArgs = {
+                    className: apexArgs.className,
+                    namePattern: apexArgs.namePattern,
+                    includeMetadata: apexArgs.includeMetadata,
+                    limit: apexArgs.limit,
+                    offset: apexArgs.offset
+                };
+                return await handleReadApex(conn, validatedArgs);
+            }
+            case "salesforce_write_apex": {
+                const apexArgs = args;
+                if (!apexArgs.operation || !apexArgs.className || !apexArgs.body) {
+                    throw new Error('operation, className, and body are required for writing Apex');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    operation: apexArgs.operation,
+                    className: apexArgs.className,
+                    apiVersion: apexArgs.apiVersion,
+                    body: apexArgs.body
+                };
+                return await handleWriteApex(conn, validatedArgs);
+            }
+            case "salesforce_read_apex_trigger": {
+                const triggerArgs = args;
+                // Type check and conversion
+                const validatedArgs = {
+                    triggerName: triggerArgs.triggerName,
+                    namePattern: triggerArgs.namePattern,
+                    includeMetadata: triggerArgs.includeMetadata,
+                    limit: triggerArgs.limit,
+                    offset: triggerArgs.offset
+                };
+                return await handleReadApexTrigger(conn, validatedArgs);
+            }
+            case "salesforce_write_apex_trigger": {
+                const triggerArgs = args;
+                if (!triggerArgs.operation || !triggerArgs.triggerName || !triggerArgs.body) {
+                    throw new Error('operation, triggerName, and body are required for writing Apex trigger');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    operation: triggerArgs.operation,
+                    triggerName: triggerArgs.triggerName,
+                    objectName: triggerArgs.objectName,
+                    apiVersion: triggerArgs.apiVersion,
+                    body: triggerArgs.body
+                };
+                return await handleWriteApexTrigger(conn, validatedArgs);
+            }
+            case "salesforce_execute_anonymous": {
+                const executeArgs = args;
+                if (!executeArgs.apexCode) {
+                    throw new Error('apexCode is required for executing anonymous Apex');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    apexCode: executeArgs.apexCode,
+                    logLevel: executeArgs.logLevel
+                };
+                return await handleExecuteAnonymous(conn, validatedArgs);
+            }
+            case "salesforce_manage_debug_logs": {
+                const debugLogsArgs = args;
+                if (!debugLogsArgs.operation || !debugLogsArgs.username) {
+                    throw new Error('operation and username are required for managing debug logs');
+                }
+                // Type check and conversion
+                const validatedArgs = {
+                    operation: debugLogsArgs.operation,
+                    username: debugLogsArgs.username,
+                    logLevel: debugLogsArgs.logLevel,
+                    expirationTime: debugLogsArgs.expirationTime,
+                    limit: debugLogsArgs.limit,
+                    logId: debugLogsArgs.logId,
+                    includeBody: debugLogsArgs.includeBody,
+                    offset: debugLogsArgs.offset
+                };
+                return await handleManageDebugLogs(conn, validatedArgs);
+            }
+            case "salesforce_list_analytics": {
+                const listAnalyticsArgs = args;
+                if (!listAnalyticsArgs.type) {
+                    throw new Error('type is required');
+                }
+                const validatedArgs = {
+                    type: listAnalyticsArgs.type,
+                    searchTerm: listAnalyticsArgs.searchTerm,
+                };
+                return await handleListAnalytics(conn, validatedArgs);
+            }
+            case "salesforce_describe_analytics": {
+                const descAnalyticsArgs = args;
+                if (!descAnalyticsArgs.type || !descAnalyticsArgs.resourceId) {
+                    throw new Error('type and resourceId are required');
+                }
+                const validatedArgs = {
+                    type: descAnalyticsArgs.type,
+                    resourceId: descAnalyticsArgs.resourceId,
+                };
+                return await handleDescribeAnalytics(conn, validatedArgs);
+            }
+            case "salesforce_run_analytics": {
+                const runAnalyticsArgs = args;
+                if (!runAnalyticsArgs.type || !runAnalyticsArgs.resourceId) {
+                    throw new Error('type and resourceId are required');
+                }
+                const validatedArgs = {
+                    type: runAnalyticsArgs.type,
+                    resourceId: runAnalyticsArgs.resourceId,
+                    includeDetails: runAnalyticsArgs.includeDetails,
+                    filters: runAnalyticsArgs.filters,
+                    booleanFilter: runAnalyticsArgs.booleanFilter,
+                    standardDateFilter: runAnalyticsArgs.standardDateFilter,
+                    topRows: runAnalyticsArgs.topRows,
+                };
+                return await handleRunAnalytics(conn, validatedArgs);
+            }
+            case "salesforce_refresh_dashboard": {
+                const refreshArgs = args;
+                if (!refreshArgs.operation || !refreshArgs.dashboardId) {
+                    throw new Error('operation and dashboardId are required');
+                }
+                const validatedArgs = {
+                    operation: refreshArgs.operation,
+                    dashboardId: refreshArgs.dashboardId,
+                };
+                return await handleRefreshDashboard(conn, validatedArgs);
+            }
+            case "salesforce_rest_api": {
+                const restArgs = args;
+                if (!restArgs.method || !restArgs.endpoint) {
+                    throw new Error('method and endpoint are required for REST API calls');
+                }
+                const validatedArgs = {
+                    method: restArgs.method,
+                    endpoint: restArgs.endpoint,
+                    body: restArgs.body,
+                    queryParameters: restArgs.queryParameters,
+                    apiVersion: restArgs.apiVersion,
+                    rawPath: restArgs.rawPath
+                };
+                return await handleRestApi(conn, validatedArgs);
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+            isError: true,
+        };
+    }
+});
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Salesforce MCP Server running on stdio");
+}
+runServer().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

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,275 @@
+import { DEFAULT_LIMITS } from "../utils/pagination.js";
+import { validateIdentifier } from "../utils/sanitize.js";
+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,
+            };
+        }
+        const objValidation = validateIdentifier(objectName);
+        if (!objValidation.valid) {
+            return { content: [{ type: "text", text: objValidation.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}`;
+        const effectiveLimit = limit ?? DEFAULT_LIMITS.aggregate;
+        soql += ` LIMIT ${effectiveLimit}`;
+        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 (e.g., Account.Industry in GROUP BY)
+                if (baseField.includes('.')) {
+                    // Strategy 1: Walk nested object (e.g., record.Account.Industry)
+                    const parts = baseField.split('.');
+                    let value = record;
+                    for (const part of parts) {
+                        value = value?.[part];
+                    }
+                    // Strategy 2: Flattened key (jsforce sometimes returns flat keys)
+                    if (value === null || value === undefined) {
+                        value = record[baseField];
+                    }
+                    // Strategy 3: Alias/display name
+                    if (value === null || value === undefined) {
+                        value = record[displayName];
+                    }
+                    // Strategy 4: Salesforce expr aliases (expr0, expr1, etc.)
+                    if (value === null || value === undefined) {
+                        const fieldIndex = selectFields.indexOf(field);
+                        value = record[`expr${fieldIndex}`];
+                    }
+                    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');
+        const totalSize = result.totalSize ?? result.records.length;
+        let text = `Aggregate query returned ${result.records.length} of ${totalSize} grouped results:\n\n${formattedRecords}`;
+        if (result.records.length < totalSize) {
+            text += `\n\nNote: Results are truncated (${result.records.length} of ${totalSize}). Narrow with WHERE/HAVING to see different slices (OFFSET is not supported with GROUP BY in Salesforce).`;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text,
+                }],
+            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,
+        };
+    }
+}