@iflow-mcp/mmarqueti-whatsapp-mcp 1.0.0

package/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+RUN npm install -g pnpm
+
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install
+
+COPY . .
+RUN pnpm run build
+
+EXPOSE 4000
+
+CMD ["pnpm", "start"]

package/README.md

@@ -0,0 +1,220 @@
+# WhatsApp Cloud API MCP Server – Spec v1.0
+
+## Overview
+This project defines version **1.0** of an **MCP Server** that exposes the **WhatsApp Cloud API** to LLM agents through standardized MCP tools.
+
+Goal: Provide a minimal, clean, production-ready baseline so developers can use WhatsApp messaging inside AI agents with zero complexity.
+
+---
+
+# 1. Objectives
+
+- Create a lightweight MCP server (TypeScript + Node.js).
+- Expose WhatsApp Cloud API functionalities as tools.
+- Provide helpers for webhook verification.
+- Be deployable with a single command (Docker + local dev).
+
+---
+
+# 2. Tech Stack
+
+- **Node.js 20+**
+- **TypeScript**
+- **Express** (or Fastify) for HTTP + webhooks
+- **MCP Server SDK**
+- **Axios** for outbound WhatsApp API requests
+- **WebSocket** for MCP transport (mandatory)
+- **Dotenv** for configs
+- **Pino** or console logging
+
+---
+
+# 3. Project Structure (v1.0)
+
+```
+/src
+  /mcp
+    server.ts
+  /whatsapp
+    client.ts
+    webhook.ts
+  /config
+    env.ts
+  index.ts
+.env.example
+mcp.json
+package.json
+README.md
+```
+
+---
+
+# 4. Environment Variables
+
+Required:
+
+```
+META_WHATSAPP_TOKEN=
+META_WHATSAPP_PHONE_ID=
+META_WHATSAPP_WABA_ID=
+META_VERIFY_TOKEN=
+PORT=4000
+MCP_PORT=8000
+```
+
+Optional:
+
+```
+LOG_LEVEL=debug
+```
+
+---
+
+# 5. WhatsApp Cloud API Endpoints to Support (v1.0)
+
+The MCP server will call these official endpoints:
+
+### **Send Text Message**
+```
+POST /v18.0/{PHONE_ID}/messages
+```
+
+### **Send Template Message**
+```
+POST /v18.0/{PHONE_ID}/messages
+```
+
+### **Get Media URL**
+```
+GET /v18.0/{MEDIA_ID}
+```
+
+### **Download Media**
+```
+GET {MEDIA_URL}
+```
+
+### **Health Check**
+```
+GET /v18.0/{PHONE_ID}
+```
+
+---
+
+# 6. Webhook Handling
+
+Expose:
+```
+GET  /webhook (verification)
+```
+
+Features:
+- Validate `hub.verify_token`
+
+---
+
+# 7. MCP Tools (v1.0)
+
+Tools exposed to agents:
+
+## **1. send_text_message**
+Send a simple text message to a WhatsApp user.
+
+### Params:
+```json
+{
+  "to": "string",
+  "text": "string"
+}
+```
+
+## **2. send_template_message**
+Send a WhatsApp template message.
+
+### Params:
+```json
+{
+  "to": "string",
+  "template_name": "string",
+  "language": "string",
+  "components": []
+}
+```
+
+## **3. get_media**
+Retrieve a media file by MEDIA_ID.
+
+### Params:
+```json
+{
+  "media_id": "string"
+}
+```
+
+## **4. health_check**
+Verify connectivity with WhatsApp Cloud API.
+
+---
+
+# 8. Security
+
+- Validate Meta webhook signature (optional v1).
+- Restrict MCP tool usage to authenticated WebSocket clients.
+- Sanitize user inputs.
+- Never log tokens.
+
+---
+
+# 9. Documentation Requirements
+
+## Setup Instructions
+
+1. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Configure Environment**
+   Copy `.env.example` to `.env` and fill in your Meta WhatsApp API credentials.
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Run Locally**
+   ```bash
+   npm run dev
+   ```
+   Server will start on port 4000 (HTTP) and expose MCP on WebSocket.
+
+4. **Configure Webhook**
+   - Expose your local server using ngrok or similar: `ngrok http 4000`
+   - In Meta App Dashboard, set Webhook URL to `https://<your-ngrok-url>/webhook`
+   - Set Verify Token to match `META_VERIFY_TOKEN` in `.env`
+
+## Docker Usage
+
+```bash
+docker build -t whatsapp-mcp .
+docker run -p 4000:4000 --env-file .env whatsapp-mcp
+```
+
+## Example Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "whatsapp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "whatsapp-mcp"]
+    }
+  }
+}
+```
+(Note: For local dev without docker, point to the build output)
+
+# 10. Contact
+
+For any inquiries or similar projects, please contact: marcelo@marcelomarchetti.com
+  

package/dist/config/env.js

@@ -0,0 +1,25 @@
+import dotenv from 'dotenv';
+import { z } from 'zod';
+// Suppress dotenv debug output by not logging to console
+dotenv.config({ quiet: true });
+const envSchema = z.object({
+    META_WHATSAPP_TOKEN: z.string().default('test_token'),
+    META_WHATSAPP_PHONE_ID: z.string().default('test_phone_id'),
+    META_WHATSAPP_WABA_ID: z.string().default('test_waba_id'),
+    META_VERIFY_TOKEN: z.string().default('test_verify_token'),
+    PORT: z.string().default('4000'),
+    MCP_PORT: z.string().default('8000'),
+    LOG_LEVEL: z.string().default('info'),
+});
+const parseEnv = () => {
+    try {
+        return envSchema.parse(process.env);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            console.error('❌ Invalid environment variables:', error.flatten().fieldErrors);
+        }
+        process.exit(1);
+    }
+};
+export const config = parseEnv();

package/dist/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import express from 'express';
+import { createServer } from 'http';
+import { config } from './config/env.js';
+import { webhookRouter } from './whatsapp/webhook.js';
+import { mcpServer } from './mcp/server.js';
+// Start servers
+async function main() {
+    try {
+        const args = process.argv.slice(2);
+        const useStdio = args.includes('--stdio');
+        if (useStdio) {
+            // Start MCP Server (Stdio) only - no HTTP server needed
+            await mcpServer.startStdio();
+        }
+        else {
+            // Setup HTTP server for WebSocket mode
+            const app = express();
+            const httpServer = createServer(app);
+            // Middleware
+            app.use(express.json());
+            // Routes
+            app.use('/webhook', webhookRouter);
+            // Health check
+            app.get('/health', (req, res) => {
+                res.status(200).json({ status: 'ok' });
+            });
+            // Start MCP Server (WebSocket)
+            await mcpServer.start(httpServer);
+            // Start HTTP Server
+            httpServer.listen(config.PORT, () => {
+                console.error(`🚀 Server running on port ${config.PORT}`);
+                console.error(`webhook: http://localhost:${config.PORT}/webhook`);
+                console.error(`mcp: ws://localhost:${config.PORT}`);
+            });
+        }
+    }
+    catch (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/mcp/server.js

@@ -0,0 +1,104 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebSocketServer } from 'ws';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { whatsAppClient } from '../whatsapp/client.js';
+class WhatsAppMcpServer {
+    server;
+    wss = null;
+    constructor() {
+        this.server = new McpServer({
+            name: 'WhatsApp MCP Server',
+            version: '1.0.0',
+        });
+        this.registerTools();
+    }
+    registerTools() {
+        this.server.tool('send_text_message', {
+            to: z.string().describe('The WhatsApp phone number to send the message to'),
+            text: z.string().describe('The text content of the message'),
+        }, async ({ to, text }) => {
+            const result = await whatsAppClient.sendText(to, text);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+            };
+        });
+        this.server.tool('send_template_message', {
+            to: z.string().describe('The WhatsApp phone number'),
+            template_name: z.string().describe('Name of the template'),
+            language: z.string().describe('Language code (e.g., en_US)'),
+            components: z.array(z.any()).optional().describe('Template components'),
+        }, async ({ to, template_name, language, components }) => {
+            const result = await whatsAppClient.sendTemplate(to, template_name, language, components);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+            };
+        });
+        this.server.tool('get_media', {
+            media_id: z.string().describe('The ID of the media to retrieve'),
+        }, async ({ media_id }) => {
+            const url = await whatsAppClient.getMediaUrl(media_id);
+            return {
+                content: [{ type: 'text', text: url }],
+            };
+        });
+        this.server.tool('health_check', {}, async () => {
+            const isHealthy = await whatsAppClient.healthCheck();
+            return {
+                content: [{ type: 'text', text: isHealthy ? 'healthy' : 'unhealthy' }],
+                isError: !isHealthy,
+            };
+        });
+    }
+    async start(httpServer) {
+        this.wss = new WebSocketServer({ server: httpServer });
+        this.wss.on('connection', async (ws) => {
+            console.error('New MCP WebSocket connection');
+            // Minimal Transport implementation for WebSocket
+            const transport = {
+                start: async () => { },
+                send: async (message) => {
+                    if (ws.readyState === ws.OPEN) {
+                        ws.send(JSON.stringify(message));
+                    }
+                },
+                close: async () => {
+                    ws.close();
+                },
+                onclose: undefined,
+                onerror: undefined,
+                onmessage: undefined,
+            };
+            ws.on('message', (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    if (transport.onmessage) {
+                        transport.onmessage(message);
+                    }
+                }
+                catch (error) {
+                    console.error('Failed to parse message:', error);
+                }
+            });
+            ws.on('close', () => {
+                if (transport.onclose) {
+                    transport.onclose();
+                }
+            });
+            ws.on('error', (error) => {
+                console.error('WebSocket error:', error);
+                if (transport.onerror) {
+                    transport.onerror(error);
+                }
+            });
+            // @ts-ignore - McpServer.connect expects a Transport interface which matches our object structure
+            await this.server.connect(transport);
+        });
+    }
+    async startStdio() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('MCP Server running on stdio');
+    }
+}
+export const mcpServer = new WhatsAppMcpServer();

package/dist/whatsapp/__tests__/webhook.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import request from 'supertest';
+import express from 'express';
+import { webhookRouter } from '../webhook.js';
+// Mock config
+vi.mock('../../config/env.js', () => ({
+    config: {
+        META_VERIFY_TOKEN: 'test-token',
+        META_WHATSAPP_TOKEN: 'test-token',
+        META_WHATSAPP_PHONE_ID: 'test-phone-id',
+        PORT: 4000
+    }
+}));
+const app = express();
+app.use(express.json());
+app.use('/webhook', webhookRouter);
+describe('Webhook Integration', () => {
+    beforeEach(() => {
+        // Clear storage before each test
+        // We need to access the private array or just add a clear method to storage
+        // For now, we can just assume it works or add a clear method if needed.
+        // But since we are testing ingestion, we can just check if count increases.
+    });
+    describe('GET /webhook', () => {
+        it('should verify token correctly', async () => {
+            const response = await request(app)
+                .get('/webhook')
+                .query({
+                'hub.mode': 'subscribe',
+                'hub.verify_token': 'test-token',
+                'hub.challenge': '12345'
+            });
+            expect(response.status).toBe(200);
+            expect(response.text).toBe('12345');
+        });
+        it('should reject invalid token', async () => {
+            const response = await request(app)
+                .get('/webhook')
+                .query({
+                'hub.mode': 'subscribe',
+                'hub.verify_token': 'wrong-token',
+                'hub.challenge': '12345'
+            });
+            expect(response.status).toBe(403);
+        });
+        it('should reject missing params', async () => {
+            const response = await request(app)
+                .get('/webhook');
+            expect(response.status).toBe(400);
+        });
+    });
+});

package/dist/whatsapp/client.js

@@ -0,0 +1,111 @@
+import axios from 'axios';
+import { config } from '../config/env.js';
+// Mock mode for testing without real API credentials
+const isMockMode = !process.env.META_WHATSAPP_TOKEN ||
+    process.env.META_WHATSAPP_TOKEN === 'test_token' ||
+    !process.env.META_WHATSAPP_PHONE_ID;
+export class WhatsAppClient {
+    client;
+    constructor() {
+        if (isMockMode) {
+            // Create mock client that doesn't make real API calls
+            this.client = {
+                get: async (url, config) => {
+                    console.error(`[MOCK] GET request to ${url}`);
+                    if (url.includes('PHONE_ID')) {
+                        return { data: { id: 'mock_phone_id' } };
+                    }
+                    if (url.match(/^[0-9]+$/)) {
+                        return { data: { url: 'https://mock.media.url/file.pdf' } };
+                    }
+                    return { data: {} };
+                },
+                post: async (url, data, config) => {
+                    console.error(`[MOCK] POST request to ${url}`, data);
+                    return { data: { success: true, message: 'Mock response' } };
+                }
+            };
+        }
+        else {
+            this.client = axios.create({
+                baseURL: 'https://graph.facebook.com/v18.0',
+                headers: {
+                    'Authorization': `Bearer ${config.META_WHATSAPP_TOKEN}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+        }
+    }
+    async sendText(to, text) {
+        try {
+            const response = await this.client.post(`/${config.META_WHATSAPP_PHONE_ID}/messages`, {
+                messaging_product: 'whatsapp',
+                recipient_type: 'individual',
+                to,
+                type: 'text',
+                text: { body: text },
+            });
+            return response.data;
+        }
+        catch (error) {
+            console.error('Error sending text message:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+    async sendTemplate(to, templateName, language, components = []) {
+        try {
+            const response = await this.client.post(`/${config.META_WHATSAPP_PHONE_ID}/messages`, {
+                messaging_product: 'whatsapp',
+                recipient_type: 'individual',
+                to,
+                type: 'template',
+                template: {
+                    name: templateName,
+                    language: { code: language },
+                    components,
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            console.error('Error sending template message:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+    async getMediaUrl(mediaId) {
+        try {
+            const response = await this.client.get(`/${mediaId}`);
+            return response.data.url;
+        }
+        catch (error) {
+            console.error('Error getting media URL:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+    async downloadMedia(url) {
+        try {
+            const response = await this.client.get(url, {
+                responseType: 'arraybuffer',
+                headers: {
+                    'Authorization': `Bearer ${config.META_WHATSAPP_TOKEN}`,
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            console.error('Error downloading media:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+    async healthCheck() {
+        try {
+            await this.client.get(`/${config.META_WHATSAPP_PHONE_ID}`);
+            return true;
+        }
+        catch (error) {
+            console.error('Health check failed:', error.response?.data || error.message);
+            return false;
+        }
+    }
+}
+export const whatsAppClient = new WhatsAppClient();

package/dist/whatsapp/normalize.js

@@ -0,0 +1,47 @@
+export function normalizeMessage(webhookPayload) {
+    try {
+        const entry = webhookPayload.entry?.[0];
+        const change = entry?.changes?.[0];
+        const value = change?.value;
+        const message = value?.messages?.[0];
+        if (!message) {
+            return null;
+        }
+        const normalized = {
+            from: message.from,
+            id: message.id,
+            timestamp: parseInt(message.timestamp, 10),
+            type: 'unknown',
+            raw: message,
+        };
+        switch (message.type) {
+            case 'text':
+                normalized.type = 'text';
+                normalized.text = message.text.body;
+                break;
+            case 'image':
+                normalized.type = 'image';
+                normalized.image = message.image;
+                break;
+            case 'audio':
+                normalized.type = 'audio';
+                normalized.audio = message.audio;
+                break;
+            case 'document':
+                normalized.type = 'document';
+                normalized.document = message.document;
+                break;
+            case 'interactive':
+                normalized.type = 'interactive';
+                normalized.interactive = message.interactive;
+                break;
+            default:
+                normalized.type = 'unknown';
+        }
+        return normalized;
+    }
+    catch (error) {
+        console.error('Error normalizing message:', error);
+        return null;
+    }
+}

package/dist/whatsapp/storage.js

@@ -0,0 +1,17 @@
+export class MessageStorage {
+    messages = [];
+    limit;
+    constructor(limit = 50) {
+        this.limit = limit;
+    }
+    addMessage(message) {
+        this.messages.unshift(message);
+        if (this.messages.length > this.limit) {
+            this.messages.pop();
+        }
+    }
+    getRecentMessages(limit = 20) {
+        return this.messages.slice(0, limit);
+    }
+}
+export const messageStorage = new MessageStorage();

package/dist/whatsapp/webhook.js

@@ -0,0 +1,22 @@
+import express from 'express';
+import { config } from '../config/env.js';
+const router = express.Router();
+// Verification endpoint
+router.get('/', (req, res) => {
+    const mode = req.query['hub.mode'];
+    const token = req.query['hub.verify_token'];
+    const challenge = req.query['hub.challenge'];
+    if (mode && token) {
+        if (mode === 'subscribe' && token === config.META_VERIFY_TOKEN) {
+            console.log('WEBHOOK_VERIFIED');
+            res.status(200).send(challenge);
+        }
+        else {
+            res.sendStatus(403);
+        }
+    }
+    else {
+        res.sendStatus(400);
+    }
+});
+export const webhookRouter = router;