Smartlead Simplified MCP Server

Instructions

Implementation Reference

• src/handlers/campaign.ts:110-148 (handler)

  Core execution logic: validates args with isUpdateCampaignScheduleParams, posts to /campaigns/{campaign_id}/schedule API endpoint using axios, handles retry and returns JSON response or formatted error.

  async function handleUpdateCampaignSchedule(
    args: unknown, 
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isUpdateCampaignScheduleParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_update_campaign_schedule'
      );
    }
  
    const { campaign_id, ...scheduleParams } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.post(`/campaigns/${campaign_id}/schedule`, scheduleParams),
        'update campaign schedule'
      );
  
      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:24-67 (schema)

  MCP tool definition with name, description, category, and JSON inputSchema defining parameters for campaign schedule update.

  export const UPDATE_CAMPAIGN_SCHEDULE_TOOL: CategoryTool = {
    name: 'smartlead_update_campaign_schedule',
    description: 'Update a campaign\'s schedule settings.',
    category: ToolCategory.CAMPAIGN_MANAGEMENT,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to update',
        },
        timezone: {
          type: 'string',
          description: 'Timezone for the campaign (e.g., "America/Los_Angeles")',
        },
        days_of_the_week: {
          type: 'array',
          items: { type: 'number' },
          description: 'Days of the week to send emails (1-7, where 1 is Monday)',
        },
        start_hour: {
          type: 'string',
          description: 'Start hour in 24-hour format (e.g., "09:00")',
        },
        end_hour: {
          type: 'string',
          description: 'End hour in 24-hour format (e.g., "17:00")',
        },
        min_time_btw_emails: {
          type: 'number',
          description: 'Minimum time between emails in minutes',
        },
        max_new_leads_per_day: {
          type: 'number',
          description: 'Maximum number of new leads per day',
        },
        schedule_start_time: {
          type: 'string',
          description: 'Schedule start time in ISO format',
        },
      },
      required: ['campaign_id'],
    },
  };

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

  Registers the array of campaign tools (including this one via campaignTools export) to the tool registry if feature enabled.

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

• src/types/campaign.ts:8-108 (schema)

  TypeScript interface and type guard validator used for runtime input validation in the handler, matching the inputSchema.

  export interface UpdateCampaignScheduleParams {
    campaign_id: number;
    timezone?: string;
    days_of_the_week?: number[];
    start_hour?: string;
    end_hour?: string;
    min_time_btw_emails?: number;
    max_new_leads_per_day?: number;
    schedule_start_time?: string;
  }
  
  export interface UpdateCampaignSettingsParams {
    campaign_id: number;
    name?: string;
    status?: 'active' | 'paused' | 'completed';
    settings?: Record<string, any>;
  }
  
  export interface UpdateCampaignStatusParams {
    campaign_id: number;
    status: 'PAUSED' | 'STOPPED' | 'START';
  }
  
  export interface GetCampaignParams {
    campaign_id: number;
  }
  
  export interface GetCampaignSequenceParams {
    campaign_id: number;
  }
  
  export interface ListCampaignsParams {
    status?: 'active' | 'paused' | 'completed';
    limit?: number;
    offset?: number;
  }
  
  export interface SaveCampaignSequenceParams {
    campaign_id: number;
    sequence: Array<{
      seq_number: number;
      seq_delay_details: {
        delay_in_days: number;
      };
      variant_distribution_type: 'MANUAL_EQUAL' | 'MANUAL_PERCENTAGE' | 'AI_EQUAL';
      lead_distribution_percentage?: number;
      winning_metric_property?: 'OPEN_RATE' | 'CLICK_RATE' | 'REPLY_RATE' | 'POSITIVE_REPLY_RATE';
      seq_variants: Array<{
        subject: string;
        email_body: string;
        variant_label: string;
        id?: number;
        variant_distribution_percentage?: number;
      }>;
    }>;
  }
  
  // New interface definitions for remaining campaign management endpoints
  export interface GetCampaignsByLeadParams {
    lead_id: number;
  }
  
  export interface ExportCampaignLeadsParams {
    campaign_id: number;
  }
  
  export interface DeleteCampaignParams {
    campaign_id: number;
  }
  
  export interface GetCampaignAnalyticsByDateParams {
    campaign_id: number;
    start_date: string;
    end_date: string;
  }
  
  export interface GetCampaignSequenceAnalyticsParams {
    campaign_id: number;
    start_date: string;
    end_date: string;
    time_zone?: string;
  }
  
  // Type guards
  export function isCreateCampaignParams(args: unknown): args is CreateCampaignParams {
    return (
      typeof args === 'object' &&
      args !== null &&
      'name' in args &&
      typeof (args as { name: unknown }).name === 'string'
    );
  }
  
  export function isUpdateCampaignScheduleParams(args: unknown): args is UpdateCampaignScheduleParams {
    return (
      typeof args === 'object' &&
      args !== null &&
      'campaign_id' in args &&
      typeof (args as { campaign_id: unknown }).campaign_id === 'number'
    );
  }

• src/handlers/campaign.ts:30-31 (handler)

  Switch case in main campaign handler that delegates to the specific handleUpdateCampaignSchedule function.

  case 'smartlead_update_campaign_schedule': {
    return handleUpdateCampaignSchedule(args, apiClient, withRetry);