Smartlead Simplified MCP Server

Instructions

Implementation Reference

• src/handlers/statistics.ts:182-220 (handler)

  Executes the tool logic: validates parameters using isCampaignTopLevelAnalyticsParams, calls Smartlead API endpoint `/campaigns/${campaign_id}/analytics`, returns JSON response or formatted error.

  async function handleCampaignTopLevelAnalytics(
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isCampaignTopLevelAnalyticsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_get_campaign_top_level_analytics'
      );
    }
  
    const { campaign_id } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.get(`/campaigns/${campaign_id}/analytics`),
        'get campaign top level 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/statistics.ts:84-98 (schema)

  MCP tool definition including name, description, category, and JSON schema for input validation (requires campaign_id).

  export const CAMPAIGN_TOP_LEVEL_ANALYTICS_TOOL: CategoryTool = {
    name: 'smartlead_get_campaign_top_level_analytics',
    description: 'Fetch top level analytics for a campaign.',
    category: ToolCategory.CAMPAIGN_STATISTICS,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to fetch analytics for',
        },
      },
      required: ['campaign_id'],
    },
  };

• src/index.ts:212-214 (registration)

  Registers the array of statistics tools (including this one) via toolRegistry.registerMany(statisticsTools) when campaignStatistics feature is enabled.

  if (enabledCategories.campaignStatistics) {
    toolRegistry.registerMany(statisticsTools);
  }

• src/types/statistics.ts:142-150 (schema)

  TypeScript type guard for runtime input validation, ensuring args is an object with numeric campaign_id.

  export function isCampaignTopLevelAnalyticsParams(args: unknown): args is CampaignTopLevelAnalyticsParams {
    if (typeof args !== 'object' || args === null) {
      return false;
    }
  
    const params = args as CampaignTopLevelAnalyticsParams;
    
    return typeof params.campaign_id === 'number';
  }

• src/tools/statistics.ts:250-260 (registration)

  The statisticsTools export array that includes this tool's CategoryTool definition for bulk registration.

  export const statisticsTools: CategoryTool[] = [
    CAMPAIGN_STATISTICS_TOOL,
    CAMPAIGN_STATISTICS_BY_DATE_TOOL,
    WARMUP_STATS_BY_EMAIL_TOOL,
    CAMPAIGN_TOP_LEVEL_ANALYTICS_TOOL,
    CAMPAIGN_TOP_LEVEL_ANALYTICS_BY_DATE_TOOL,
    CAMPAIGN_LEAD_STATISTICS_TOOL,
    CAMPAIGN_MAILBOX_STATISTICS_TOOL,
    DOWNLOAD_CAMPAIGN_DATA_TOOL,
    VIEW_DOWNLOAD_STATISTICS_TOOL,
  ];