@messegy/mcp 1.0.0

package/dist/web-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-app.js","sourceRoot":"","sources":["../src/web-app.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa;IAC3B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAy0BD,CAAC;AACT,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@messegy/mcp",
+  "version": "1.0.0",
+  "description": "Official Model Context Protocol (MCP) Server for Messegy WhatsApp Business Cloud Platform",
+  "main": "dist/index.js",
+  "bin": {
+    "messegy-mcp": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "server": "node dist/server.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "messegy",
+    "whatsapp",
+    "whatsapp-business-api",
+    "ai-agent",
+    "claude",
+    "cursor"
+  ],
+  "author": "Messegy",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "axios": "^1.7.9",
+    "cors": "^2.8.6",
+    "dotenv": "^16.4.7",
+    "express": "^5.2.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.13.4",
+    "typescript": "^5.7.3"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,112 @@
+import axios, { AxiosError } from 'axios';
+import { getConfig } from './config.js';
+
+export class MessegyApiClient {
+  private getHeaders(): Record<string, string> {
+    const config = getConfig();
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    };
+
+    if (config.apiKey) {
+      headers['Authorization'] = `Bearer ${config.apiKey}`;
+      headers['x-api-key'] = config.apiKey;
+    }
+
+    if (config.projectKey) {
+      headers['x-project-key'] = config.projectKey;
+    }
+
+    return headers;
+  }
+
+  private checkAuth() {
+    const config = getConfig();
+    if (!config.apiKey) {
+      throw new Error(
+        '⚠️ No Messegy account connected! Please provide your Messegy API Key by calling the "messegy_connect_account" tool or by saying: "Connect my Messegy account with API Key <your_key>".'
+      );
+    }
+  }
+
+  async get<T = any>(endpoint: string, params?: Record<string, any>, skipAuthCheck = false): Promise<T> {
+    if (!skipAuthCheck) this.checkAuth();
+    const config = getConfig();
+    try {
+      const response = await axios.get<T>(`${config.baseUrl}${endpoint}`, {
+        params,
+        headers: this.getHeaders(),
+        timeout: 15000,
+      });
+      return response.data;
+    } catch (err) {
+      this.handleError(err, `GET ${endpoint}`);
+    }
+  }
+
+  async post<T = any>(endpoint: string, data?: Record<string, any>, skipAuthCheck = false): Promise<T> {
+    if (!skipAuthCheck) this.checkAuth();
+    const config = getConfig();
+    try {
+      const response = await axios.post<T>(`${config.baseUrl}${endpoint}`, data, {
+        headers: this.getHeaders(),
+        timeout: 15000,
+      });
+      return response.data;
+    } catch (err) {
+      this.handleError(err, `POST ${endpoint}`);
+    }
+  }
+
+  async put<T = any>(endpoint: string, data?: Record<string, any>): Promise<T> {
+    this.checkAuth();
+    const config = getConfig();
+    try {
+      const response = await axios.put<T>(`${config.baseUrl}${endpoint}`, data, {
+        headers: this.getHeaders(),
+        timeout: 15000,
+      });
+      return response.data;
+    } catch (err) {
+      this.handleError(err, `PUT ${endpoint}`);
+    }
+  }
+
+  async delete<T = any>(endpoint: string, params?: Record<string, any>): Promise<T> {
+    this.checkAuth();
+    const config = getConfig();
+    try {
+      const response = await axios.delete<T>(`${config.baseUrl}${endpoint}`, {
+        params,
+        headers: this.getHeaders(),
+        timeout: 15000,
+      });
+      return response.data;
+    } catch (err) {
+      this.handleError(err, `DELETE ${endpoint}`);
+    }
+  }
+
+  private handleError(error: unknown, action: string): never {
+    if (axios.isAxiosError(error)) {
+      const axiosErr = error as AxiosError<any>;
+      const status = axiosErr.response?.status;
+      const responseData = axiosErr.response?.data;
+      const message = responseData?.message || responseData?.error || axiosErr.message;
+
+      if (status === 401 || status === 403) {
+        throw new Error(
+          `🔒 Authentication Failed (Status ${status}): Invalid or expired Messegy API Key. Please reconnect using "messegy_connect_account" with a valid key.`
+        );
+      }
+
+      throw new Error(
+        `Messegy API Error during [${action}]: (Status ${status || 'Unknown'}) ${message}`
+      );
+    }
+    throw new Error(`Messegy Network Error during [${action}]: ${(error as Error).message}`);
+  }
+}
+
+export const api = new MessegyApiClient();

package/src/cli-setup.ts

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import readline from 'readline';
+
+function getClaudeConfigPath(): string {
+  const home = os.homedir();
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else if (process.platform === 'win32') {
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return path.join(appData, 'Claude', 'claude_desktop_config.json');
+  } else {
+    return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+  }
+}
+
+export async function runInteractiveCliSetup() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (query: string): Promise<string> =>
+    new Promise((resolve) => rl.question(query, resolve));
+
+  console.log('\n======================================================');
+  console.log('  🚀 Messegy WhatsApp MCP 1-Click Auto-Setup');
+  console.log('======================================================\n');
+
+  try {
+    const apiKey = (
+      await question('🔑 Enter your Messegy API Key (from Messegy Portal -> Settings): ')
+    ).trim();
+
+    if (!apiKey) {
+      console.log('\n❌ Error: API Key is required. Setup cancelled.\n');
+      rl.close();
+      process.exit(1);
+    }
+
+    const projectKey = (
+      await question('📁 Enter Project Key (Optional, press Enter to skip): ')
+    ).trim();
+
+    const configPath = getClaudeConfigPath();
+    const configDir = path.dirname(configPath);
+
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    let existingConfig: any = {};
+    if (fs.existsSync(configPath)) {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        existingConfig = JSON.parse(raw);
+      } catch {
+        existingConfig = {};
+      }
+    }
+
+    if (!existingConfig.mcpServers) {
+      existingConfig.mcpServers = {};
+    }
+
+    existingConfig.mcpServers.messegy = {
+      command: 'npx',
+      args: ['-y', '@messegy/mcp'],
+      env: {
+        MESSEGY_API_KEY: apiKey,
+        ...(projectKey ? { MESSEGY_PROJECT_KEY: projectKey } : {}),
+      },
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(existingConfig, null, 2), 'utf-8');
+
+    console.log('\n✅ SUCCESS! Messegy MCP Server has been configured automatically.');
+    console.log(`📂 Updated Config: ${configPath}`);
+    console.log('\n👉 Next Step: Open or Restart Claude Desktop, and start chatting with your WhatsApp business!\n');
+  } catch (err: any) {
+    console.error('\n❌ Setup failed:', err.message);
+  } finally {
+    rl.close();
+    process.exit(0);
+  }
+}

package/src/config.ts

@@ -0,0 +1,111 @@
+import dotenv from 'dotenv';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+dotenv.config();
+
+export interface MessegyConfig {
+  apiKey: string;
+  projectKey?: string;
+  baseUrl: string;
+}
+
+const CONFIG_DIR = path.join(os.homedir(), '.messegy');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+// In-memory configuration cache
+let activeConfig: MessegyConfig | null = null;
+
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    try {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    } catch {}
+  }
+}
+
+function loadSavedFileConfig(): Partial<MessegyConfig> | null {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const data = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      return JSON.parse(data);
+    }
+  } catch (err) {
+    console.error('Error reading saved Messegy config:', err);
+  }
+  return null;
+}
+
+export function getConfig(): MessegyConfig {
+  if (activeConfig) {
+    return activeConfig;
+  }
+
+  const fileConfig = loadSavedFileConfig();
+
+  const apiKey =
+    process.env.MESSEGY_API_KEY ||
+    fileConfig?.apiKey ||
+    '';
+
+  const projectKey =
+    process.env.MESSEGY_PROJECT_KEY ||
+    fileConfig?.projectKey ||
+    undefined;
+
+  const baseUrl = (
+    process.env.MESSEGY_BASE_URL ||
+    fileConfig?.baseUrl ||
+    'https://backend.messegy.com/api'
+  ).replace(/\/$/, '');
+
+  activeConfig = {
+    apiKey,
+    projectKey,
+    baseUrl,
+  };
+
+  return activeConfig;
+}
+
+/**
+ * Save new credentials interactively and persist to ~/.messegy/config.json
+ */
+export function saveConfig(newConfig: { apiKey: string; projectKey?: string; baseUrl?: string }): MessegyConfig {
+  ensureConfigDir();
+
+  const updated: MessegyConfig = {
+    apiKey: newConfig.apiKey.trim(),
+    projectKey: newConfig.projectKey?.trim() || undefined,
+    baseUrl: (newConfig.baseUrl || 'https://backend.messegy.com/api').replace(/\/$/, ''),
+  };
+
+  try {
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(updated, null, 2), 'utf-8');
+  } catch (err) {
+    console.error('Failed to write ~/.messegy/config.json:', err);
+  }
+
+  activeConfig = updated;
+  return updated;
+}
+
+/**
+ * Disconnect & remove saved credentials
+ */
+export function clearConfig(): void {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      fs.unlinkSync(CONFIG_FILE);
+    }
+  } catch (err) {
+    console.error('Failed to delete ~/.messegy/config.json:', err);
+  }
+
+  activeConfig = {
+    apiKey: '',
+    projectKey: undefined,
+    baseUrl: 'https://backend.messegy.com/api',
+  };
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { runInteractiveCliSetup } from './cli-setup.js';
+import { startHttpMcpServer } from './server.js';
+import { registerAuthTools } from './tools/auth.js';
+import { registerMessageTools } from './tools/messages.js';
+import { registerTemplateTools } from './tools/templates.js';
+import { registerChatTools } from './tools/chats.js';
+import { registerContactTools } from './tools/contacts.js';
+import { registerBroadcastTools } from './tools/broadcasts.js';
+import { registerAnalyticsTools } from './tools/analytics.js';
+import { registerAutoReplyTools } from './tools/auto-replies.js';
+import { registerFlowTools } from './tools/flows.js';
+import { registerShopifyTools } from './tools/shopify.js';
+import { registerResources } from './resources/index.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('init') || args.includes('--init') || args.includes('setup') || args.includes('--setup')) {
+    await runInteractiveCliSetup();
+    return;
+  }
+
+  if (args.includes('server') || args.includes('--server') || args.includes('--http') || process.env.MESSEGY_MCP_MODE === 'http') {
+    const port = process.env.PORT || 3001;
+    startHttpMcpServer(port);
+    return;
+  }
+
+  // Initialize official Messegy MCP Server
+  const server = new McpServer({
+    name: 'messegy-whatsapp',
+    version: '1.0.0',
+  });
+
+  // Register interactive Auth & Account Switching tools (1st priority)
+  registerAuthTools(server);
+
+  // Register all tool suites
+  registerMessageTools(server);
+  registerTemplateTools(server);
+  registerChatTools(server);
+  registerContactTools(server);
+  registerBroadcastTools(server);
+  registerAutoReplyTools(server);
+  registerFlowTools(server);
+  registerAnalyticsTools(server);
+  registerShopifyTools(server);
+
+  // Register dynamic LLM context resources
+  registerResources(server);
+
+  // Connect via standard input/output transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('🚀 Messegy WhatsApp MCP Server is running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error in Messegy MCP server:', error);
+  process.exit(1);
+});

package/src/lib/quota-guard.ts

@@ -0,0 +1,138 @@
+import { api } from '../api-client.js';
+
+export interface PlanUsageInfo {
+  planName: string;
+  status: string;
+  messagesRemaining: number;
+  dailyTierLimit: number;
+  maxAutoReplies: number;
+  currentAutoReplies: number;
+  maxFlows: number;
+  currentFlows: number;
+  isTrial: boolean;
+  trialDaysLeft?: number;
+  expiresAt?: string;
+}
+
+let cachedUsage: { data: PlanUsageInfo; timestamp: number } | null = null;
+const CACHE_TTL_MS = 30000; // 30 seconds cache to keep tools fast
+
+export async function fetchCurrentPlanUsage(forceRefresh = false): Promise<PlanUsageInfo> {
+  const now = Date.now();
+  if (!forceRefresh && cachedUsage && now - cachedUsage.timestamp < CACHE_TTL_MS) {
+    return cachedUsage.data;
+  }
+
+  try {
+    const [planRes, dashRes] = await Promise.all([
+      api.get('/billing/my-plan').catch(() => null),
+      api.get('/dashboard').catch(() => null),
+    ]);
+
+    const plan = planRes?.data?.plan || planRes?.plan || planRes?.data || {};
+    const dash = dashRes?.data || dashRes || {};
+    const meta = dash?.meta || {};
+    const stats = dash?.stats || {};
+
+    const planName = plan?.name || meta?.plan_name || 'Starter Plan';
+    const isTrial = Boolean(dash?.trial_days_left && dash.trial_days_left > 0);
+
+    const usage: PlanUsageInfo = {
+      planName,
+      status: plan?.status || 'active',
+      messagesRemaining: typeof stats?.messages_remaining === 'number' ? stats.messages_remaining : (plan?.message_limit ?? 1000),
+      dailyTierLimit: parseTierLimit(meta?.throughput || meta?.tier),
+      maxAutoReplies: plan?.max_auto_replies ?? (planName.toLowerCase().includes('enterprise') ? 9999 : planName.toLowerCase().includes('pro') ? 50 : 5),
+      currentAutoReplies: typeof stats?.active_auto_replies === 'number' ? stats.active_auto_replies : 0,
+      maxFlows: plan?.max_flows ?? (planName.toLowerCase().includes('enterprise') ? 9999 : planName.toLowerCase().includes('pro') ? 20 : 2),
+      currentFlows: typeof stats?.active_flows === 'number' ? stats.active_flows : 0,
+      isTrial,
+      trialDaysLeft: dash?.trial_days_left,
+      expiresAt: plan?.expires_at || plan?.renewal_date,
+    };
+
+    cachedUsage = { data: usage, timestamp: now };
+    return usage;
+  } catch (err: any) {
+    // Fallback safe limits if billing API is unreachable
+    return {
+      planName: 'Standard Plan',
+      status: 'active',
+      messagesRemaining: 500,
+      dailyTierLimit: 1000,
+      maxAutoReplies: 10,
+      currentAutoReplies: 0,
+      maxFlows: 5,
+      currentFlows: 0,
+      isTrial: false,
+    };
+  }
+}
+
+function parseTierLimit(throughputOrTier: any): number {
+  if (typeof throughputOrTier === 'number') return throughputOrTier;
+  const str = String(throughputOrTier || '').toLowerCase();
+  if (str.includes('100k') || str.includes('tier 3')) return 100000;
+  if (str.includes('10k') || str.includes('tier 2')) return 10000;
+  if (str.includes('1k') || str.includes('tier 1')) return 1000;
+  return 1000; // default Meta tier 1
+}
+
+/**
+ * Validates requested action against plan quotas before executing.
+ * Throws friendly user error if limit exceeded.
+ */
+export async function enforcePlanQuota(
+  action: 'send_message' | 'send_broadcast' | 'create_auto_reply' | 'create_flow',
+  quantity = 1
+): Promise<void> {
+  const usage = await fetchCurrentPlanUsage();
+
+  // Check if account status is active
+  if (usage.status.toLowerCase() === 'expired' || usage.status.toLowerCase() === 'suspended') {
+    throw new Error(
+      `🚫 Action Blocked: Your Messegy subscription [${usage.planName}] is currently ${usage.status.toUpperCase()}. Please renew your plan on the Messegy Billing portal.`
+    );
+  }
+
+  // 1. Message sending check
+  if (action === 'send_message') {
+    if (usage.messagesRemaining <= 0) {
+      throw new Error(
+        `🚫 Message Limit Reached: You have 0 messages remaining on your [${usage.planName}]. Please top up message credits on Messegy Dashboard.`
+      );
+    }
+  }
+
+  // 2. Broadcast bulk recipient check
+  if (action === 'send_broadcast') {
+    if (quantity > usage.messagesRemaining) {
+      throw new Error(
+        `🚫 Broadcast Quota Exceeded: You are trying to send ${quantity} messages, but your current plan [${usage.planName}] only has ${usage.messagesRemaining} credits remaining. Please reduce recipient count or purchase additional credits.`
+      );
+    }
+    if (quantity > usage.dailyTierLimit) {
+      throw new Error(
+        `⚠️ Meta Daily Tier Limit Warning: Your current WhatsApp number tier allows max ${usage.dailyTierLimit.toLocaleString()} messages/day. Batch size ${quantity} exceeds this limit.`
+      );
+    }
+  }
+
+  // 3. Auto-reply rule limit check
+  if (action === 'create_auto_reply') {
+    if (usage.currentAutoReplies >= usage.maxAutoReplies) {
+      throw new Error(
+        `🚫 Auto-Reply Rule Limit Reached: Your [${usage.planName}] allows a maximum of ${usage.maxAutoReplies} automated rules (${usage.currentAutoReplies}/${usage.maxAutoReplies} used). Please upgrade your plan or delete unused rules.`
+      );
+    }
+  }
+
+  // 4. WhatsApp Flow creation limit check
+  if (action === 'create_flow') {
+    if (usage.currentFlows >= usage.maxFlows) {
+      throw new Error(
+        `🚫 WhatsApp Flow Limit Reached: Your [${usage.planName}] allows a maximum of ${usage.maxFlows} active flows (${usage.currentFlows}/${usage.maxFlows} used). Please upgrade your plan on Messegy Dashboard to create more flows.`
+      );
+    }
+  }
+}

package/src/resources/index.ts

@@ -0,0 +1,70 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { api } from '../api-client.js';
+
+export function registerResources(server: McpServer) {
+  /**
+   * Resource 1: Approved WhatsApp Templates Context
+   */
+  server.resource(
+    'messegy-templates',
+    'messegy://templates',
+    async (uri) => {
+      try {
+        const res = await api.get('/v1/templates', { status: 'APPROVED' });
+        const templates = res.data || res.templates || res;
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify(templates, null, 2),
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'text/plain',
+              text: `Failed to fetch active templates: ${err.message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  /**
+   * Resource 2: WhatsApp Account & Phone Health
+   */
+  server.resource(
+    'messegy-account',
+    'messegy://account-status',
+    async (uri) => {
+      try {
+        const res = await api.get('/dashboard');
+        const data = res.data || res;
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify(data, null, 2),
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'text/plain',
+              text: `Failed to fetch account status: ${err.message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+}