ClickSend MCP Server

Instructions

Implementation Reference

• src/index.ts:130-146 (handler)

  MCP tool handler for 'make_tts_call': extracts arguments, validates parameters using validateTTSParams, calls ClickSendClient.makeTTSCall, and returns a text content response with the API result.

  case 'make_tts_call': {
    const { to, message, voice } = request.params.arguments as { 
      to: string; 
      message: string; 
      voice?: 'male' | 'female' 
    };
    validateTTSParams(to, message, voice);
    const result = await this.client.makeTTSCall({ to, message, voice });
    return {
      content: [
        {
          type: 'text',
          text: `TTS call initiated successfully: ${JSON.stringify(result)}`
        }
      ]
    };
  }

• src/index.ts:86-106 (schema)

  Input schema definition for the 'make_tts_call' tool, specifying properties for 'to', 'message', and optional 'voice' with types and requirements.

  inputSchema: {
    type: 'object',
    properties: {
      to: {
        type: 'string',
        description: 'Phone number in E.164 format'
      },
      message: {
        type: 'string',
        description: 'Text content to convert to speech'
      },
      voice: {
        type: 'string',
        enum: ['female', 'male'],
        default: 'female',
        description: 'Voice type for TTS'
      }
    },
    required: ['to', 'message'],
    additionalProperties: false
  }

• src/index.ts:83-107 (registration)

  Registration of the 'make_tts_call' tool in the ListTools response, including name, description, and full input schema.

  {
    name: 'make_tts_call',
    description: 'Make Text-to-Speech calls via ClickSend',
    inputSchema: {
      type: 'object',
      properties: {
        to: {
          type: 'string',
          description: 'Phone number in E.164 format'
        },
        message: {
          type: 'string',
          description: 'Text content to convert to speech'
        },
        voice: {
          type: 'string',
          enum: ['female', 'male'],
          default: 'female',
          description: 'Voice type for TTS'
        }
      },
      required: ['to', 'message'],
      additionalProperties: false
    }
  }

• src/client.ts:52-74 (helper)

  Core implementation of makeTTSCall in ClickSendClient: constructs TTS payload and sends POST request to ClickSend /voice/send endpoint, handles errors.

  async makeTTSCall(params: TTSMessage) {
    const payload = {
      messages: [
        {
          to: params.to,
          body: params.message,
          voice: params.voice || 'female',
          require_input: 0,
          machine_detection: 0
        }
      ]
    };
  
    try {
      const response = await this.client.post('/voice/send', payload);
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(`ClickSend API Error: ${error.response?.data?.message || error.message}`);
      }
      throw error;
    }
  }

• src/utils/validation.ts:28-38 (helper)

  Validation helper validateTTSParams: checks E.164 phone format, message length (1-1600 chars), and valid voice option ('male' or 'female').

  export function validateTTSParams(to: string, message: string, voice?: string): void {
    if (!validatePhoneNumber(to)) {
      throw new ValidationError('Invalid phone number format. Must be in E.164 format (e.g., +61423456789)');
    }
    if (!validateMessage(message)) {
      throw new ValidationError('Invalid message. Must be between 1 and 1600 characters');
    }
    if (voice && !['male', 'female'].includes(voice)) {
      throw new ValidationError('Invalid voice option. Must be either "male" or "female"');
    }
  }