Wassenger

Enables direct HTTPS/SSE connection from modern MCP clients (Claude Desktop 0.48.0+, VS Code Copilot, OpenAI Responses API) to the Wassenger MCP server at https://api.wassenger.com/mcp without local installation. API key is embedded as URL query parameter and validated on every request, eliminating OAuth complexity for stateless clients. Uses Server-Sent Events (SSE) for bidirectional message streaming over standard HTTPS.

Provides a local Node.js proxy (mcp-wassenger NPX package) that bridges STDIO transport from legacy MCP clients (Cline, Continue) to SSE connection with the Wassenger API. Implements OAuth 2.0 with PKCE flow for secure credential handling, using lockfile-based coordination (src/lib/coordination.ts) to prevent duplicate browser authentication flows when multiple client instances spawn the proxy simultaneously. Parses command-line arguments and manages credential lifecycle.

Automatically generates MCP tool schemas (JSON Schema format) for all Wassenger API operations, with built-in type validation and parameter documentation. Implements schema validation on tool invocation to catch missing or invalid parameters before sending to Wassenger API. Provides TypeScript type definitions for all tool inputs/outputs, enabling IDE autocomplete and compile-time type checking.

Implements comprehensive error handling for Wassenger API failures, including network errors, rate limiting (HTTP 429), and API errors (HTTP 4xx/5xx). Provides automatic retry logic with exponential backoff (initial delay 100ms, max delay 30s) for transient failures, with configurable retry counts. Returns detailed error messages to AI clients, distinguishing between retryable errors (rate limit, timeout) and permanent failures (invalid parameters, authentication).

Provides flexible configuration loading from environment variables, command-line arguments, and configuration files (.env, JSON). Implements secure credential storage with support for API keys, OAuth secrets, and webhook URLs. Validates configuration on startup and provides helpful error messages for missing or invalid settings. Supports configuration inheritance and overrides (CLI args > env vars > config files).

Enables AI clients to send text messages to WhatsApp contacts or groups via the Wassenger API, with built-in recipient validation (phone number format checking, contact existence verification) and delivery status tracking. Implements message queuing to handle rate limits (typically 80 messages/minute per Wassenger account) and provides structured responses indicating success, pending, or failure states. Supports both individual chats and group messaging with automatic recipient type detection.

Provides AI clients with the ability to fetch and analyze WhatsApp conversation history from specific chats or groups, extracting message content, sender metadata, timestamps, and media references. Implements pagination for large conversations (typically 50-100 messages per page) and optional filtering by date range or sender. Returns structured conversation data suitable for RAG (Retrieval-Augmented Generation) pipelines or conversation analysis tasks.

Enables AI clients to create WhatsApp groups, add/remove members, update group metadata (name, description, icon), and manage group permissions. Implements role-based access control (admin vs member) and provides group listing with member counts and metadata. Supports bulk member operations with error handling for invalid phone numbers or permission violations.

Enables AI clients to send pre-approved WhatsApp message templates (stored in Wassenger account) with dynamic variable substitution. Implements template parameter validation (ensuring required variables are provided) and supports both text templates and templates with media (images, documents). Handles template approval status checking and provides fallback to plain text if template is not approved.

Enables AI clients to send WhatsApp messages with media attachments (images, documents, audio, video) by providing publicly accessible URLs. Implements media type validation (MIME type checking), file size verification (WhatsApp limits: images 16MB, videos 100MB, documents 100MB), and URL accessibility checking before sending. Returns media metadata (type, size, URL) in message responses for tracking.

Provides a mechanism for Wassenger to deliver incoming WhatsApp messages and events (message received, delivery confirmation, read receipt) to AI clients via webhooks. Implements event filtering (by message type, sender, or chat), event deduplication using message IDs, and retry logic for failed webhook deliveries. Supports both webhook registration via MCP tools and direct webhook URL configuration in Wassenger dashboard.

Enables AI clients to retrieve and manage WhatsApp contact lists, including phone numbers, display names, and last interaction timestamps. Implements contact filtering (by name, phone number, or interaction date), bulk contact operations (add/remove from groups), and contact metadata updates (custom fields, tags). Provides contact search functionality with fuzzy matching for name-based lookups.

Implements a coordination mechanism (src/lib/coordination.ts 12-143) to prevent duplicate OAuth authentication flows when multiple MCP client instances spawn the mcp-wassenger NPX package simultaneously. Uses filesystem-based lockfiles to track active authentication sessions, allowing subsequent instances to wait for or reuse existing tokens. Handles lock timeout and cleanup to prevent deadlocks.