46elks MCP Server

Instructions

Implementation Reference

• src/index.ts:326-345 (handler)

  Executes the get_delivery_statistics tool by fetching recent outbound messages and formatting delivery statistics.

  case 'get_delivery_statistics':
    const { limit: statsLimit = 50 } = args as {
      limit?: number;
    };
  
    // Validate and constrain limit
    const analysisLimit = Math.min(Math.max(statsLimit, 10), 100);
    
    // Get messages for analysis - only outbound messages matter for delivery stats
    const elksClientForStats = new ElksClient();
    const messagesForStats = await elksClientForStats.getMessages(analysisLimit);
    
    return {
      content: [
        {
          type: 'text',
          text: formatDeliveryStatistics(messagesForStats)
        }
      ]
    };

• src/index.ts:131-146 (registration)

  Registers the get_delivery_statistics tool with the MCP server, including input schema definition.

  {
    name: 'get_delivery_statistics',
    description: 'Get SMS delivery statistics and success rates from recent messages',
    inputSchema: {
      type: 'object',
      properties: {
        limit: {
          type: 'number',
          description: 'Number of recent messages to analyze for statistics (default: 50, max: 100)',
          minimum: 10,
          maximum: 100
        }
      },
      required: []
    }
  }

• src/utils.ts:92-150 (helper)

  Core utility function that analyzes outbound messages to compute delivery success rates, total/average costs, status breakdowns, and provides performance recommendations.

  export const formatDeliveryStatistics = (messages: ElksMessage[]): string => {
    if (messages.length === 0) {
      return '📊 No messages found to analyze';
    }
  
    // Filter only outbound messages (we can't analyze delivery for inbound)
    const outboundMessages = messages.filter(msg => msg.direction === 'outbound');
    
    if (outboundMessages.length === 0) {
      return '📊 No outbound messages found to analyze delivery statistics';
    }
  
    // Count messages by status
    const statusCounts = outboundMessages.reduce((counts, msg) => {
      counts[msg.status] = (counts[msg.status] || 0) + 1;
      return counts;
    }, {} as Record<string, number>);
  
    // Calculate costs
    const totalCost = outboundMessages
      .filter(msg => msg.cost)
      .reduce((sum, msg) => sum + (msg.cost || 0), 0) / 10000;
  
    const averageCost = totalCost / Math.max(outboundMessages.filter(msg => msg.cost).length, 1);
  
    // Calculate success rate
    const deliveredCount = statusCounts.delivered || 0;
    const sentCount = statusCounts.sent || 0;
    const successfulMessages = deliveredCount + sentCount;
    const successRate = Math.round((successfulMessages / outboundMessages.length) * 100);
  
    // Build statistics output
    let output = `📊 SMS Delivery Statistics\n\n`;
    output += `📈 Summary (Last ${outboundMessages.length} outbound messages)\n`;
    output += `Success Rate: ${successRate}% (${successfulMessages}/${outboundMessages.length})\n`;
    output += `Total Cost: ${totalCost.toFixed(2)} SEK\n`;
    output += `Average Cost: ${averageCost.toFixed(2)} SEK per SMS\n\n`;
  
    output += `📋 Message Status Breakdown:\n`;
    Object.entries(statusCounts).forEach(([status, count]) => {
      const percentage = Math.round((count / outboundMessages.length) * 100);
      const statusEmoji = getStatusEmoji(status);
      output += `${statusEmoji} ${status}: ${count} (${percentage}%)\n`;
    });
  
    output += `\n📅 Analysis Period: ${new Date(outboundMessages[outboundMessages.length - 1].created).toLocaleDateString()} - ${new Date(outboundMessages[0].created).toLocaleDateString()}`;
  
    // Add recommendations
    if (successRate < 90) {
      output += `\n\n⚠️  Low success rate detected. Consider:\n`;
      output += `• Verifying phone number formats\n`;
      output += `• Checking message content for blocked words\n`;
      output += `• Ensuring recipient numbers are active`;
    } else {
      output += `\n\n✅ Good delivery performance!`;
    }
  
    return output;
  };