Customer Registration MCP Server

Instructions

Implementation Reference

• src/index.ts:59-152 (registration)

  Tool registration in ListToolsRequestHandler: defines name, description, and detailed inputSchema for createCustomer.
  { name: 'createCustomer', description: 'Create a new customer in the external API. Requires name, email, and phone. Supports optional fields like address, UTM parameters, and more.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Customer full name (required)', }, email: { type: 'string', description: 'Customer email address (required)', }, phone: { type: 'string', description: 'Customer phone number (required)', }, retention: { type: 'boolean', description: 'Retention flag', }, identification: { type: 'string', description: 'Customer identification document (e.g., CPF)', }, zipcode: { type: 'string', description: 'ZIP/Postal code', }, state: { type: 'string', description: 'State/Province', }, street: { type: 'string', description: 'Street name', }, number: { type: 'string', description: 'Street number', }, neighborhood: { type: 'string', description: 'Neighborhood', }, city: { type: 'string', description: 'City', }, list_ids: { type: 'number', description: 'List ID for categorization', }, create_deal: { type: 'boolean', description: 'Whether to create a deal', }, tags: { type: 'string', description: 'Tags for the customer', }, url: { type: 'string', description: 'URL reference', }, utm_term: { type: 'string', description: 'UTM term parameter', }, utm_medium: { type: 'string', description: 'UTM medium parameter', }, utm_source: { type: 'string', description: 'UTM source parameter', }, utm_campaign: { type: 'string', description: 'UTM campaign parameter', }, company_id: { type: 'string', description: 'Company ID', }, utm_content: { type: 'string', description: 'UTM content parameter', }, }, required: ['name', 'email', 'phone'], }, },
• src/index.ts:190-221 (handler)

  MCP CallToolRequest handler for 'createCustomer': extracts arguments, validates required fields, calls CustomerService.createCustomer, and returns JSON result.
  if (request.params.name === 'createCustomer') { const customerData = request.params.arguments as Partial<CustomerData>; // Validate required fields const validation = this.customerService.validateRequiredFields(customerData); if (!validation.valid) { return { content: [ { type: 'text', text: JSON.stringify({ status: 'error', error: 'Validation failed', errors: validation.errors, }, null, 2), }, ], }; } // Create customer const result = await this.customerService.createCustomer(customerData as CustomerData); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/services/customerService.ts:56-101 (handler)

  CustomerService.createCustomer: the core handler logic that performs the HTTP POST request to the external customer API endpoint.
  async createCustomer(customerData: CustomerData): Promise<CustomerResponse> { const url = `${this.apiHost}/api/v1/customers`; try { this.log('Making POST request to:', url); this.log('Request payload:', customerData); const response = await axios.post(url, customerData, { headers: { 'Authorization': `Bearer ${this.apiToken}`, 'Content-Type': 'application/json', }, }); this.log('Response status:', response.status); this.log('Response data:', response.data); return { status: 'success', customerId: response.data.id || response.data.customerId, data: response.data, }; } catch (error) { if (axios.isAxiosError(error)) { const axiosError = error as AxiosError; this.log('API error:', { status: axiosError.response?.status, data: axiosError.response?.data, message: axiosError.message, }); return { status: 'error', error: axiosError.response?.data ? JSON.stringify(axiosError.response.data) : axiosError.message, statusCode: axiosError.response?.status, }; } this.log('Unexpected error:', error); return { status: 'error', error: error instanceof Error ? error.message : 'Unknown error occurred', }; }
• src/services/customerService.ts:3-25 (schema)

  CustomerData interface: TypeScript type definition for customer input data, matching the MCP tool's inputSchema.
  export interface CustomerData { name: string; email: string; phone: string; retention?: boolean; identification?: string; zipcode?: string; state?: string; street?: string; number?: string; neighborhood?: string; city?: string; list_ids?: number; create_deal?: boolean; tags?: string; url?: string; utm_term?: string; utm_medium?: string; utm_source?: string; utm_campaign?: string; company_id?: string; utm_content?: string; }
• src/services/customerService.ts:104-125 (helper)

  validateRequiredFields helper: Validates required fields (name, email, phone) and email format before creating customer.
  validateRequiredFields(data: Partial<CustomerData>): { valid: boolean; errors: string[] } { const errors: string[] = []; if (!data.name) { errors.push('name is required'); } if (!data.email) { errors.push('email is required'); } else if (!this.isValidEmail(data.email)) { errors.push('email format is invalid'); } if (!data.phone) { errors.push('phone is required'); } return { valid: errors.length === 0, errors, }; }