smartlead_list_leads

Instructions

Implementation Reference

• src/handlers/lead.ts:48-108 (handler)

  The handler function that executes the smartlead_list_leads tool: validates input with isListLeadsParams, builds URLSearchParams from optional filters, performs GET /leads API call with retry, returns JSON response or error.

  async function handleListLeads(
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isListLeadsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_list_leads'
      );
    }
  
    try {
      // Build query parameters from args
      const params = new URLSearchParams();
      if (args.campaign_id !== undefined) {
        params.append('campaign_id', args.campaign_id.toString());
      }
      if (args.status !== undefined) {
        params.append('status', args.status);
      }
      if (args.limit !== undefined) {
        params.append('limit', args.limit.toString());
      }
      if (args.offset !== undefined) {
        params.append('offset', args.offset.toString());
      }
      if (args.search !== undefined) {
        params.append('search', args.search);
      }
      if (args.start_date !== undefined) {
        params.append('start_date', args.start_date);
      }
      if (args.end_date !== undefined) {
        params.append('end_date', args.end_date);
      }
  
      const response = await withRetry(
        async () => apiClient.get('/leads', { params }),
        'list leads'
      );
  
      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/lead.ts:4-41 (schema)

  Tool definition including name, description, category (LEAD_MANAGEMENT), and detailed inputSchema for optional filtering parameters.

  export const LIST_LEADS_TOOL: CategoryTool = {
    name: 'smartlead_list_leads',
    description: 'List leads with optional filtering by campaign or status.',
    category: ToolCategory.LEAD_MANAGEMENT,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'Filter leads by campaign ID',
        },
        status: {
          type: 'string',
          description: 'Filter leads by status (e.g., "active", "unsubscribed", "bounced")',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of leads to return',
        },
        offset: {
          type: 'number',
          description: 'Offset for pagination',
        },
        search: {
          type: 'string',
          description: 'Search term to filter leads',
        },
        start_date: {
          type: 'string',
          description: 'Filter leads created after this date (YYYY-MM-DD format)',
        },
        end_date: {
          type: 'string',
          description: 'Filter leads created before this date (YYYY-MM-DD format)',
        },
      },
    },
  };

• src/index.ts:207-209 (registration)

  Registers the leadTools array (including smartlead_list_leads) to the toolRegistry if leadManagement category is enabled by license.

  if (enabledCategories.leadManagement) {
    toolRegistry.registerMany(leadTools);
  }

• src/index.ts:350-351 (registration)

  In the main CallToolRequest handler switch, dispatches LEAD_MANAGEMENT tools (including smartlead_list_leads) to handleLeadTool.

  case ToolCategory.LEAD_MANAGEMENT:
    return await handleLeadTool(name, toolArgs, apiClient, withRetry);

• src/types/lead.ts:70-113 (schema)

  Type guard function isListLeadsParams validates input arguments match ListLeadsParams interface with optional fields of correct types.

  export function isListLeadsParams(args: unknown): args is ListLeadsParams {
    if (typeof args !== 'object' || args === null) {
      return false;
    }
  
    const params = args as ListLeadsParams;
    
    // Optional campaign_id must be a number if present
    if (params.campaign_id !== undefined && typeof params.campaign_id !== 'number') {
      return false;
    }
    
    // Optional status must be a string if present
    if (params.status !== undefined && typeof params.status !== 'string') {
      return false;
    }
    
    // Optional limit must be a number if present
    if (params.limit !== undefined && typeof params.limit !== 'number') {
      return false;
    }
    
    // Optional offset must be a number if present
    if (params.offset !== undefined && typeof params.offset !== 'number') {
      return false;
    }
    
    // Optional search must be a string if present
    if (params.search !== undefined && typeof params.search !== 'string') {
      return false;
    }
    
    // Optional start_date must be a string if present
    if (params.start_date !== undefined && typeof params.start_date !== 'string') {
      return false;
    }
    
    // Optional end_date must be a string if present
    if (params.end_date !== undefined && typeof params.end_date !== 'string') {
      return false;
    }
    
    return true;
  }