Smartlead Simplified MCP Server

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; }