Smartlead Simplified MCP Server

Instructions

Implementation Reference

• src/handlers/campaign.ts:306-344 (handler)

  The handler function that executes the tool: validates input using isSaveCampaignSequenceParams, sends POST request to `/campaigns/${campaign_id}/sequences` with the sequence data, and returns the API response or error.

  async function handleSaveCampaignSequence(
    args: unknown, 
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isSaveCampaignSequenceParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_save_campaign_sequence'
      );
    }
  
    const { campaign_id, sequence } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.post(`/campaigns/${campaign_id}/sequences`, { sequence }),
        'save campaign sequence'
      );
  
      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:159-237 (schema)

  Defines the tool metadata including name, description, category, and detailed inputSchema for validation in MCP protocol.

  export const SAVE_CAMPAIGN_SEQUENCE_TOOL: CategoryTool = {
    name: 'smartlead_save_campaign_sequence',
    description: 'Save a sequence of emails for a campaign.',
    category: ToolCategory.CAMPAIGN_MANAGEMENT,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign',
        },
        sequence: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              seq_number: {
                type: 'number',
                description: 'The sequence number (order) of this email',
              },
              seq_delay_details: {
                type: 'object',
                properties: {
                  delay_in_days: {
                    type: 'number',
                    description: 'Days to wait before sending this email',
                  }
                },
                description: 'Delay details for this sequence'
              },
              variant_distribution_type: {
                type: 'string',
                enum: ['MANUAL_EQUAL', 'MANUAL_PERCENTAGE', 'AI_EQUAL'],
                description: 'How to distribute variants'
              },
              lead_distribution_percentage: {
                type: 'number',
                description: 'What sample % size of the lead pool to use to find the winner (for AI_EQUAL)'
              },
              winning_metric_property: {
                type: 'string',
                enum: ['OPEN_RATE', 'CLICK_RATE', 'REPLY_RATE', 'POSITIVE_REPLY_RATE'],
                description: 'Metric to use for determining the winning variant (for AI_EQUAL)'
              },
              seq_variants: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    subject: {
                      type: 'string',
                      description: 'Email subject line',
                    },
                    email_body: {
                      type: 'string',
                      description: 'Email body content in HTML',
                    },
                    variant_label: {
                      type: 'string',
                      description: 'Label for this variant (A, B, C, etc.)',
                    },
                    variant_distribution_percentage: {
                      type: 'number',
                      description: 'Percentage of leads to receive this variant (for MANUAL_PERCENTAGE)'
                    }
                  },
                  required: ['subject', 'email_body', 'variant_label'],
                },
                description: 'Variants of the email in this sequence'
              }
            },
            required: ['seq_number', 'seq_delay_details', 'variant_distribution_type', 'seq_variants'],
          },
          description: 'Sequence of emails to send',
        },
      },
      required: ['campaign_id', 'sequence'],
    },
  };

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

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

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

• src/types/campaign.ts:153-167 (schema)

  Type guard function used by the handler to validate input arguments against SaveCampaignSequenceParams interface.

  export function isSaveCampaignSequenceParams(args: unknown): args is SaveCampaignSequenceParams {
    if (
      typeof args !== 'object' ||
      args === null ||
      !('campaign_id' in args) ||
      typeof (args as { campaign_id: unknown }).campaign_id !== 'number' ||
      !('sequence' in args) ||
      !Array.isArray((args as { sequence: unknown }).sequence)
    ) {
      return false;
    }
  
    const sequence = (args as { sequence: unknown[] }).sequence;
    return sequence.every(isValidSequenceItem);
  }

• src/types/campaign.ts:223-250 (helper)

  Helper function used by isSaveCampaignSequenceParams to deeply validate each item in the sequence array.

  function isValidSequenceItem(item: unknown): boolean {
    return (
      typeof item === 'object' &&
      item !== null &&
      'seq_number' in item &&
      typeof (item as { seq_number: unknown }).seq_number === 'number' &&
      'seq_delay_details' in item &&
      typeof (item as { seq_delay_details: unknown }).seq_delay_details === 'object' &&
      (item as { seq_delay_details: unknown }).seq_delay_details !== null &&
      'delay_in_days' in (item as { seq_delay_details: { delay_in_days: unknown } }).seq_delay_details &&
      typeof (item as { seq_delay_details: { delay_in_days: unknown } }).seq_delay_details.delay_in_days === 'number' &&
      'variant_distribution_type' in item &&
      typeof (item as { variant_distribution_type: unknown }).variant_distribution_type === 'string' &&
      'seq_variants' in item &&
      Array.isArray((item as { seq_variants: unknown[] }).seq_variants) &&
      (item as { seq_variants: unknown[] }).seq_variants.every(
        (variant) =>
          typeof variant === 'object' &&
          variant !== null &&
          'subject' in variant &&
          typeof (variant as { subject: unknown }).subject === 'string' &&
          'email_body' in variant &&
          typeof (variant as { email_body: unknown }).email_body === 'string' &&
          'variant_label' in variant &&
          typeof (variant as { variant_label: unknown }).variant_label === 'string'
      )
    );
  }