46elks MCP Server

Instructions

Implementation Reference

• src/index.ts:36-64 (registration)

  Registration of the 'send_sms' MCP tool including input schema definition.

    name: 'send_sms',
    description: 'Send SMS message via 46elks',
    inputSchema: {
      type: 'object',
      properties: {
        to: {
          type: 'string',
          description: 'Recipient phone number with country code - MUST be a real phone number, not a placeholder (e.g., +46XXXXXXXXX for Swedish numbers)'
        },
        message: {
          type: 'string',
          description: 'SMS message content (max 160 characters for single SMS)'
        },
        from: {
          type: 'string',
          description: 'Sender phone number or name (optional, uses default if not specified)'
        },
        flashsms: {
          type: 'string',
          description: 'Set to "yes" for flash SMS that displays immediately and is not stored (optional)'
        },
        dry_run: {
          type: 'boolean',
          description: 'Test mode - verify request without sending actual SMS (optional, defaults to environment setting)'
        }
      },
      required: ['to', 'message']
    }
  },

• src/index.ts:157-197 (handler)

  MCP tool handler for 'send_sms': validates parameters, calls ElksClient.sendSms, formats and returns response.

  case 'send_sms':
    const { to, message, from, flashsms, dry_run } = args as {
      to: string;
      message: string;
      from?: string;
      flashsms?: string;
      dry_run?: boolean;
    };
  
    const isDryRunMode = dry_run !== undefined ? dry_run : config.dryRun;
  
    // Validate inputs
    handleValidationError('phone number', validatePhoneNumber(to));
    const messageValidation = validateSmsMessage(message);
    handleValidationError('message', messageValidation);
    if (from) {
      handleValidationError('sender ID', validateSenderId(from));
    }
  
    // Send SMS via 46elks
    const elksClient = new ElksClient();
    const response = await elksClient.sendSms(to, message, from, dry_run, flashsms);
    
    // Format response with validation warnings
    let responseText = formatSmsResponse(response, isDryRunMode);
    
    // Add validation warning if present
    if (messageValidation.warning) {
      responseText += `\n\n${messageValidation.warning}`;
    }
    
    
    return {
      content: [
        {
          type: 'text',
          text: responseText
        }
      ]
    };

• src/elks-client.ts:110-143 (handler)

  Core implementation of SMS sending: constructs API request to 46elks /sms endpoint and handles response.

  async sendSms(to: string, message: string, from?: string, dryRun?: boolean, flashsms?: string): Promise<SendSmsResponse> {
    const formData = new URLSearchParams({
      to,
      message,
      from: from || this.phoneNumber
    });
  
    // Add dry run parameter if enabled
    const isDryRun = dryRun !== undefined ? dryRun : this.dryRun;
    if (isDryRun) {
      formData.append('dryrun', 'yes');
    }
  
    // Add flash SMS parameter if specified
    if (flashsms === 'yes') {
      formData.append('flashsms', 'yes');
    }
  
    const response = await fetch(`${this.baseUrl}/sms`, {
      method: 'POST',
      headers: {
        'Authorization': this.auth,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: formData
    });
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Failed to send SMS: ${response.status} ${response.statusText} - ${errorText}`);
    }
  
    return await response.json();
  }

• src/elks-client.ts:14-24 (schema)

  TypeScript interface defining the response structure from sendSms API call.

  export interface SendSmsResponse {
    id: string;
    to: string;
    from: string;
    message: string;
    created: string;
    status: string;
    cost?: number;
    estimated_cost?: number;
    parts?: number;
  }

• src/utils.ts:6-31 (helper)

  Utility function to format the sendSms response into user-friendly text output for the MCP tool.

  export const formatSmsResponse = (response: SendSmsResponse, isDryRun: boolean): string => {
    const mode = isDryRun ? '🧪 DRY RUN' : '📱 SENT';
    const cost = response.estimated_cost ? 
      `Estimated cost: ${response.estimated_cost / 10000} SEK` : 
      response.cost ? `Cost: ${response.cost / 10000} SEK` : 'Cost: N/A';
  
    let output = `${mode} SMS Status: ${response.status}\n`;
    output += `To: ${response.to}\n`;
    output += `From: ${response.from}\n`;
    output += `Message: ${response.message}\n`;
    output += `${cost}\n`;
    
    if (response.parts) {
      output += `Message parts: ${response.parts}\n`;
    }
    
    if (response.id) {
      output += `Message ID: ${response.id}\n`;
    }
    
    if (isDryRun) {
      output += '\n⚠️  This was a test - no actual SMS was sent';
    }
  
    return output;
  };