Smartlead Simplified MCP Server

Instructions

Implementation Reference

• src/handlers/campaign.ts:543-582 (handler)

  The core handler function that validates the input parameters using isGetCampaignSequenceAnalyticsParams, makes an authenticated GET request to the Smartlead API endpoint `/campaigns/{campaign_id}/sequence-analytics` with date range and timezone parameters, formats the response as JSON text, and handles errors appropriately.

  async function handleGetCampaignSequenceAnalytics(
    args: unknown, 
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isGetCampaignSequenceAnalyticsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_get_campaign_sequence_analytics'
      );
    }
  
    const { campaign_id, ...params } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.get(`/campaigns/${campaign_id}/sequence-analytics`, { 
          params 
        }),
        'get campaign sequence analytics'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error: any) {
      return {
        content: [{ 
          type: 'text', 
          text: `API Error: ${error.response?.data?.message || error.message}` 
        }],
        isError: true,
      };
    }

• src/tools/campaign.ts:331-357 (schema)

  Defines the tool metadata including name, description, category, and detailed input schema (JSON Schema) for validation, specifying required campaign_id, start_date, end_date, and optional time_zone.

  export const GET_CAMPAIGN_SEQUENCE_ANALYTICS_TOOL: CategoryTool = {
    name: 'smartlead_get_campaign_sequence_analytics',
    description: 'Fetch analytics data for a specific email campaign sequence.',
    category: ToolCategory.CAMPAIGN_MANAGEMENT,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to fetch sequence analytics for',
        },
        start_date: {
          type: 'string',
          description: 'Start date in YYYY-MM-DD HH:MM:SS format',
        },
        end_date: {
          type: 'string',
          description: 'End date in YYYY-MM-DD HH:MM:SS format',
        },
        time_zone: {
          type: 'string',
          description: 'Timezone for the analytics data (e.g., "Europe/London")',
        },
      },
      required: ['campaign_id', 'start_date', 'end_date'],
    },
  };

• src/types/campaign.ts:210-221 (schema)

  Runtime type guard function that validates input arguments match the GetCampaignSequenceAnalyticsParams interface, checking for required properties with correct types.

  export function isGetCampaignSequenceAnalyticsParams(args: unknown): args is GetCampaignSequenceAnalyticsParams {
    return (
      typeof args === 'object' &&
      args !== null &&
      'campaign_id' in args &&
      typeof (args as { campaign_id: unknown }).campaign_id === 'number' &&
      'start_date' in args &&
      typeof (args as { start_date: unknown }).start_date === 'string' &&
      'end_date' in args &&
      typeof (args as { end_date: unknown }).end_date === 'string'
    );
  }

• src/index.ts:197-199 (registration)

  Registers the array of campaign tools (including smartlead_get_campaign_sequence_analytics) to the tool registry if the campaignManagement category is enabled by license/features.

  if (enabledCategories.campaignManagement) {
    toolRegistry.registerMany(campaignTools);
  }

• src/handlers/campaign.ts:63-65 (registration)

  Switch case in handleCampaignTool that dispatches execution to the specific handler function for this tool name.

  case 'smartlead_get_campaign_sequence_analytics': {
    return handleGetCampaignSequenceAnalytics(args, apiClient, withRetry);
  }