whatsapp-sender-pro-mcp 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# WhatsApp Sender Pro MCP Server
+
+[![npm version](https://badge.fury.io/js/whatsapp-sender-pro-mcp.svg)](https://www.npmjs.com/package/whatsapp-sender-pro-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Model Context Protocol (MCP) server for WhatsApp Sender Pro. This allows AI assistants like Claude to send WhatsApp messages, manage contacts, and run marketing campaigns on your behalf.
+
+**Website:** https://whatsappsender.speedliv.com
+**Chrome Extension:** [Install from Chrome Web Store](https://chromewebstore.google.com/detail/whatsapp-sender-pro/akaajmihnfkohfcpbohmephlldmlibok)
+
+## Features
+
+### Tools
+- **send_whatsapp_message** - Send a message to a single contact
+- **send_bulk_messages** - Send messages to multiple contacts with human-like delays
+- **get_contacts** - Retrieve your saved contacts
+- **add_contact** - Add a new contact
+- **import_contacts** - Import multiple contacts at once
+- **get_message_history** - View sent messages and their status
+- **get_credits_balance** - Check your credits balance
+- **get_analytics** - View messaging statistics
+- **create_message_template** - Create reusable templates
+- **authenticate** - Login to your account
+
+### Resources
+- `whatsapp://contacts` - All saved contacts
+- `whatsapp://templates` - Message templates
+- `whatsapp://stats` - Usage statistics
+- `whatsapp://account` - Account information
+
+### Prompts
+- **send_marketing_campaign** - Create and send marketing campaigns
+- **send_appointment_reminder** - Send appointment reminders
+- **customer_followup** - Follow up with customers after purchase
+- **event_invitation** - Send event invitations
+
+## Installation
+
+### Option 1: NPX (No installation required)
+```bash
+npx whatsapp-sender-pro-mcp
+```
+
+### Option 2: NPM Global Install
+```bash
+npm install -g whatsapp-sender-pro-mcp
+whatsapp-sender-mcp
+```
+
+### Option 3: From Source
+```bash
+git clone https://github.com/whatsapp-sender-pro/mcp-server
+cd mcp-server
+npm install
+npm start
+```
+
+## Configuration
+
+### For Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "whatsapp-sender": {
+      "command": "npx",
+      "args": ["whatsapp-sender-pro-mcp"],
+      "env": {
+        "WHATSAPP_API_URL": "https://whatsapp-backend-prod.worksaas.workers.dev"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+```json
+{
+  "mcpServers": {
+    "whatsapp-sender": {
+      "command": "whatsapp-sender-mcp",
+      "env": {
+        "WHATSAPP_API_URL": "https://whatsapp-backend-prod.worksaas.workers.dev"
+      }
+    }
+  }
+}
+```
+
+### For Claude Code
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "whatsapp-sender": {
+      "command": "npx",
+      "args": ["whatsapp-sender-pro-mcp"],
+      "env": {
+        "WHATSAPP_API_URL": "https://whatsapp-backend-prod.worksaas.workers.dev"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### Authenticate First
+```
+Use the authenticate tool with my email and password to login
+```
+
+### Send a Single Message
+```
+Send a WhatsApp message to +1234567890 saying "Hello! Thanks for your interest in our product."
+```
+
+### Send Bulk Campaign
+```
+Get my contacts and send a promotional message about our 20% holiday sale to all of them
+```
+
+### Check Analytics
+```
+Show me my messaging statistics for the past week
+```
+
+### Use a Prompt
+```
+Use the send_marketing_campaign prompt to promote our new fitness app with a 30-day free trial offer
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `WHATSAPP_API_URL` | API server URL | `https://whatsapp-backend-prod.worksaas.workers.dev` |
+| `WHATSAPP_API_TOKEN` | JWT authentication token | None (use authenticate tool) |
+
+## Security
+
+- Never share your API token
+- The MCP server runs locally and communicates with the WhatsApp Sender API
+- All messages are sent through your authenticated account
+- Credits are deducted per message sent
+
+## Support
+
+- Website: https://whatsappsender.speedliv.com
+- Chrome Extension: https://chromewebstore.google.com/detail/whatsapp-sender-pro/akaajmihnfkohfcpbohmephlldmlibok
+- Email: support@speedliv.com
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "whatsapp-sender-pro-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for WhatsApp Sender Pro - Send bulk WhatsApp messages via AI assistants like Claude",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "whatsapp-sender-mcp": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "prepublishOnly": "chmod +x src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whatsapp",
+    "whatsapp-sender",
+    "bulk-messaging",
+    "whatsapp-automation",
+    "claude",
+    "anthropic",
+    "ai",
+    "llm",
+    "marketing",
+    "messaging"
+  ],
+  "author": "WhatsApp Sender Pro <support@speedliv.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/whatsapp-sender-pro/mcp-server"
+  },
+  "homepage": "https://whatsappsender.speedliv.com",
+  "bugs": {
+    "url": "https://github.com/whatsapp-sender-pro/mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// API Configuration
+const API_BASE_URL = process.env.WHATSAPP_API_URL || "https://whatsapp-backend-prod.worksaas.workers.dev";
+let API_TOKEN = process.env.WHATSAPP_API_TOKEN || "";
+
+// Helper function for API calls
+async function apiCall(endpoint, method = "GET", body = null) {
+  const headers = {
+    "Content-Type": "application/json",
+  };
+
+  if (API_TOKEN) {
+    headers["Authorization"] = `Bearer ${API_TOKEN}`;
+  }
+
+  const options = {
+    method,
+    headers,
+  };
+
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(`${API_BASE_URL}${endpoint}`, options);
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`API Error: ${response.status} - ${error}`);
+  }
+
+  return response.json();
+}
+
+// Create MCP Server
+const server = new Server(
+  {
+    name: "whatsapp-sender-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+    },
+  }
+);
+
+// ==================== TOOLS ====================
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "send_whatsapp_message",
+        description: "Send a WhatsApp message to a single contact. Requires phone number and message content.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            phone: {
+              type: "string",
+              description: "Phone number with country code (e.g., +1234567890)",
+            },
+            message: {
+              type: "string",
+              description: "Message content to send",
+            },
+            contactName: {
+              type: "string",
+              description: "Optional name of the contact",
+            },
+          },
+          required: ["phone", "message"],
+        },
+      },
+      {
+        name: "send_bulk_messages",
+        description: "Send WhatsApp messages to multiple contacts at once. Uses human-like delays to prevent bans.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            contacts: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  phone: { type: "string" },
+                  name: { type: "string" },
+                },
+                required: ["phone"],
+              },
+              description: "Array of contacts with phone numbers",
+            },
+            message: {
+              type: "string",
+              description: "Message template. Use {name} for personalization.",
+            },
+            minDelay: {
+              type: "number",
+              description: "Minimum delay between messages in seconds (default: 3)",
+            },
+            maxDelay: {
+              type: "number",
+              description: "Maximum delay between messages in seconds (default: 8)",
+            },
+          },
+          required: ["contacts", "message"],
+        },
+      },
+      {
+        name: "get_contacts",
+        description: "Retrieve all saved contacts from WhatsApp Sender Pro",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Maximum number of contacts to retrieve (default: 100)",
+            },
+            search: {
+              type: "string",
+              description: "Search term to filter contacts by name or phone",
+            },
+          },
+        },
+      },
+      {
+        name: "add_contact",
+        description: "Add a new contact to WhatsApp Sender Pro",
+        inputSchema: {
+          type: "object",
+          properties: {
+            phone: {
+              type: "string",
+              description: "Phone number with country code",
+            },
+            name: {
+              type: "string",
+              description: "Contact name",
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Tags for organizing contacts",
+            },
+          },
+          required: ["phone"],
+        },
+      },
+      {
+        name: "import_contacts",
+        description: "Import multiple contacts at once",
+        inputSchema: {
+          type: "object",
+          properties: {
+            contacts: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  phone: { type: "string" },
+                  name: { type: "string" },
+                  tags: { type: "array", items: { type: "string" } },
+                },
+                required: ["phone"],
+              },
+              description: "Array of contacts to import",
+            },
+          },
+          required: ["contacts"],
+        },
+      },
+      {
+        name: "get_message_history",
+        description: "Get message history and delivery status",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Number of messages to retrieve (default: 50)",
+            },
+            status: {
+              type: "string",
+              enum: ["sent", "failed", "pending"],
+              description: "Filter by message status",
+            },
+          },
+        },
+      },
+      {
+        name: "get_credits_balance",
+        description: "Check current credits balance and usage",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "get_analytics",
+        description: "Get messaging analytics and statistics",
+        inputSchema: {
+          type: "object",
+          properties: {
+            period: {
+              type: "string",
+              enum: ["today", "week", "month"],
+              description: "Time period for analytics",
+            },
+          },
+        },
+      },
+      {
+        name: "create_message_template",
+        description: "Create a reusable message template",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Template name",
+            },
+            content: {
+              type: "string",
+              description: "Template content with variables like {name}, {company}",
+            },
+            category: {
+              type: "string",
+              description: "Template category (e.g., 'marketing', 'support')",
+            },
+          },
+          required: ["name", "content"],
+        },
+      },
+      {
+        name: "authenticate",
+        description: "Authenticate with WhatsApp Sender Pro API",
+        inputSchema: {
+          type: "object",
+          properties: {
+            email: {
+              type: "string",
+              description: "Account email",
+            },
+            password: {
+              type: "string",
+              description: "Account password",
+            },
+          },
+          required: ["email", "password"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "authenticate": {
+        const result = await apiCall("/auth/login", "POST", {
+          email: args.email,
+          password: args.password,
+        });
+        API_TOKEN = result.token;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully authenticated! Credits: ${result.user.credits}. You can now use all WhatsApp Sender features.`,
+            },
+          ],
+        };
+      }
+
+      case "send_whatsapp_message": {
+        const result = await apiCall("/messages/send", "POST", {
+          phone: args.phone,
+          message: args.message,
+          contactName: args.contactName || "",
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Message sent successfully to ${args.phone}. Message ID: ${result.messageId}. Credits used: 1.`,
+            },
+          ],
+        };
+      }
+
+      case "send_bulk_messages": {
+        const result = await apiCall("/messages/bulk", "POST", {
+          contacts: args.contacts,
+          message: args.message,
+          minDelay: args.minDelay || 3,
+          maxDelay: args.maxDelay || 8,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Bulk messaging initiated. Sending to ${args.contacts.length} contacts. Campaign ID: ${result.campaignId}. Estimated completion: ${result.estimatedTime}.`,
+            },
+          ],
+        };
+      }
+
+      case "get_contacts": {
+        const params = new URLSearchParams();
+        if (args.limit) params.append("limit", args.limit);
+        if (args.search) params.append("search", args.search);
+
+        const result = await apiCall(`/contacts?${params.toString()}`);
+        const contacts = result.contacts || [];
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${contacts.length} contacts:\n\n${contacts
+                .slice(0, 20)
+                .map((c, i) => `${i + 1}. ${c.name || "Unknown"} - ${c.phone}`)
+                .join("\n")}${contacts.length > 20 ? `\n\n... and ${contacts.length - 20} more` : ""}`,
+            },
+          ],
+        };
+      }
+
+      case "add_contact": {
+        const result = await apiCall("/contacts", "POST", {
+          phone: args.phone,
+          name: args.name || "",
+          tags: args.tags || [],
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Contact added successfully! ID: ${result.contact.id}, Phone: ${args.phone}, Name: ${args.name || "Not specified"}`,
+            },
+          ],
+        };
+      }
+
+      case "import_contacts": {
+        const result = await apiCall("/contacts/import", "POST", {
+          contacts: args.contacts,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Import complete! Added: ${result.added}, Duplicates skipped: ${result.duplicates}, Failed: ${result.failed}`,
+            },
+          ],
+        };
+      }
+
+      case "get_message_history": {
+        const params = new URLSearchParams();
+        if (args.limit) params.append("limit", args.limit);
+        if (args.status) params.append("status", args.status);
+
+        const result = await apiCall(`/messages/history?${params.toString()}`);
+        const messages = result.messages || [];
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Message History (${messages.length} messages):\n\n${messages
+                .slice(0, 10)
+                .map(
+                  (m) =>
+                    `- To: ${m.contact_phone} | Status: ${m.status} | Date: ${new Date(m.sent_at).toLocaleString()}`
+                )
+                .join("\n")}`,
+            },
+          ],
+        };
+      }
+
+      case "get_credits_balance": {
+        const result = await apiCall("/user/profile");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Credits Balance: ${result.user.credits}\nPlan: ${result.user.plan || "Free"}\nEmail: ${result.user.email}`,
+            },
+          ],
+        };
+      }
+
+      case "get_analytics": {
+        const days = args.period === "today" ? 1 : args.period === "week" ? 7 : 30;
+        const result = await apiCall(`/messages/stats?period=${days}`);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Analytics (Last ${args.period || "week"}):\n\nTotal Sent: ${result.totals?.total_sent || 0}\nDelivered: ${result.totals?.total_delivered || 0}\nFailed: ${result.totals?.total_failed || 0}\nCredits Used: ${result.totals?.total_credits_used || 0}`,
+            },
+          ],
+        };
+      }
+
+      case "create_message_template": {
+        const result = await apiCall("/templates", "POST", {
+          name: args.name,
+          content: args.content,
+          category: args.category || "general",
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Template "${args.name}" created successfully! ID: ${result.template.id}`,
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ==================== RESOURCES ====================
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "whatsapp://contacts",
+        mimeType: "application/json",
+        name: "All Contacts",
+        description: "List of all saved contacts in WhatsApp Sender Pro",
+      },
+      {
+        uri: "whatsapp://templates",
+        mimeType: "application/json",
+        name: "Message Templates",
+        description: "Saved message templates for quick sending",
+      },
+      {
+        uri: "whatsapp://stats",
+        mimeType: "application/json",
+        name: "Usage Statistics",
+        description: "Messaging statistics and analytics",
+      },
+      {
+        uri: "whatsapp://account",
+        mimeType: "application/json",
+        name: "Account Info",
+        description: "Current account information and credits balance",
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  try {
+    switch (uri) {
+      case "whatsapp://contacts": {
+        const result = await apiCall("/contacts?limit=1000");
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(result.contacts || [], null, 2),
+            },
+          ],
+        };
+      }
+
+      case "whatsapp://templates": {
+        const result = await apiCall("/templates");
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(result.templates || [], null, 2),
+            },
+          ],
+        };
+      }
+
+      case "whatsapp://stats": {
+        const result = await apiCall("/messages/stats?period=30");
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "whatsapp://account": {
+        const result = await apiCall("/user/profile");
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(result.user, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown resource: ${uri}`);
+    }
+  } catch (error) {
+    throw new Error(`Failed to read resource: ${error.message}`);
+  }
+});
+
+// ==================== PROMPTS ====================
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "send_marketing_campaign",
+        description: "Create and send a marketing campaign to your contacts",
+        arguments: [
+          {
+            name: "product",
+            description: "Product or service to promote",
+            required: true,
+          },
+          {
+            name: "offer",
+            description: "Special offer or discount",
+            required: false,
+          },
+        ],
+      },
+      {
+        name: "send_appointment_reminder",
+        description: "Send appointment reminders to clients",
+        arguments: [
+          {
+            name: "appointment_type",
+            description: "Type of appointment (e.g., 'meeting', 'consultation')",
+            required: true,
+          },
+          {
+            name: "date",
+            description: "Date and time of appointment",
+            required: true,
+          },
+        ],
+      },
+      {
+        name: "customer_followup",
+        description: "Send follow-up messages to customers after purchase",
+        arguments: [
+          {
+            name: "product_purchased",
+            description: "Product that was purchased",
+            required: true,
+          },
+        ],
+      },
+      {
+        name: "event_invitation",
+        description: "Send event invitations via WhatsApp",
+        arguments: [
+          {
+            name: "event_name",
+            description: "Name of the event",
+            required: true,
+          },
+          {
+            name: "event_date",
+            description: "Date and time of the event",
+            required: true,
+          },
+          {
+            name: "location",
+            description: "Event location or link",
+            required: true,
+          },
+        ],
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case "send_marketing_campaign":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Create a WhatsApp marketing campaign for "${args.product}"${args.offer ? ` with offer: "${args.offer}"` : ""}.
+
+Steps:
+1. First, use get_contacts to see my contact list
+2. Create a compelling, personalized message (use {name} for personalization)
+3. Send the campaign using send_bulk_messages with appropriate delays
+
+Make the message friendly, concise, and include a clear call-to-action. Keep it under 500 characters for WhatsApp.`,
+            },
+          },
+        ],
+      };
+
+    case "send_appointment_reminder":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Send appointment reminders for ${args.appointment_type} scheduled on ${args.date}.
+
+Create a professional reminder message that:
+1. Greets the person by name
+2. Confirms the appointment details
+3. Asks for confirmation or rescheduling
+4. Provides contact info for questions
+
+Use the send_whatsapp_message tool to send to specific contacts.`,
+            },
+          },
+        ],
+      };
+
+    case "customer_followup":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Create a follow-up message campaign for customers who purchased "${args.product_purchased}".
+
+The message should:
+1. Thank them for their purchase
+2. Ask if they're satisfied
+3. Offer help if needed
+4. Maybe suggest related products
+
+Use get_contacts first, then send_bulk_messages with personalization.`,
+            },
+          },
+        ],
+      };
+
+    case "event_invitation":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Create WhatsApp invitations for "${args.event_name}" on ${args.event_date} at ${args.location}.
+
+The invitation should:
+1. Be exciting and engaging
+2. Include all event details
+3. Have a clear RSVP request
+4. Mention any special instructions
+
+Get contacts and send personalized invitations using send_bulk_messages.`,
+            },
+          },
+        ],
+      };
+
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("WhatsApp Sender MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});