mcp-evolution 0.0.0-stage → 0.8.1

package/dist/util/normalize.d.ts

@@ -0,0 +1,44 @@
+/** Shared message normalizer — prevents payload overflow from raw Evolution responses. */
+interface RawMessage {
+    key?: {
+        id?: string;
+        fromMe?: boolean;
+        remoteJid?: string;
+    };
+    messageTimestamp?: number;
+    message?: {
+        conversation?: string;
+        extendedTextMessage?: {
+            text?: string;
+        };
+        imageMessage?: {
+            caption?: string;
+        };
+        videoMessage?: {
+            caption?: string;
+        };
+        quotedMessage?: unknown;
+        contextInfo?: {
+            stanzaId?: string;
+        };
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface NormalizedMessage {
+    id: string;
+    fromMe: boolean;
+    remoteJid: string;
+    timestamp: number;
+    type: string;
+    text: string | null;
+    mediaKey?: string;
+    quotedMessageId?: string;
+}
+/** Infer MIME extension — returns e.g. "jpg", "mp4", "ogg". Falls back to "bin". */
+export declare function mimeToExt(mime: string): string;
+/** Normalize a raw Evolution message object to the compact, bounded shape. */
+export declare function normalizeMessage(raw: RawMessage): NormalizedMessage;
+/** Evolution v2 paginates messages under messages.records. */
+export declare function extractMessages(data: unknown): unknown[];
+export {};

package/dist/util/normalize.js

@@ -0,0 +1,68 @@
+/** Shared message normalizer — prevents payload overflow from raw Evolution responses. */
+/** Infer MIME extension — returns e.g. "jpg", "mp4", "ogg". Falls back to "bin". */
+export function mimeToExt(mime) {
+    const map = {
+        "image/jpeg": "jpg",
+        "image/png": "png",
+        "image/gif": "gif",
+        "image/webp": "webp",
+        "video/mp4": "mp4",
+        "video/webm": "webm",
+        "audio/ogg": "ogg",
+        "audio/mpeg": "mp3",
+        "audio/mp4": "m4a",
+        "audio/wav": "wav",
+        "application/pdf": "pdf",
+        "application/zip": "zip",
+    };
+    const sub = mime.split("/")[1]?.replace(/[^a-z0-9]/gi, "");
+    return map[mime] ?? (sub !== undefined && sub.length > 0 ? sub : "bin");
+}
+/** Normalize a raw Evolution message object to the compact, bounded shape. */
+export function normalizeMessage(raw) {
+    const key = raw.key ?? {};
+    const msg = raw.message ?? {};
+    // Detect media types by checking which message type key exists
+    const MEDIA_TYPES = new Set(["imageMessage", "videoMessage", "audioMessage", "documentMessage", "stickerMessage"]);
+    const type = Object.keys(msg).find((k) => k !== "contextInfo") ?? "unknown";
+    const isMedia = MEDIA_TYPES.has(type);
+    // Extract text from whichever message field is present
+    const msgObj = msg[type];
+    const text = msg.conversation ??
+        msg.extendedTextMessage?.text ??
+        (msgObj?.caption) ??
+        null;
+    // Quoted message ID lives in contextInfo.stanzaId
+    const contextInfo = msgObj?.contextInfo
+        ?? msg.contextInfo;
+    const quotedMessageId = contextInfo?.stanzaId;
+    const result = {
+        id: key.id ?? "",
+        fromMe: key.fromMe ?? false,
+        remoteJid: key.remoteJid ?? "",
+        timestamp: raw.messageTimestamp ?? 0,
+        type,
+        text,
+    };
+    // Only attach mediaKey when this is a media message — id doubles as download handle
+    if (isMedia && key.id)
+        result.mediaKey = key.id;
+    if (quotedMessageId)
+        result.quotedMessageId = quotedMessageId;
+    return result;
+}
+/** Evolution v2 paginates messages under messages.records. */
+export function extractMessages(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object" && "messages" in data) {
+        const messages = data.messages;
+        if (Array.isArray(messages))
+            return messages;
+        if (messages && typeof messages === "object" && "records" in messages && Array.isArray(messages.records)) {
+            return messages.records;
+        }
+    }
+    throw new Error("Unsupported Evolution messages response shape");
+}
+//# sourceMappingURL=normalize.js.map

package/dist/util/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/util/normalize.ts"],"names":[],"mappings":"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"}

package/dist/util/redact.d.ts

@@ -0,0 +1,11 @@
+/** Secret redaction for anything that may be returned to the MCP client or logged. */
+export declare const REDACTED = "[REDACTED]";
+export type Redactor = (text: string) => string;
+export interface SecretSources {
+    apiKey?: string;
+    basicAuth?: string;
+    dbUrl?: string;
+    apiUrl?: string;
+}
+/** Build a redactor that masks the API key, Basic Auth (raw and decoded) and URL passwords. */
+export declare function createRedactor(src: SecretSources): Redactor;

package/dist/util/redact.js

@@ -0,0 +1,54 @@
+/** Secret redaction for anything that may be returned to the MCP client or logged. */
+export const REDACTED = "[REDACTED]";
+function urlSecrets(raw) {
+    if (!raw)
+        return [];
+    try {
+        const u = new URL(raw);
+        const out = [];
+        if (u.password)
+            out.push(u.password, decodeURIComponent(u.password));
+        if (u.password || u.username)
+            out.push(`${u.username}:${u.password}@`);
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Build a redactor that masks the API key, Basic Auth (raw and decoded) and URL passwords. */
+export function createRedactor(src) {
+    const secrets = new Set();
+    const add = (s) => {
+        if (!s || s.length < 4)
+            return;
+        secrets.add(s);
+        secrets.add(encodeURIComponent(s));
+    };
+    add(src.apiKey);
+    if (src.basicAuth) {
+        add(src.basicAuth);
+        try {
+            const decoded = Buffer.from(src.basicAuth, "base64").toString("utf8");
+            // Only treat it as credentials if it looks like "user:pass"
+            if (/^[^:\s]+:\S+$/.test(decoded)) {
+                add(decoded);
+                add(decoded.slice(decoded.indexOf(":") + 1));
+            }
+        }
+        catch {
+            /* not base64 — raw value already covered */
+        }
+    }
+    urlSecrets(src.dbUrl).forEach(add);
+    urlSecrets(src.apiUrl).forEach(add);
+    add(src.dbUrl);
+    const ordered = [...secrets].sort((a, b) => b.length - a.length);
+    return (text) => {
+        let out = text;
+        for (const s of ordered)
+            out = out.split(s).join(REDACTED);
+        return out;
+    };
+}
+//# sourceMappingURL=redact.js.map

package/dist/util/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/util/redact.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAWrC,SAAS,UAAU,CAAC,GAAuB;IACzC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,GAAG,GAAG,CAAC,CAAqB,EAAQ,EAAE;QAC1C,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO;QAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChB,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACtE,4DAA4D;YAC5D,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACb,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAEf,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,CAAC,IAAY,EAAU,EAAE;QAC9B,IAAI,GAAG,GAAG,IAAI,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3D,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "mcp-evolution",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "MCP server for Evolution API (WhatsApp) with instance allowlist, tool and recipient guards",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-evolution": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "evolution-api",
+    "whatsapp"
+  ],
+  "author": "Francione Matias Carvalho",
+  "contributors": [
+    {
+      "name": "Billy Franklim",
+      "url": "https://github.com/billyfranklim1"
+    }
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/santificado13/mcp-evolution.git"
+  },
+  "bugs": {
+    "url": "https://github.com/santificado13/mcp-evolution/issues"
+  },
+  "homepage": "https://github.com/santificado13/mcp-evolution#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "pg": "^8.20.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.20.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}